Web Engineering · May 29, 2026

How Next.js Works Internally: The Compilation Pipeline, RSC Protocol, and Caching Architecture From Request to Render

A deep dive into the internal architecture of Next.js App Router. Covers the SWC/Turbopack compilation pipeline, the RSC wire protocol, the four-layer caching architecture, rendering strategies, middleware execution, Server Actions, and the self-hosted vs managed deployment tradeoffs.

Most developers using Next.js App Router know the surface API: async server components, "use client", fetch with { next: { revalidate } }, Server Actions with "use server". What very few understand is what the framework is actually doing at each stage, and why certain behaviors exist that otherwise seem arbitrary.

Understanding the internals matters when you hit edge cases. Cache invalidation that does not behave as expected. Middleware that fires at a different time than you assumed. A deployment that works on Vercel but breaks on your own Node.js server. These problems are easy to debug when you have a clear model of what is happening. Without that model, you are guessing.

This article builds that model: from the compilation pipeline through the RSC wire protocol to the four-layer caching system, rendering strategies, and the deployment differences that actually matter in production.

The Compilation Pipeline: SWC, Turbopack, and the Client/Server Split

When you run next build, the first thing Next.js does is analyze your component tree to produce two separate module graphs: one for the server and one for the client. This split is the foundation that everything else rests on.

The compiler (SWC in the stable webpack-backed pipeline, Turbopack in the newer pipeline) scans your source files for "use client" and "use server" directives. These directives act as boundary markers:

A file with "use client" at the top becomes an entry point in the client module graph. Its imports are pulled into the client bundle.
A file with "use server" marks functions that the server exposes as callable endpoints (used for Server Actions).
Files with neither directive are treated as server-only by default. They do not appear in the client bundle at all.

SWC is a Rust-based compiler that replaces Babel. It handles JSX transformation, TypeScript stripping, decorators, and the RSC-specific transforms. On a large codebase, SWC is typically 20-70x faster than Babel for individual file transforms.

Turbopack is the incremental bundler replacing webpack. The key architectural difference is that Turbopack builds a demand-driven task graph using a persistent cache backed by the filesystem. Each task corresponds to a computation (parse a file, resolve imports, transform JSX) and Turbopack only re-executes tasks whose inputs changed. In a monorepo with hundreds of components, changing one file in development causes only the affected subgraph to rebuild, not the entire dependency tree.

The output of next build is:

A set of server bundles (one per route segment, plus shared chunks)
A set of client bundles (hydration scripts, client components, and browser runtime)
A prerendered HTML and RSC payload for every statically renderable route
A .next/server/ directory containing the Node.js runtime artifacts
A routes manifest, middleware manifest, and prerender manifest used at request time

For the client bundle, Next.js does automatic code splitting per route. You do not get one large bundle.js. Each route gets a minimal chunk containing only the client components actually used on that route, plus shared chunks for components used across routes.

The RSC Wire Protocol

The React Server Components payload is the data format that carries the server-rendered component tree from the server to the client. It is not HTML and it is not JSON. It is a custom line-delimited text format that React’s client runtime knows how to parse and apply.

Understanding this format explains behaviors that seem magical otherwise: how server components can stream in out of order, why RSC navigations feel instant while still fetching fresh data, and what router.refresh() actually does.

An RSC payload looks roughly like this (simplified):

0:["$","div",null,{"className":"container","children":["$","$L1",null,{"title":"Hello"}]}]
1:I["./components/ClientButton","default"]
2:["$","$L1",null,{"label":"Click me"}]

Each line starts with a row identifier. Row 0 is typically the root element tree, serialized as a recursive JSON structure using React’s internal element format. The "$" prefix denotes a React element. "$L1" is a lazy reference to a client component module, identified by its chunk path.

Row 1 is a client component reference declaration. It tells the browser which module to load and which export to use when it encounters $L1 in the tree.

This format is designed to stream. The server can emit row 0 as soon as the root layout renders, then emit rows for subtrees as their async data resolves. The client runtime processes each row as it arrives and progressively builds the React tree without waiting for the full payload.

Here is a concrete example of how a page with a slow data fetch streams:

// app/dashboard/page.tsx
export default async function DashboardPage() {
  // This resolves immediately
  const user = await getUser();

  return (
    <main>
      <h1>Welcome, {user.name}</h1>
      {/* This suspends until metrics load */}
      <Suspense fallback={<MetricsSkeleton />}>
        <MetricsPanel />
      </Suspense>
    </main>
  );
}

