System at a Glance
| Layer | Technology | Purpose |
|---|---|---|
| Framework | Next.js 16 + React 19 | SSG, routing, build optimization |
| Content | MDX + Remark/Rehype | Markdown-with-JSX authoring pipeline |
| Styling | Tailwind CSS + CSS Modules + PostCSS | Utility-first design + scoped components |
| UI Primitives | Radix UI + Heroicons | Accessible, unstyled component base |
| i18n | next-intl + Crowdin | Subfolder-per-locale translations |
| Syntax Highlighting | Shiki | Build-time code block coloring |
| Testing | Playwright + Storybook + Chromatic | E2E + visual regression |
| Deployment | Vercel (primary) + Cloudflare (secondary) | CDN-backed global serving |
Key Design Decisions
Static Build Support
The Node.js Technical Steering Committee requires the site to be fully statically exportable. Runningpnpm deploy produces a standalone build/ directory that can be served from any file server — no Node.js process needed at runtime. This ensures the site can be served even if cloud hosting providers change.
Custom Page Rendering
Rather than relying on Next.js file-system routing directly, the site uses a[...path].tsx catch-all route paired with next.dynamic.mjs to:
- Discover all Markdown/MDX source pages under
apps/site/pages/en/ - Generate localized paths for every supported locale
- Serve English content as a fallback for untranslated pages (with localized navigation and UI)
Custom Internationalization
The site does not use Next.js’s built-in i18n routing. Instead, it uses a subfolder-per-locale content structure (/pages/en/, /pages/fr/, etc.) combined with next-intl for message formatting. This matches the previous site structure and gives more control over page listing and routing.
Layouts as Frontmatter
Every content page declares its layout in YAML frontmatter. The layout system inapps/site/layouts/ wraps MDX content with the appropriate navigation, sidebars, and metadata components. Adding a new layout means adding a file to that directory and registering it in withLayout.tsx.
Architecture Groups
Explore each area of the architecture in detail:Tech Stack
All libraries and frameworks — Next.js, React, MDX, Tailwind, Radix UI, Shiki, next-intl, Storybook, Playwright.
Repository Structure
Monorepo layout:
apps/site/, packages/ui-components/, packages/i18n/, packages/rehype-shiki/.Content Pages
How MDX pages work, frontmatter fields, and the custom rendering pipeline.
Adding Pages
Step-by-step guide to creating new content pages and updating navigation.
Layouts
Available layout templates and how to create a custom layout.
MDX Features
GFM, tabbed code blocks, React components in content, and Shiki syntax highlighting.
i18n Overview
Why a custom i18n approach, next-intl, ICU Message Syntax, and locale routing.
Translation Workflow
Crowdin sync, GitHub Actions automation, and which sections are translated.
Adding a Language
How to request and configure a new locale in
i18n/config.json.Build Targets
pnpm build, pnpm deploy, and pnpm dev — when to use each.Vercel Deployment
Auto-deploy on push to
main, branch previews, and dependency rules.Cloudflare Deployment
OpenNext Cloudflare adapter, Wrangler configuration, R2 cache, and skew protection.