This directory contains the Next.js App Router implementation for GitHub Docs. It currently serves as the application shell, handling the root layout, global providers, and 404 error pages, while coexisting with the Pages Router implementation.
The src/app directory is the entry point for the Next.js App Router. Its primary responsibilities are:
- Defining the root HTML structure and metadata.
- Initializing global client-side context providers (Theme, Locale, Languages).
- Handling global "Not Found" (404) scenarios.
- Providing a bridge between the modern App Router architecture and the
MainContextused by existing components.
We began this migration because we anticipate @primer/react will eventually drop support for the Pages Router. If that happens, we will be unable to upgrade @primer/react, effectively blocking us from receiving any future design system updates. Moving to the App Router prevents this and aligns us with the broader Next.js ecosystem.
layout.tsx: The server-side Root Layout. It sets up the<html>and<body>tags, loads global styles, and defines metadata/viewport settings.client-layout.tsx: A client component ('use client') that wraps the application in necessary React Context providers. This allows server components to compose client-side logic for theming and state management.not-found.tsx: The UI for 404 errors within the App Router.lib/: Utilities for context adaptation and routing logic.app-router-context.ts: Generates context data based on the current request path.main-context-adapter.ts: Adapts App Router data structures to match theMainContextshape, ensuring backward compatibility for components.
components/: Client-side components specific to the App Router shell (e.g., wrappers for 404 pages, context providers).
- Context Adaptation: Since much of the codebase relies on a monolithic
MainContext, this directory implements adapters to construct a compatible context object from App Router primitives. This allows us to reuse existing components without rewriting them immediately. - Hybrid Routing: The application currently operates in a hybrid mode. While
src/appdefines the outer shell, many specific routes and page rendering logic may still reside in the Pages Router (src/pages) or are being incrementally migrated.
Standard Next.js App Router conventions apply. To add a new route using the App Router, create a folder with a page.tsx file inside src/app.
Useful documentation:
Tests for App Router logic should be placed alongside the components if applicable.
Tests that verify Next.js behavior (like 404 handling) can be found in src/frame/tests/next.ts.
- Data Sources:
- Consumes UI strings and language data from
src/data-directory(viagetUIDataMerged). - Uses
src/languagesfor locale definitions.
- Consumes UI strings and language data from
- External Libraries:
@primer/react: Used for the design system and theming provider.next: The core framework.
- Owner: Docs Engineering
- Related Directories:
src/pages: The Pages Router implementation.src/frame: Server and middleware logic that interacts with routing.src/data-directory: Source of static data used in layouts.
- Current State: The App Router handles the root layout and 404s. It provides a compatibility layer for existing contexts.
- Next Steps:
- Migrate individual page routes from
src/pagestosrc/app. - Refactor components to reduce dependency on the monolithic
MainContext. - Improve data fetching patterns to use React Server Components (RSC) more effectively.
- Migrate individual page routes from