How once-ui-system/magic-portfolio works
Project type and purpose
• This is a full-stack, Next.js-based portfolio/CMS-style application that uses SSG/SSR along with dynamic API routes for lightweight serverless behavior.
• It ships a custom UI library (Once UI) alongside client pages, MDX-driven content (blog & projects), API routes (authentication, OG generation, sitemap), and static assets.
File structure
• Top-level “public/” holds static assets (fonts, images, videos).
• “src/app/” is the Next.js App Router: pages, layouts, API routes under api/authenticate, api/check-auth, api/og, plus next-generated sitemap and robots.
• “src/components/” contains reusable UI bits.
• “src/once-ui/” is the embedded component library (tokens, styles, hooks, components).
• “src/app/resources/” holds runtime configuration and content manifests.
• MDX posts live under “src/app/blog/posts” and “src/app/work/projects.”
• Config files: next.config.mjs, tsconfig.json, ESLint, PostCSS, package.json.
Key insights from the README
• Built with Next.js & Once UI, targeting Vercel.
• Features: automatic SEO (open-graph via next/og, metadata/schema), conditional page rendering (content-driven), password-protected routes, localization support (next-intl branch).
• MDX used for rich content; dynamic asset import.
Main components & interactions (to represent
a. Client (Browser)
– Requests HTML/CSS/JS.
– Runs React app, toggles theme, navigates between pages.
b. CDN / Static Asset Layer
– Serves files in “public/” (images, fonts, videos).
– Delivers built JS/CSS bundles.
c. Next.js Serverless Functions (on Vercel)
– SSG at build time: reads MDX files → generates static pages (blog, projects).
– SSR/API at runtime:
• /api/authenticate (password protection)
• /api/check-auth (verify session)
• /app/og route (dynamic OG image generation)
• /sitemap.xml and /robots.txt generation
– Data layer: imports from src/app/resources/config.js & content.js.
d. MDX Content Store
– Local files under blog/posts & work/projects.
– Parsed via next-mdx (build & hydration).
e. Once UI Component Library
– Shared tokens, styles, hooks, and components consumed by pages & src/components.
– Treat as an internal package module.
f. External Services
– Mailchimp (via Mailchimp.tsx) for newsletter sign-up.
– Vercel (hosting & deployment).
– (Potential) Analytics/CDN logging.
• Browser → CDN/static (GET bundles & assets)
• Browser → Next.js server (initial SSR or on-demand API calls)
• Next.js build process → MDX content → static page generation
• API routes ↔ Browser (auth, OG image fetch)
• Once UI library → consumed by pages & components
Architectural patterns & design principles
• Jamstack / hybrid SSG+SSR (Next.js App Router)
• Content-driven rendering (MDX + config)
• Design system integration (Once UI as a mono-repo component layer)
• API-first lightweight serverless endpoints for auth & dynamic assets
• Separation of concerns:
– Presentation (React + Once UI)
– Content (MDX)
– Config (JS modules)
– Serverless logic (API routes)