|
| 1 | +# App Router (`src/app`) |
| 2 | + |
| 3 | +This directory contains the [Next.js App Router](https://nextjs.org/docs/app) 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. |
| 4 | + |
| 5 | +## Purpose & Scope |
| 6 | + |
| 7 | +The `src/app` directory is the entry point for the Next.js App Router. Its primary responsibilities are: |
| 8 | +- Defining the root HTML structure and metadata. |
| 9 | +- Initializing global client-side context providers (Theme, Locale, Languages). |
| 10 | +- Handling global "Not Found" (404) scenarios. |
| 11 | +- Providing a bridge between the modern App Router architecture and the `MainContext` used by existing components. |
| 12 | + |
| 13 | +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. |
| 14 | + |
| 15 | +## Architecture & Key Assets |
| 16 | + |
| 17 | +### Directory Structure |
| 18 | + |
| 19 | +- `layout.tsx`: The server-side Root Layout. It sets up the `<html>` and `<body>` tags, loads global styles, and defines metadata/viewport settings. |
| 20 | +- `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. |
| 21 | +- `not-found.tsx`: The UI for 404 errors within the App Router. |
| 22 | +- `lib/`: Utilities for context adaptation and routing logic. |
| 23 | + - `app-router-context.ts`: Generates context data based on the current request path. |
| 24 | + - `main-context-adapter.ts`: Adapts App Router data structures to match the `MainContext` shape, ensuring backward compatibility for components. |
| 25 | +- `components/`: Client-side components specific to the App Router shell (e.g., wrappers for 404 pages, context providers). |
| 26 | + |
| 27 | +### Key Concepts |
| 28 | + |
| 29 | +- **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. |
| 30 | +- **Hybrid Routing**: The application currently operates in a hybrid mode. While `src/app` defines the outer shell, many specific routes and page rendering logic may still reside in the Pages Router (`src/pages`) or are being incrementally migrated. |
| 31 | + |
| 32 | +## Setup & Usage |
| 33 | + |
| 34 | +### Development |
| 35 | + |
| 36 | +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`. |
| 37 | + |
| 38 | +Useful documentation: |
| 39 | +- [Next.js App Router Documentation](https://nextjs.org/docs/app) |
| 40 | +- [Migrating from Pages to App Router](https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration) |
| 41 | + |
| 42 | +### Testing |
| 43 | + |
| 44 | +Tests for App Router logic should be placed alongside the components if applicable. |
| 45 | + |
| 46 | +Tests that verify Next.js behavior (like 404 handling) can be found in `src/frame/tests/next.ts`. |
| 47 | + |
| 48 | +## Data & External Dependencies |
| 49 | + |
| 50 | +- **Data Sources**: |
| 51 | + - Consumes UI strings and language data from `src/data-directory` (via `getUIDataMerged`). |
| 52 | + - Uses `src/languages` for locale definitions. |
| 53 | +- **External Libraries**: |
| 54 | + - `@primer/react`: Used for the design system and theming provider. |
| 55 | + - `next`: The core framework. |
| 56 | + |
| 57 | +## Cross-links & Ownership |
| 58 | + |
| 59 | +- **Owner**: Docs Engineering |
| 60 | +- **Related Directories**: |
| 61 | + - `src/pages`: The Pages Router implementation. |
| 62 | + - `src/frame`: Server and middleware logic that interacts with routing. |
| 63 | + - `src/data-directory`: Source of static data used in layouts. |
| 64 | + |
| 65 | +## Current State & Next Steps |
| 66 | + |
| 67 | +- **Current State**: The App Router handles the root layout and 404s. It provides a compatibility layer for existing contexts. |
| 68 | +- **Next Steps**: |
| 69 | + - Migrate individual page routes from `src/pages` to `src/app`. |
| 70 | + - Refactor components to reduce dependency on the monolithic `MainContext`. |
| 71 | + - Improve data fetching patterns to use React Server Components (RSC) more effectively. |
0 commit comments