Skip to content

Latest commit

 

History

History
346 lines (251 loc) · 11.3 KB

technologies.md

File metadata and controls

346 lines (251 loc) · 11.3 KB

Technologies & Architecture

This document provides an overview of the technologies used in the Node.js website and explains key architectural decisions.

Table of Contents

Core Technologies

Frontend Framework

The Node.js Website is built with React and Next.js:

  • React: UI rendering engine for component-based development
  • Next.js: Full-stack framework providing SSG, routing, and build optimization

Why Next.js?

We chose Next.js because it is:

  • Versatile and hackable for custom requirements
  • Stable with strong community maintenance
  • Well-suited as a long-term framework choice
  • Capable of supporting static builds (a requirement from the Node.js Technical Steering Committee)

Styling System

  • PostCSS: CSS preprocessing with plugin-based architecture
  • Tailwind CSS: Utility-first CSS framework and design system foundation
  • CSS Modules: Scoped styling for components

PostCSS Plugins

  • postcss-calc: Resolves calc() expressions at build time
  • @tailwindcss/postcss: Enables Tailwind integration

Content Management

  • MDX: Markdown with JSX component support
  • Remark: Markdown processing plugins
  • Rehype: HTML processing plugins

Content Processing Plugins

  • remark-gfm: GitHub Flavored Markdown support
  • remark-headings: Generates metadata for table of contents
  • rehype-autolink-headings: Automatic anchor links for headings
  • rehype-slug: Automatic ID generation for headings

UI Components

  • Radix UI: Accessible, unstyled component primitives
  • Hero Icons: SVG icon library
  • Shiki: Syntax highlighting for code blocks

Why Radix UI?

  • Minimalistic, component-focused approach
  • Built-in WAI-ARIA and accessibility features
  • Allows focus on design without accessibility implementation overhead
  • Modular package structure

Internationalization

Development Tools

  • Storybook: Component development and visual testing
  • Chromatic: Automated visual regression testing
  • Husky: Git hooks for code quality

Repository Structure

nodejs.org/
├── apps/
│   └── site/                    # Main website application
│       ├── components/          # Website-specific React components
│       ├── layouts/             # Page layout templates
│       ├── pages/               # Content pages (Markdown/MDX)
│       │   ├── en/              # English content (source)
│       │   └── {locale}/        # Translated content
│       ├── public/              # Static assets
│       │   └── static/          # Images, documents, etc.
│       ├── hooks/               # React hooks
│       ├── providers/           # React context providers
│       ├── types/               # TypeScript definitions
│       ├── next-data/           # Build-time data fetching
│       ├── scripts/             # Utility scripts
│       ├── snippets/            # Code snippets for download page
│       └── tests/               # Test files
│           └── e2e/             # End-to-end tests
└── packages/
    ├── ui-components/           # Reusable UI components
    │   ├── styles/             # Global stylesheets
    │   └── .storybook/         # Storybook configuration
    ├── i18n/                # Internationalization
    │   ├── locales/         # Translation files
    │   └── config.json      # Locale configuration
    ├── rehype-shiki/        # Syntax highlighting plugin
   ...

Architecture Decisions

Static Build Support

The website supports fully static builds to ensure independence from third-party services:

  • Content can be served without external dependencies
  • Maintains availability even if hosting providers change

Custom Page Rendering

The website uses a custom rendering system instead of Next.js default routing:

[...path].tsx - Dynamic Route Handler

  • Catches all routes and renders them through a custom system
  • Enables dynamic page generation from Markdown files
  • Supports incremental static generation (ISG)

next.dynamic.mjs - Page Generation

This file handles:

  • Discovering all source pages in apps/site/pages/en
  • Identifying translated pages
  • Generating localized paths for untranslated content
  • Creating fallback pages that show English content with translated menus and UI elements

next.data.mjs - Build-time Data

Responsible for:

  • Node.js release data fetching
  • Blog post metadata generation
  • RSS feed creation
  • Build-time indexing

Internationalization Strategy

Why Not Next.js Built-in i18n?

We use a custom i18n solution because:

  • Need comprehensive locale and page listing capabilities
  • Use subfolder content structure (/pages/en/, /pages/fr/) vs. extension-based (file.en.md)
  • Maintain consistency with previous website structure
  • Ensure long-term maintainability

Locale Detection and Routing

  • next.middleware.js: Handles browser locale detection and redirects
  • Falls back to /en for unsupported locales
  • Provides seamless user experience across languages

Content Structure

Layouts System

// Each page specifies its layout in frontmatter
---
title: Page Title
layout: layout-name
---

// Layouts wrap content and provide structure
const Layout: FC<{ children: ReactNode }> = ({ children }) => (
  <div className="layout">
    <Header />
    <main>{children}</main>
    <Footer />
  </div>
);

Content Processing Pipeline

  1. Markdown files → MDX compiler
  2. Rehype/Remark plugins → Content transformation
  3. Shiki integration → Syntax highlighting
  4. Layout system → Page structure
  5. i18n integration → Localized rendering

Rewrite and Redirect System

next.rewrites.mjs

Handles URL rewriting and redirects:

// Internal rewrites (same content, different URL)
{ source: '/old-path', destination: '/new-path' }

// External redirects (different domain)
{ source: '/docs', destination: 'https://nodejs.org/docs' }

// Locale template support
{ source: '/:locale/old-path', destination: '/:locale/new-path' }

redirects.json

Configuration file supporting:

  • Internal and external redirects
  • Locale templating with /:locale placeholder
  • Simple template engine for dynamic paths

Configuration Files

site.json

Website metadata configuration:

  • RSS feed definitions
  • Social media information
  • Build-time metadata
  • Uses JSON format for easy collaboration

Development Environment

VSCode Configuration

The .vscode directory provides:

  • extensions.json: Recommended extensions for optimal development
  • settings.json: Consistent formatting and linting configuration

Benefits:

  • Uniform developer experience
  • Automatic code formatting and linting
  • Tailwind CSS IntelliSense
  • Works with GitHub Codespaces

Build and Deployment

Multiple Build Targets

  • pnpm build: Production build for Vercel
  • pnpm deploy: Export build for legacy servers
  • pnpm dev: Development server

Vercel Integration

  • Automatic deployments for branches (excluding dependabot/* and gh/*)
  • Custom install script: pnpm install --prod --frozen-lockfile
  • Dependency management: Build-time dependencies must be in dependencies, not devDependencies
  • Sponsorship maintained by OpenJS Foundation

Package Management

Multi-package Workspace

  • Individual packages published to npm registry
  • Automated publishing via GitHub Actions
  • Triggered after successful CI or manual workflow dispatch

Publishing Process

  1. Automatic: After merging to main (via merge queue)
  2. Manual: Workflow dispatch for specific packages
  3. Notifications: Slack alerts for manual triggers

Performance Optimizations

Static Generation

  • Build-time page generation reduces server load
  • Incremental Static Regeneration (ISR) for dynamic content
  • Optimized asset handling and compression

Bundle Optimization

  • Code splitting at component and route levels
  • Dynamic imports for large components
  • Tree shaking for unused code elimination

Image Optimization

  • Next.js Image component for automatic optimization
  • WebP conversion and responsive images
  • Lazy loading for performance

Testing Infrastructure

Visual Regression Testing

  • Storybook integration with Chromatic
  • Automated visual diff detection
  • Component isolation and testing

End-to-End Testing

  • Playwright for full application testing
  • Critical user journey validation
  • Cross-browser compatibility testing