// app/dashboard/MetricsPanel.tsx
export default async function MetricsPanel() {
  // This takes 400ms
  const metrics = await getMetrics();
  return <MetricsGrid data={metrics} />;
}

The server emits the RSC payload for <main> and <h1> immediately. When MetricsPanel suspends, the payload includes a Suspense boundary placeholder. When getMetrics() resolves 400ms later, the server emits the RSC rows for <MetricsGrid> and streams them to the client. The React runtime on the client fills in the Suspense boundary without a full re-render of the page.

On soft navigations (clicking a Link component), Next.js does not reload HTML. It fetches only the RSC payload for the new route, applies it to the existing React tree, and React reconciles the diff. This is why App Router navigations preserve state in persistent layout components: the RSC payload only replaces the changed subtree.

The Four-Layer Caching Architecture

Next.js has four distinct caching mechanisms. They operate at different granularities and have different invalidation semantics. Using all four correctly requires understanding what each one owns.

Layer 1: Request Memoization

Request memoization deduplicates identical fetch calls within a single render pass. If two server components in the same request tree call fetch("https://api.example.com/user/1") with identical URL and options, only one network request goes out. The second call receives the cached response from memory.

This memoization is per-request only. It does not persist across requests. Its purpose is to allow you to fetch data close to where it is used (inside the component that needs it) without worrying about N+1 fetch calls in a single render tree.

// Both components call the same URL. Only one fetch goes out per request.
async function UserAvatar({ userId }: { userId: string }) {
  const user = await fetch(`/api/users/${userId}`).then(r => r.json());
  return <img src={user.avatarUrl} alt={user.name} />;
}

async function UserName({ userId }: { userId: string }) {
  const user = await fetch(`/api/users/${userId}`).then(r => r.json());
  return <span>{user.name}</span>;
}

Layer 2: Data Cache

The Data Cache persists fetch responses across requests and deployments. When you call fetch inside a server component or a Route Handler, Next.js wraps the native fetch and stores the response on disk (in .next/cache/fetch-cache/) or in a remote cache store on managed deployments.

The cache key is derived from the URL and options. Cache entries have configurable lifetimes:

// Cache for 60 seconds, then revalidate
const data = await fetch("https://api.example.com/posts", {
  next: { revalidate: 60 },
});

// Never cache (opt out)
const data = await fetch("https://api.example.com/user", {
  cache: "no-store",
});

// Cache indefinitely until manually revalidated
const data = await fetch("https://api.example.com/config", {
  next: { tags: ["config"] },
});

On-demand revalidation lets you invalidate specific cache entries by tag:

import { revalidateTag } from "next/cache";

// In a Route Handler or Server Action called after a CMS publish
export async function POST() {
  revalidateTag("config");
  return Response.json({ revalidated: true });
}

Layer 3: Full Route Cache

The Full Route Cache stores the rendered HTML and RSC payload for a complete route on the server filesystem. At build time, any route that can be statically rendered (no dynamic functions like cookies(), headers(), or searchParams accessed) gets prerendered and stored. These routes are served directly from the cache on each request without running any server-side code.

At runtime, dynamically rendered routes do not use the Full Route Cache at all. They run the full render pipeline on every request.

The Full Route Cache is invalidated when you call revalidatePath(), when a revalidateTag() invalidates a fetch result that a route depends on, or when you redeploy.

Layer 4: Router Cache

The Router Cache lives entirely in the browser. It is an in-memory store of RSC payloads for routes the user has already visited. When you navigate back to a previously visited route, Next.js serves the cached RSC payload from memory instead of making a server request.

The Router Cache has fixed expiration: 30 seconds for dynamically rendered routes, 5 minutes for statically rendered routes. Calling router.refresh() invalidates the Router Cache for the current route and triggers a fresh RSC payload fetch from the server.

This is the layer that most often surprises developers. Data that was just mutated via a Server Action still shows the old values until the Router Cache expires or is explicitly invalidated. The fix:

"use server";

import { revalidatePath } from "next/cache";

export async function updatePost(id: string, data: PostData) {
  await db.posts.update(id, data);
  revalidatePath("/posts");       // Clears Full Route Cache for /posts
  // Router Cache on client expires after 30s, or user calls router.refresh()
}

Rendering Strategies

Next.js supports three rendering strategies, and the choice happens at the route segment level, not per component.

Static Rendering (SSG) is the default. Routes are rendered at build time and the output is stored in the Full Route Cache. Appropriate for content that does not change per-user or per-request: marketing pages, blog posts, documentation.

Dynamic Rendering kicks in automatically when a route accesses dynamic functions: cookies(), headers(), searchParams, or noStore(). The route renders fresh on every request, bypassing the Full Route Cache but still using the Data Cache for individual fetch calls.

