Every React application needs the same plumbing before it can ship: a bundler, a compiler, a routing system, server rendering, image optimization, and a story for data fetching. Next.js, maintained by Vercel, packages all of that into a single framework - you write React components, and Next.js decides how they are compiled, rendered on the server or the client, cached, and deployed. It is the framework behind sites from some of the world’s largest companies, and its repository is one of the largest TypeScript codebases in open source.

What makes the repository genuinely interesting is that it is two frameworks in one. There is the TypeScript side in packages/next - the CLI, the dev server, the server runtime, and the client router - and there is a Rust side, spread across crates and the turbopack workspace, where the SWC compiler and the Turbopack bundler live. The two halves talk over a napi-rs bridge, and understanding that seam explains almost everything about how Next.js behaves: its build speed, its hot reloading, and its incremental caching. This post walks through that machinery as it is actually implemented in the repository.

High-level overview: create-next-app scaffolds projects around the next CLI, which drives the dev server, the build system, and the production server; the compiler layer reaches into the Rust native layer, and the server renderer streams React output to the client router.

Reading the overview left to right tells the story of a Next.js project’s life. The create-next-app node on the left is where every project begins - it generates an application skeleton that depends on the next CLI entry point in the center. From that entry point, three paths fan out. The first goes to the dev server, the tool that watches your files while you work; notice it points back into the compiler box, because development compiles on demand rather than up front. The second path is next build, the production compiler. The third is the production server runtime, which only ever runs what the build produced.

The two boxes on the right of the framework core deserve attention because they are the heart of the App Router. The server renderer turns your React components into HTML and flight payloads on the server, and the client router box below it is the counterpart that hydrates and navigates that output in the browser. Finally, the layer at the bottom right - the SWC bindings and the Turbopack engine - is the Rust side of the repository. Every compile operation in the TypeScript boxes ultimately crosses into those Rust crates, which is why the diagram draws them as a separate group rather than as part of the framework core. The documentation and examples nodes complete the picture: they are how the project teaches itself to new developers.

Why You Need This

Before frameworks like Next.js, assembling a production React app was a project in itself. You had to pick a bundler, wire up a compiler, decide between client-side rendering and server-side rendering, configure code splitting, solve image and font optimization, and then glue all of it together with custom server code - and every choice you made was another thing to maintain. Most teams ended up with nearly identical webpack configurations and none of them worked quite the same way.

Next.js collapses that entire decision tree into one install. The repository README describes it plainly: Next.js enables you to create full-stack web applications by extending the latest React features and integrating powerful Rust-based JavaScript tooling for the fastest builds. That single sentence maps to real subsystems you can find in the source. The App Router builds on React Server Components, so pages render on the server by default and stream to the browser. The bundler story is written in Rust, first as SWC transforms and now as Turbopack, which replaces long webpack rebuilds with incremental computation. And the framework takes responsibility for the awkward parts - routing, caching, prefetching - so that the application code stays declarative.

This post is for developers who use Next.js daily and want to know what next dev actually starts, or who debug a build and want to know which layer owns the error. The answer, as we will see, is always one of four places: the CLI, the compiler, the server runtime, or the client router.

How It Works

The diagram below maps the real subsystems of the repository and how they connect.

Detailed architecture: the CLI and its commands, the development server, the compiler and build layer, the server runtime with its caches, the client router, the Rust native layer, and the surrounding ecosystem of tooling, docs, and tests.

Understanding the Architecture

Entry point and CLI. Everything starts at packages/next/src/bin/next.ts, the executable that lands in node_modules/.bin/next when you install the framework. It parses the command name and dispatches into packages/next/src/cli: next-dev.ts, next-build.ts, and next-start.ts are the three verbs every Next.js developer knows, and the CLI directory also holds next-export, next-info, next-telemetry, next-typegen, and next-upgrade. Keeping the commands thin matters - each one is just a shell that configures options and hands control to the machinery deeper in the package.

