Data models

Most-traveled types in the codebase. If you're tracing data flow, these are the shapes that show up at most boundaries.

Routes

// packages/next/src/server/route-definitions/route-definition.ts
type RouteDefinition = {
  kind: RouteKind; // 'PAGES' | 'APP_PAGE' | 'APP_ROUTE' | 'PAGES_API'
  bundlePath: string; // .next/server path
  filename: string; // user source path
  page: string; // route path (e.g. '/dashboard/[id]')
  pathname: string; // resolved pathname for static routes
};

RouteKind lives in packages/next/src/server/route-kind.ts. Each kind has a corresponding subtype with extra fields:

• AppRouteRouteDefinition — for App Router route handlers.
• AppPageRouteDefinition — for App Router pages.
• PagesAPIRouteDefinition — for Pages Router API routes.
• PagesRouteDefinition — for Pages Router pages.

Definitions live under packages/next/src/server/route-definitions/.

Route matchers and matches

A matcher decides whether a request matches a route. A match is the result of running a matcher.

File	What
packages/next/src/server/route-matchers/route-matcher.ts	Base matcher
packages/next/src/server/route-matchers/locale-route-matcher.ts	Locale-aware matcher
packages/next/src/server/route-matches/route-match.ts	Base match
packages/next/src/server/route-matches/app-page-route-match.ts	App page match

Matchers know dynamic segments ([id]), catch-all ([...rest]), and optional catch-all ([[...rest]]).

Route modules

A RouteModule is the runtime-loaded module for a single route. Subclasses by kind:

File	What
packages/next/src/server/route-modules/app-page/module.ts	App page module
packages/next/src/server/route-modules/app-route/module.ts	App route handler module
packages/next/src/server/route-modules/pages/module.ts	Pages page module
packages/next/src/server/route-modules/pages-api/module.ts	Pages API module

Each one knows how to render itself.

Request / response

The framework abstracts HTTP via two adapters:

File	What
packages/next/src/server/base-http/	Internal abstraction
packages/next/src/server/request/	Request-level helpers (cookies, headers, body)
packages/next/src/server/web/spec-extension/request.ts	NextRequest (extends Web Request)

The same NextRequest shape works in Edge and Node — implementations diverge but the surface is identical.

Manifests

Built artifacts live as JSON in .next/. The runtime reads them on startup and caches per-process. Each manifest has a TS type:

Manifest	TS file
routes-manifest.json	packages/next/src/build/generate-routes-manifest.ts
app-build-manifest.json	packages/next/src/build/manifests/
prerender-manifest.json	packages/next/src/build/manifests/
client-reference-manifest.json	packages/next/src/build/webpack/plugins/flight-manifest-plugin.ts
server-reference-manifest.json	packages/next/src/build/webpack/plugins/flight-server-references-plugin.ts
next-font-manifest.json	packages/next/src/build/webpack/plugins/next-font-manifest-plugin.ts
react-loadable-manifest.json	packages/next/src/build/webpack/plugins/react-loadable-plugin.ts
images-manifest.json	packages/next/src/build/manifests/
middleware-manifest.json	packages/next/src/build/webpack/plugins/middleware-plugin.ts

Loader trees

App Router renders a tree of segments. The tree shape is:

type LoaderTree = [
  segment: string,
  parallelRoutes: { [parallelRouteKey: string]: LoaderTree },
  modules: {
    layout?: ModuleReference;
    page?: ModuleReference;
    error?: ModuleReference;
    loading?: ModuleReference;
    notFound?: ModuleReference;
    forbidden?: ModuleReference;
    unauthorized?: ModuleReference;
    template?: ModuleReference;
    route?: ModuleReference;
    metadata?: MetadataItems;
  },
];

Source: packages/next/src/server/app-render/types.ts. The build emits one of these per app-page entry into the corresponding template file.

FlightRouterState

The router's serialized state. Travels in the Next-Router-State-Tree header on RSC requests.

type FlightRouterState = [
  segment: Segment,
  parallelRoutes: { [parallelRouteKey: string]: FlightRouterState },
  url?: string | null,
  refresh?: 'refetch' | 'inside-shared-layout' | null,
  isRootLayout?: boolean,
];

Source: packages/next/src/server/app-render/types.ts.

Async storage

Multiple AsyncLocalStorage instances scope per-request data:

File	What
packages/next/src/server/app-render/work-async-storage.external.ts	Per-request work scope
packages/next/src/server/app-render/work-unit-async-storage.external.ts	Per-render-unit scope (for caching)
packages/next/src/server/app-render/action-async-storage.external.ts	Per-action scope
packages/next/src/server/app-render/after-task-async-storage.external.ts	Per-after-task scope

These are how server code accesses request data without explicit threading.

Errors

The framework's error registry lives at errors/index.json. Each entry has a code (e.g., E001), a one-line summary, and a path to a markdown explanation under errors/. Compiled-in calls to error(code) reference these. The SWC plugin at crates/next-error-code-swc-plugin/ rewrites the helpers at compile time.

Key source files

Listed inline above. The bulk of types live in:

• packages/next/src/server/app-render/types.ts (loader tree, FlightRouterState)
• packages/next/src/server/route-definitions/
• packages/next/src/server/route-modules/
• packages/next/src/build/manifests/
• packages/next/src/server/config-shared.ts (NextConfig)