# Magic Portfolio for MDX project, blog and CV sites > Magic Portfolio is a Next.js and Once UI template for publishing a personal portfolio through configuration, MDX files and reusable content sections. It suits noncommercial portfolios, but its custom license and dependency changes require attention before adoption. **once-ui-system/magic-portfolio** — ⚡ Build your timeless portfolio with Once UI's Magic Portfolio - Repository: https://github.com/once-ui-system/magic-portfolio - Website: https://magic-portfolio.com - Stars: 1,416 · Forks: 937 - Language: TypeScript - License: NOASSERTION - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/once-ui-system-magic-portfolio ## The portfolio structure Magic Portfolio puts in place Magic Portfolio addresses a specific editorial problem: a developer or designer needs more than a static introduction page, but does not want to build and maintain a full Next.js site from scratch. The repository provides project case studies, blog posts, an about or CV page and a gallery. Those pages can be enabled conditionally from a central content file, while social links can be generated from the same configuration. This makes it suitable for a personal site that must present both professional history and written work. The intended audience is clear from the content model. Projects are separate MDX documents under `src/app/work/projects`, while posts live under `src/app/blog/posts`. Global navigation, page availability and shared profile data belong in JavaScript resource files rather than inside each article. Once UI supplies the component and token system, and Next.js handles the application structure. The result is closer to an editable publishing starter than a general-purpose portfolio service. That focus creates a boundary. The repository does not present a dashboard, database-backed editor or multi-author workflow. Content changes still depend on files in the repository and a deployment process. The README points to Aveiro as a managed publishing option and says case studies, blog posts and content can be updated through MCP from AI tools, but the core repository tutorial remains file-based. Engineers who need a visual content editor should treat the hosted platform as a separate adoption decision rather than assume it is part of the open-source template. ## MDX articles, resource files and the Next.js data flow The repository uses Next.js, React and TypeScript tooling, with MDX handling for written content. The package dependencies include `@next/mdx`, `next-mdx-remote`, `gray-matter` and `@mdx-js/loader`. Based on the documented file layout, a project or article is added as an `.mdx` file in its corresponding directory, while site-wide settings are separated into `src/resources/once-ui.config.js` and `src/resources/content.js`. This separation limits repeated edits. Site-level choices, page visibility and shared information can be handled in the resource files. Individual work samples and posts remain independent documents that can be added without changing every page. The README states that sections render conditionally from the content file, so the blog, work, gallery and about or CV areas can be enabled or disabled rather than treated as permanent parts of the site. Metadata is derived from content rather than maintained as a separate SEO configuration in the documented setup. The README identifies automatic schema and metadata generation based on the content file. It also documents automatic open-graph and X image generation with `next/og`. These features reduce the amount of manual page-level SEO plumbing, although the README does not document the exact schema fields or a rollback procedure for generated metadata. The content model also supports password protection for URLs through `PAGE_ACCESS_PASSWORD`. The `.env.example` says that no environment variables are currently required to run the project, while listing this password as the option for protected pages and routes. That distinction matters for deployment planning. A public portfolio needs no environment variable according to the example file, but protected content introduces a configuration step whose runtime behavior should be checked in the chosen deployment environment. ## Installing Magic Portfolio and running the first local use The documented setup starts with a clone, dependency installation and the development server. The project requires Node.js v18.17 or newer. These commands come directly from the README and should be run in the repository directory. The development command starts the Next.js development server, after which the local output should include the starter portfolio pages and any content enabled in `src/resources/content.js`. Clone the repository: ```bash git clone https://github.com/once-ui-system/magic-portfolio.git ``` Install the package dependencies: ```bash npm install ``` Start the local Next.js server: ```bash npm run dev ``` The first meaningful customization is not a component edit. The README identifies `src/resources/once-ui.config.js` as the configuration file for the site and `src/resources/content.js` as the central content file. The latter controls sections and shared portfolio content. A new case study or blog post is created by adding an `.mdx` file under `src/app/blog/posts` or `src/app/work/projects`. For a first real use, replace the starter content with one actual project, then enable only the pages needed for that public profile. The repository includes `public/images/og/home.jpg`, and the README says that social and open-graph images are generated. After changing content, the developer should check the relevant project route, blog route, about or CV route and gallery route. The README does not give a route naming convention for every MDX document, so the exact URL should be taken from the existing files rather than inferred from the directory name. ## Once UI customization and responsive presentation Once UI is the primary design abstraction. The README lists the Once UI tokens, components and features as included, and points to data attributes for customization. This is useful for engineers who want to alter spacing, colors, typography or component appearance without replacing the entire page structure, but it also means the implementation is coupled to Once UI conventions. A developer unfamiliar with data attributes will need to consult the linked Once UI documentation rather than infer behavior from ordinary CSS alone. The stated visual approach is intentionally restrained. The README describes a timeless design with limited heavy animation and motion, and says the layout is responsive across screen sizes. That is a reasonable starting point for a personal portfolio where content and readability matter more than an elaborate front-end effect. It does not mean every screen size has been formally verified for a particular customization. Once images, long project titles or expanded CV content are added, layout checks remain part of the work. The repository also includes Sass as a dependency and has configuration files such as `next.config.mjs`, `tsconfig.json`, `biome.json` and `.eslintrc.json`. This gives the project a recognizable Next.js development structure, but it does not turn it into a fully opinionated design system for an organization. Teams wanting a company-specific component library will need to decide how much of Once UI to retain and where project-specific code should live. ## License constraints for personal and commercial portfolios The README identifies the license as CC BY-NC 4.0 and summarizes its practical conditions: attribution is required and commercial usage is not allowed. It also says the license can be extended to Dopler CC by purchasing an Once UI Pro license. The repository contains `LICENSE` at the top level, while the README refers to `LICENSE.txt`; that naming difference should be checked in the repository before distribution. The restriction is material for adoption. A personal portfolio for a developer or designer can fit the stated noncommercial use, subject to the license terms and attribution requirements. A company portfolio, paid client deliverable, recruitment site or agency template may raise a different licensing question. The README does not provide legal advice or define every possible commercial scenario, so it cannot settle those cases. Procurement or legal review should use the actual license file rather than relying only on the README summary. The README also links to a Vercel deployment flow, but deployment convenience does not change the stated license terms. Before publishing a fork or using the template for a business, verify which assets are included, how attribution appears, and whether the selected Once UI license covers the intended use. The repository's `LICENSE` is the primary file to inspect for the exact terms. ## Maintenance status, dependency upgrades and the Vercel path The repository is not archived, and its last push was on 2026-08-08. The listed releases are v1.3.0 from 2025-01-12, v1.2.0 from 2024-11-08 and v1.1.0 from 2024-10-15. The package manifest currently declares version 2.3.0, so the release list and the package version are not identical in the repository metadata. An adopter should inspect tags, package history and the current branch before assuming that a release tag represents the checked-out code. The dependency list uses broad ranges for several packages, including `latest` for `@once-ui-system/core`. That can make a fresh `npm install` resolve differently from an older installation or deployment. The lockfile is present, so retaining it during initial setup is the safer path for reproducibility. The repository also includes lint and formatting scripts such as `npm run lint` and `npm run biome-write`, but the README does not provide a project-specific upgrade procedure. Vercel deployment is documented through a repository-specific clone link. That gives a direct route for a Next.js deployment, but the README does not document environment setup, custom domains, protected-page configuration or post-deployment validation. Password-protected pages depend on `PAGE_ACCESS_PASSWORD`, while the example file says other variables are not required. Those details must be configured and verified in the selected hosting environment rather than assumed from the local tutorial. ## When Magic Portfolio is the wrong tool Magic Portfolio is a poor fit for a site whose primary requirement is nontechnical publishing without a managed service. Adding an article means creating an `.mdx` file and arranging shared configuration, so editors who cannot work in a repository will need another process. The mention of Aveiro may address that need for some users, but it is an external platform and should not be treated as an offline feature of the template. It is also a poor fit when commercial use is required under the documented CC BY-NC 4.0 terms, unless the required extended license is obtained and its conditions are understood. A team looking for a reusable organization-wide design system, authenticated multi-user workflow or database-backed content model will also find that the documented feature set is narrower than those requirements. Finally, the project is not a minimal static theme. Its MDX pipeline, Once UI dependency, image generation and configurable page model add more moving parts than a hand-written HTML portfolio. A simple one-page site may not justify that setup. The decision should be based on the need for projects, posts, CV content and structured metadata rather than on the visual slogan in the README. ## Conclusion Developers, designers and other professionals should adopt Magic Portfolio when they want an editable Next.js portfolio with MDX content and do not need commercial use. Organizations, agencies and commercial template buyers should resolve the CC BY-NC 4.0 restriction before using it. Verify first that the desired pages and social links work with the content structure in `src/resources/content.js`, that existing MDX files compile under the installed dependencies, and that the planned deployment satisfies the license. ## FAQ ### How do I install and run Magic Portfolio locally? Clone the repository, install dependencies with `npm install`, and run `npm run dev`. The README requires Node.js v18.17 or newer. ### Where do I add a project or blog post in Magic Portfolio? Add an `.mdx` file to `src/app/work/projects` for a project or `src/app/blog/posts` for a blog post. Shared content and page configuration are edited through `src/resources/content.js` and `src/resources/once-ui.config.js`. ### Can I use Magic Portfolio for a commercial website? The README states that CC BY-NC 4.0 requires attribution and does not allow commercial usage. It mentions extending the license to Dopler CC by purchasing an Once UI Pro license, so commercial users should inspect the repository license before proceeding. ## Sources - [Issues](https://github.com/once-ui-system/magic-portfolio/issues) - [once-ui-system/magic-portfolio on GitHub](https://github.com/once-ui-system/magic-portfolio) - [Project website](https://magic-portfolio.com) - [README](https://github.com/once-ui-system/magic-portfolio/blob/main/README.md) - [Releases](https://github.com/once-ui-system/magic-portfolio/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/once-ui-system-magic-portfolio