The development server chain. next dev boots through a precise sequence. The command calls the bootstrap in packages/next/src/server/lib/start-server.ts, which starts an HTTP server and loads the router server in server/lib/router-server.ts; the router server, in turn, initializes the actual dev server in server/dev/next-dev-server.ts. That class owns the development request cycle and drives a hot reloader - the repository ships one per bundler (hot-reloader-turbopack.ts, hot-reloader-webpack.ts, hot-reloader-rspack.ts), each implementing the same contract of watching files and pushing HMR updates to the browser. The dev server is also where Next.js does its best impression of a production server: it serves the same routes, runs the same renderer, and returns the same kinds of errors, so the gap between development and production stays small.

Compiler and build layer. When next build runs, the orchestrator in packages/next/src/build/index.ts coordinates everything: it reads the configuration, computes the route tree, runs the bundler, and writes the manifests the production server will later consume. Two bundler implementations hang off it. The stable path is the webpack builder in build/webpack-build/index.ts, configured by the enormous but battle-tested rule set in build/webpack-config.ts. The Rust path is the Turbopack builder in build/turbopack-build/index.ts. Both converge on the same native dependency: the SWC bindings loader in build/swc/index.ts, whose loadBindings function locates and loads the platform-specific next-swc binary. When output: 'export' is configured, the build also drives the static exporter in packages/next/src/export/index.ts, which renders every route to plain HTML files.

The server runtime. In production, next start serves prebuilt output through NextNodeServer in packages/next/src/server/next-server.ts, which extends the shared request machinery in server/base-server.ts. For App Router pages, the base server hands requests to the React Server Components renderer in server/app-render/app-render.tsx, and it is the app page module in server/route-modules/app-page/module.ts that invokes the renderer’s renderToHTMLOrFlight entry point. The renderer creates an async work store - server/async-storage/work-store.ts - so that components can call cookies() and headers() without threading a request object through every function. Caching is layered: the response cache in server/response-cache memoizes rendered output in memory, while the incremental cache in server/lib/incremental-cache persists revalidated pages to disk or a shared store, which is what makes ISR possible. There are also the specialists: server/image-optimizer.ts serves resized images on demand, and server/use-cache/use-cache-wrapper.ts implements the use cache runtime for function-level caching.

The client router. Everything the server produces crosses the network as a serialized React flight payload, and the browser side picks it up in packages/next/src/client/components/app-router.tsx. That component is the host for navigation: when you click a link, the router reducer - for example client/components/router-reducer/reducers/navigate-reducer.ts - computes the new router state, and the segment cache in client/components/segment-cache/cache.ts supplies prefetched or previously rendered segments so that navigation can complete without a round trip. This is a state machine built from reducers, which is why Next.js navigation can prefetch, cache, and reconcile partial layouts with so little application code.

The Rust native layer. Underneath the JavaScript sits the Rust half. The SWC bindings loader talks to crates/next-napi-bindings/src/lib.rs, the napi-rs bridge that exposes compiled Rust functions to Node. That crate fronts crates/next-core, which models Next.js project structure and configuration (see next_config.rs), and crates/next-api, the project API Turbopack uses during development. The bundler itself lives in the turbopack workspace - turbopack/crates/turbopack - on top of the incremental computation engine in turbopack/crates/turbo-tasks, which is the real reason rebuilds are fast: instead of rerunning a whole build, TurboTasks recomputes only the tasks whose inputs changed.

Ecosystem and quality gates. Around the core sit the packages that make the framework feel complete: packages/create-next-app scaffolds new projects (its create-app.ts is worth reading if you have ever wondered what those interactive prompts do), the documentation lives in the docs directory with separate App Router and Pages Router trees, the examples directory holds dozens of starter templates, and the test/e2e suites exercise the whole stack against real built apps. The e2e tests are the framework’s specification in practice - most behaviors you rely on have a test fixture somewhere in that tree.

A request in flight. Follow one request through the boxes above. In development, the browser asks the dev server for a route; the hot reloader asks the native layer to compile exactly the modules touched, and the app renderer produces the flight payload, which the client router hydrates into a live tree. In production, next build has already run everything through SWC and the bundler and written static shells and manifests; next start serves those artifacts, re-renders only where the data demands it, consults the response and incremental caches first, and streams fresh output to the segment cache in the browser for the next navigation.

Advantages