Incremental Static Regeneration (ISR) combines static rendering with time-based or on-demand revalidation. The route is prerendered at build time, served statically, and regenerated in the background when the revalidation period expires. The first request after expiration receives the stale page while the regeneration happens asynchronously. The next request gets the fresh version.

// This route is ISR with 300-second revalidation
export const revalidate = 300;

export default async function BlogPost({ params }: { params: { slug: string } }) {
  const post = await fetch(`https://cms.example.com/posts/${params.slug}`, {
    next: { revalidate: 300 },
  }).then(r => r.json());

  return <Article post={post} />;
}

For streaming, any server component that is wrapped in <Suspense> causes the route to stream. The server sends HTTP with Transfer-Encoding: chunked, flushes the synchronous content immediately, and appends resolved content as async work completes.

Middleware Execution at the Edge

Next.js Middleware runs before the request reaches the routing layer. It executes in the Edge Runtime: a V8 isolate environment without access to Node.js APIs like fs or net.

Middleware runs on every request (or a subset you configure with a matcher) and can:

Read and modify request headers
Rewrite the URL (transparently change which route handles the request)
Redirect to a different URL
Return a response directly (short-circuit the routing pipeline)
Read cookies and make authentication decisions

// middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function middleware(request: NextRequest) {
  const token = request.cookies.get("session")?.value;

  if (!token && request.nextUrl.pathname.startsWith("/dashboard")) {
    return NextResponse.redirect(new URL("/login", request.url));
  }

  // Add tenant context via header for downstream server components
  const tenantId = resolveTenantId(request.headers.get("host") ?? "");
  const response = NextResponse.next();
  response.headers.set("x-tenant-id", tenantId);
  return response;
}

export const config = {
  matcher: ["/dashboard/:path*", "/api/:path*"],
};

The Edge Runtime constraint is intentional: it enables Middleware to run at CDN edge locations with low latency (sub-millisecond cold start), close to the user. The tradeoff is no access to Node.js built-ins. Any heavy logic (crypto, filesystem reads, database connections) belongs in Route Handlers or server components, not Middleware.

Server Actions as RPC-over-HTTP

Server Actions are functions marked with "use server" that execute on the server when called from a client component. Under the hood, each Server Action becomes an HTTP POST endpoint. The framework automatically handles serialization and deserialization.

When you call a Server Action from a form action attribute, the request is a standard application/x-www-form-urlencoded POST. When called programmatically from JavaScript, it is an application/json POST with serialized arguments. This dual behavior is how progressive enhancement works: the form submission path functions without JavaScript, and the JavaScript path provides a better UX when JS is available.

// actions.ts
"use server";

import { revalidatePath } from "next/cache";

export async function createComment(formData: FormData) {
  const text = formData.get("text") as string;
  const postId = formData.get("postId") as string;

  await db.comments.create({ text, postId });
  revalidatePath(`/posts/${postId}`);
}

// CommentForm.tsx (client component)
"use client";

import { createComment } from "./actions";

export function CommentForm({ postId }: { postId: string }) {
  return (
    <form action={createComment}>
      <input type="hidden" name="postId" value={postId} />
      <textarea name="text" required />
      <button type="submit">Post</button>
    </form>
  );
}

The generated POST endpoint has an opaque URL (something like /_next/server-action/[hash]). The hash is derived from the action’s module path and export name at build time. The server validates the action ID and only executes known registered actions, preventing arbitrary code execution via forged requests.

Server Actions do not require separate API route files, removing the boilerplate of creating Route Handlers for common mutations. The tradeoff is that they are less visible as API contracts and harder to test in isolation compared to explicit Route Handlers.

Tradeoffs Comparison

	Next.js	Remix	Astro	SvelteKit	Nuxt
Server rendering model	RSC + SSR streaming	SSR with loaders	Islands / SSR / SSG	SSR / SSG	SSR / SSG
Data loading	Async server components + fetch caching	Route loaders with `defer`	`getStaticProps`-style or fetch in components	`load()` per page/layout	`useFetch`, `useAsyncData`
Caching strategy	Four-layer (request, data, route, router)	HTTP cache headers only	Build-time + CDN	Per-load cache control	Per-fetch `getCachedData`
Routing	Filesystem, nested layouts	Filesystem, nested layouts	Filesystem + content collections	Filesystem	Filesystem
Client bundle size	Medium (RSC reduces payload; client components still ship)	Medium (all route modules are client bundles)	Very small (islands only)	Small (Svelte compiler output)	Medium (Vue runtime)
Edge support	Middleware + Edge Runtime (partial)	Full Edge via Remix adapters	Full edge with Cloudflare adapter	Full edge with Cloudflare adapter	Full edge with Nitro
Streaming	First-class via Suspense	First-class via `defer`	Limited	First-class	First-class
Sweet spot	Full-stack React apps, complex data requirements, large teams	Form-heavy apps, progressive enhancement focus	Content sites, blogs, documentation	Greenfield projects wanting minimal JS	Vue ecosystem teams