• Rendering strategy as a per-route decision. Static generation, server rendering, and incremental revalidation are not separate tools - they are properties of individual routes, managed by the same server runtime and the same caches. You choose per page, not per project.
• A bundler written for incrementalism. Turbopack is built on TurboTasks, an incremental computation engine in Rust, so rebuilds recompute only what changed. Webpack remains the stable fallback, and both bundlers share the same framework-level configuration, so switching does not rewrite your app.
• React Server Components done end to end. The App Router’s renderer, route modules, and client router implement the full RSC model: server components render to a streamed flight payload, client components hydrate selectively, and the segment cache makes back-and-forward navigation instant.
• One native layer, many payoffs. The same next-swc binary that compiles TypeScript for webpack also powers Turbopack and the framework’s codemods. Fast transforms in Rust show up everywhere at once, and the napi bridge keeps that complexity out of the JavaScript layer.
• Caching as architecture, not an afterthought. Response cache, incremental cache, and the segment cache are separate, inspectable layers, each with a defined scope - rendered output, persisted pages, and prefetched client segments respectively.
• A monorepo that tests itself. The repository runs e2e suites across dev, start, and deploy modes and across webpack, rspack, and Turbopack, which is how a codebase this large ships canary releases weekly with reasonable confidence.

Benefits

• Time to first product, not time to first config. create-next-app gives you a working full-stack app in minutes, with routing, rendering, and optimization already wired - the hours you would have spent on bundler configuration go into the application instead.
• Performance you get by default. Server rendering, code splitting, image optimization, and font handling are on without effort, and because the framework owns them, they improve with every upgrade rather than with every refactor.
• Predictable deployments. Because the output of next build is a well-defined structure of manifests, static shells, and server functions, the same project can run under next start, behind a container, or on serverless infrastructure without code changes.
• A gentler debugging experience. The dev server mirrors production behavior closely enough that most bugs reproduce locally, and errors surface from the same subsystems described above - which turns stack traces into readable maps.
• A career-relevant codebase to read. The repository demonstrates how to structure a large TypeScript application, how to integrate Rust into a Node project through napi, and how to keep a stable API while rewriting its implementation - lessons that transfer well beyond web development.
• Open governance and momentum. The framework develops in the open on GitHub, with public discussions, weekly canaries, and a contribution process documented in the repository itself.

Usage

For most people the entry point is not the repository but the published next package. Scaffold an application with the scaffolder from packages/create-next-app:

npx create-next-app@latest

The command is interactive - it asks about TypeScript, linting, and whether you want the App Router - and you can bootstrap directly from the examples gallery that ships in the repository, for example:

npx create-next-app@latest --example blog-starter

Inside the app, the three commands you will live in are the ones the CLI implements:

npm run dev      # next dev - development server with hot reloading
npm run build    # next build - production build
npm run start    # next start - serve the production build

To work on the framework itself, clone the repository and use the workspace tooling exactly as documented in its contribution guides. The repo is a pnpm workspace managed with Turborepo:

git clone https://github.com/vercel/next.js.git
cd next.js
pnpm install
pnpm dev

pnpm dev watches the TypeScript sources and rebuilds as you edit; the precompiled native binaries are pulled in automatically during install. When you want the full production output, the build guide in contributing/core/building.md is explicit:

pnpm build

A few more commands are worth knowing if you dig into the source: pnpm types regenerates the type definitions, pnpm test-unit runs the unit tests in test/unit, and if you are working on the Rust side, pnpm swc-build-native compiles the native SWC bindings locally. Running an actual app against your locally built framework closes the loop between reading the source and watching it behave.

Conclusion

Next.js succeeds because it treats “a React app that ships” as an engineering problem with real subsystems, and the repository reflects that honestly: a CLI that dispatches to commands, a dev server that mirrors production, a build layer that can swap bundlers, a server runtime with layered caches, a client router built on reducers, and a Rust foundation that makes the whole thing fast. None of it is magic - it is readable source, from bin/next.ts down to turbo-tasks, and each layer has a job you can name. If you build with Next.js, spending an afternoon in this repository pays off every time a build breaks or a render surprises you; you will know exactly which box to look at. Clone it, run a build, and watch the pieces move in the order this post describes.

Links:

• Repository: https://github.com/vercel/next.js
• Website: https://nextjs.org
• Documentation: https://nextjs.org/docs
• Learn course: https://nextjs.org/learn
• GitHub Discussions: https://github.com/vercel/next.js/discussions

Enjoyed this post? Never miss out on future posts by following us