Production Considerations

Cache invalidation debugging. The four-layer cache is the most common source of confusing behavior in production. When data appears stale after a mutation, work through the layers in order: did revalidatePath or revalidateTag run? Did it match the correct route or tag? Is the Router Cache on the client still serving old data? Adding console.log in server components during a next dev session and checking the .next/cache directory reveals a lot.

Self-hosted deployment differences. On Vercel, the Data Cache and Full Route Cache are backed by shared infrastructure that works across multiple instances automatically. In standalone mode (output: "standalone" in next.config.js), both caches default to the local filesystem. On a multi-instance deployment behind a load balancer, each instance has its own isolated cache. Cache entries written on instance A are not visible on instance B. The fix is to configure a shared cache handler using a Redis-backed implementation, which Next.js supports via cacheHandler in next.config.js.

Middleware scope creep. Because Middleware runs on every matched request, including static file requests if your matcher is too broad, it can add latency at scale. Keep Middleware lightweight: token validation, header manipulation, redirects. Never do database queries or heavy computation in Middleware. If you need database access, pass context via headers to a server component and do the work there.

Server Actions and CSRF. Server Actions include built-in CSRF protection for same-origin requests via Origin header validation. For non-browser clients or cross-origin scenarios, you need explicit token validation. Also be aware that Server Action endpoints are discoverable by inspecting client bundles. Treat any data the action receives as untrusted input and validate at the server boundary.

Turbopack in production. As of 2026, Turbopack is stable for development (next dev --turbopack) but next build still uses the webpack pipeline by default in most setups. If you are using webpack-specific plugins or custom loaders in your Next.js config, test Turbopack compatibility before switching fully.

Bundle analysis. The client bundle is easy to underestimate. A server component that imports a large utility but inadvertently passes a non-serializable prop to a Client Component will cause that utility’s transitive dependencies to appear in the client bundle. The @next/bundle-analyzer package and ANALYZE=true next build make this visible. Run bundle analysis before each major release, not just at project start.

Next.js App Router is genuinely complex infrastructure. The complexity mostly reflects real problems: streaming partial renders across a network, coordinating caches at multiple granularities, splitting a component tree across two execution environments. Once the underlying mechanics are clear, the API decisions start to feel less arbitrary and the failure modes become predictable.

More in Web Engineering

Web Engineering · Jun 19, 2026

How Rspack Works Internally: Webpack-Compatible Module Graph, Rust Compilation Pipeline, and the Incremental Build Architecture Behind the Fastest Webpack Replacement

A deep dive into Rspack's Rust-based architecture, module graph construction, SWC transformation pipeline, webpack compatibility layer, incremental compilation, and what the tradeoffs look like for teams migrating from webpack.

Web Engineering · Jun 19, 2026

How Turbopack Works Internally: Incremental Computation, Function-Level Caching, and the Rust-Based Bundler Architecture Behind Next.js

A deep dive into Turbopack's architecture covering the Turbo engine's incremental computation model, function-level caching, Rust-based module resolution, granular HMR invalidation, SWC integration, persistent caching, and how it compares to webpack, Vite, esbuild, and Rspack.

Web Engineering · Jun 15, 2026

How gRPC Works: Protocol Buffers, HTTP/2 Multiplexing, and Bidirectional Streaming From Service Definition to Wire Format

A deep dive into gRPC internals: Protocol Buffer IDL and the buf codegen pipeline, HTTP/2 stream multiplexing and HPACK header compression, all four RPC patterns with TypeScript, channel management, deadline propagation, interceptors, load balancing from pick-first to xDS, the health checking protocol, and production tradeoffs vs REST and GraphQL.

Web Engineering · Jun 4, 2026

How Node.js Works Internally: The Event Loop, libuv Thread Pool, and Async I/O Architecture From require() to Process Exit

A deep dive into Node.js internals covering V8 JIT compilation, the six-phase libuv event loop, thread pool mechanics, microtask queue priority, async/await desugaring, CommonJS versus ESM module resolution, and production tuning considerations with TypeScript examples.

← All articles More Web Engineering →