How does Soft Navigation operate in Next.js App Router under the hood?

During navigation, the browser avoids full document reloads. It issues a background fetch for the target route's Flight Payload (via the RSC: 1 header). The client-side React runtime parses the stream, loads missing client component JS chunks, and reconciles the virtual DOM, updating only changed route segments while preserving active state across unaffected components.

Do Server Components undergo client-side re-hydration during Soft Navigation?

No. Server Components contain zero client JavaScript and do not hydrate. The browser reconciler directly mounts the pre-computed virtual DOM nodes from line 'J' of the Flight stream. Hydration occurs exclusively for Client Components referenced via 'I' markers.

How does Next.js handle version mismatch (Version Skew) during client navigation?

When a user navigates after a new deployment, the requested Flight stream references updated JS chunk hashes missing from the user's stale client session. Upon encountering chunk load errors or manifest discrepancies, Next.js falls back to a Hard Navigation (full document reload) to cleanly synchronize the client with the new release.

What is the React Flight Protocol and how does it fundamentally differ from standard JSON?

React Flight is a specialized streaming serialization format designed to transmit virtual component trees from server to client. Unlike JSON, Flight supports cyclic object references, native Date, Map, Set, and BigInt primitives, virtual JSX element hierarchies, streaming unresolved Promises, and Client Reference descriptors pointing to JavaScript bundles.

Why cannot standard callback functions cross the Flight boundary, while Server Actions can?

Standard functions depend on local memory closures and execution contexts that cannot cross process boundaries between Node.js and the browser. Server Actions do not serialize function code; they serialize a cryptographically signed RPC endpoint identifier. When called on the client, the action dispatches an HTTP POST request back to the server where the actual function executes.

What role does the Client Component Manifest play in Turbopack compilation?

The manifest is a build-time JSON map generated by Turbopack linking client component module IDs to actual hashed JavaScript chunks on disk. When the server encounters a client boundary, it consults the manifest to emit accurate Resource Hints and chunk references in the Flight stream.

How does the React 19 Taint API interact with the Flight Protocol serializer?

When an object is marked via experimental_taintObjectReference, React registers it in an internal security registry. During Flight serialization, if the serializer encounters this tainted object inside client component props, it immediately aborts with a security violation, preventing credential or sensitive record leakage.

How does the Flight Protocol serialize unresolved Promises?

The server transmits a promise descriptor with an assigned ID (marker 'P'). The client reconciler mounts a pending promise placeholder. Once the backend async task resolves, the server pushes an update chunk bearing the same ID. The client React 19 use(promise) hook unblocks, transitioning the Suspense boundary to resolved state.

Deep Dive: RSC Protocol and Internal Architecture — Next.js 16 App Router

Why This Matters#

For standard product development, high-level heuristics often suffice: "components are server-side by default," and interactivity requires 'use client'. However, for Staff/Lead architects and Senior engineers, surface-level familiarity falls short.

As applications scale to hundreds of routes and millions of concurrent users, critical low-level architectural questions inevitably emerge:

In what physical wire format does the server transmit the rendered virtual tree to the client, if it is neither raw HTML nor standard JSON?
How does the browser execute component Reconciliation during page transitions without document reloads while preserving existing client component state?
Why do native Date, BigInt, Map, Set, and streaming Promise instances cross the network boundary seamlessly, while functions and class instances trigger fatal serialization errors?

A granular grasp of the React Flight Protocol and Turbopack compiler internals enables engineering leaders to design high-throughput systems with minimal overhead and isolate complex production failures rapidly.

Mental Model#

Rendering and delivering React Server Components is not a one-off HTML generation step; it is a streaming pipeline linking two distinct runtimes (Node.js/Edge and Browser).

Upon initial page landing, the server streams the initial HTML shell (for immediate First Contentful Paint, FCP) bundled with the inline Flight Payload stream.

During subsequent in-app navigation via <Link>, however, the browser does not reload the HTML document. Instead, it executes Soft Navigation: the browser dispatches a background fetch with the RSC: 1 HTTP request header (or ?_rsc=... query param), streaming raw Flight instructions directly.

text

CLIENT (Browser)                                    SERVER (Node.js/Edge)
   │                                                         │
(1)│── Click <Link href="/analytics"> ───────────────────────►│
   │   GET /analytics?_rsc=123 (Header RSC: 1)               │
   │                                                         │
(2)│                                                         │ 1. Execute Server Components
   │                                                         │ 2. Serialize to Flight Protocol
   │                                                         │    - Resource Hints: H
   │                                                         │    - Client References: I
   │                                                         │    - UI Virtual Tree: J
   │                                                         │
(3)│◄── Stream RSC Flight Payload (Chunks) ──────────────────┤
   │                                                         │
(4)│ 1. Parse Flight stream                                  │
   │ 2. Turbopack loads matching JS chunks (I)               │
   │ 3. React Reconciler diffs virtual DOM                   │
   │ 4. Update UI WITHOUT full page reload!                  │
   │    (Active Client Component state preserved)            │

RSC Protocol Request Processing Lifecycle

1. Execution in Server Runtimeserver

The server runs component functions, resolves asynchronous database calls, and produces virtual element nodes.

2. Serialization to React Flight Wire Formatflight

The tree serializes to a string stream. Server nodes convert into JSON tags, and client components into Client Reference descriptors.

3. Taint API Security Enforcementsecurity

The React runtime inspects outgoing props. If an object marked with a taint label is encountered, serialization halts with a security error.

4. Streaming Chunk Deliverystream

Flight chunks stream via HTTP. The browser processes leading lines before upstream components finish rendering.

5. Reconciliation & Selective Hydrationclient

Client-side React mounts the updated subtree into the live DOM, resolves chunk keys against the Client Component Manifest, and hydrates interactivity.

CHECKPOINT #1

Understanding Check: Soft Navigation Mechanics in App Router

+15 XP

What does the browser request from the server when a user clicks an internal <Link href='/analytics'> in Next.js App Router?

Syntax and API: React Flight Protocol#

Over the wire, the Flight Payload consists of plain text lines delimited by newlines (\n). Each line begins with a character prefix denoting its instruction type:

text

H["/static/css/app.css","stylesheet"]
I["(app-pages-browser)/./components/Counter.tsx",["static/chunks/counter.js"],"Counter"]
J0:["$","div",null,{"className":"container","children":[
  ["$","h1",null,{"children":"Control Panel"}],
  ["$","$L1",null,{"initialCount":10}]
]}]

H (Resource Hint): A Resource Hint triggering concurrent background downloads for styles and fonts.
I (Client Module Import): An entry in the Client Component Manifest, instructing the browser which JS chunk to fetch.
J (JSON Element Tree): Serialized virtual element tree. The $ symbol denotes React.createElement, while $L1 references the client module imported on line I.

Interactive Flight Stream Inspector#

React Flight Protocol Inspector (RSC Stream)

Inspect the raw binary-text serialization protocol of React Server Components

STREAMING LIVE

Outgoing Soft Navigation HTTP Request:

RSC: 1

Requests Flight stream instead of full HTML

Next-Router-State-Tree

Transmits client snapshot tree for subtree reconciliation

Next-Router-Prefetch: 1

Prefetch flag sent by <Link>

text/x-component stream chunks:Click any chunk

Client Reference (I)Client Reference Manifest ('use client' Directive)

1:I["./components/MetricCard.tsx",["chunks/metric_card_client.js"],"default"]

Serialized JSX AST (0)Serialized Element Tree (JSX Stream)

0:{"name":"AnalyticsPage","children":["$","div",null,{"className":"p-6","children":["$","$L1",null,{"metric":"visitors"}]}]}

Lazy Slot Promise ($L1)Async Promise Resolution (Suspense Stream)

2:L1:{"value":14280,"status":"fresh","timestamp":1741859200}

Client Reference (I)

Client Reference Manifest ('use client' Directive)

The server never transmits the source code of MetricCard. Instead, it sends an export pointer to a JS bundle chunk that the browser loads and hydrates.

Architectural Advantage:

The remaining 90% of page code stays on the server with zero client bundle overhead (Zero-Bundle Size).

Next.js 16 Optimization: The client-side Flight Payload parser was rewritten to a two-phase native JavaScript parser, accelerating deserialization by 350%.

React Flight Protocol Serialization Matrix (Wire Format)

Критерий	Supported in Flight (Safe to pass)	Forbidden in Flight (Serialization Error)
Primitive Types	string, number, boolean, null, undefined, BigInt	Symbol (except those registered via Symbol.for)
Complex Structures	Plain Objects, Arrays, Map, Set, TypedArrays, ArrayBuffer	Custom class instances with methods (OOP instances)
Temporal Entities	Date (preserved as a native temporal object)	RegExp, Generator Functions
Asynchronous Types	Promise (streamed as chunks and unwrapped via use())	AsyncGenerator, WebSockets, ReadableStream (in props)
Functions & Code	Server Actions (with 'use server', serialized as RPC IDs)	Standard client/server closures and event handlers (onClick)
React Elements	JSX Elements (children, slots generated on server)	React Context objects, mutable Ref instances (useRef)

Practical Patterns#

Pattern 1: Safe DTO Projection Preserving Native Types#

React Flight natively serializes Date and BigInt. Never employ the destructive JSON.parse(JSON.stringify()) hack! Project database rows through explicit typed DTOs:

tsxlib/dto/order.ts (Safe DTO)

export interface OrderDTO {
  id: string;
  totalAmount: bigint;     // Flight natively serializes BigInt!
  createdAt: Date;         // Flight natively serializes Date!
  metadata: Map<string, string>; // Flight natively serializes Map!
}

export function toOrderDTO(raw: {
  id: string;
  total: bigint;
  created_at: Date;
  meta: Record<string, string>;
}): OrderDTO {
  return {
    id: raw.id,
    totalAmount: raw.total,
    createdAt: raw.created_at,
    metadata: new Map(Object.entries(raw.meta)),
  };
}

tsxapp/orders/[id]/page.tsx (Server Component)

import { db } from '@/lib/db';
import { toOrderDTO } from '@/lib/dto/order';
import { ClientOrderView } from './ClientOrderView';

interface PageProps {
  params: Promise<{ id: string }>;
}

export default async function OrderPage({ params }: PageProps) {
  const { id } = await params;
  const rawOrder = await db.order.findUniqueOrThrow({ where: { id } });

  // Transform raw database row into safe DTO with native types
  const orderDTO = toOrderDTO(rawOrder);

  // Delivered to client: Date, BigInt, and Map are retained without loss!
  return <ClientOrderView order={orderDTO} />;
}

Pattern 2: Server Actions as Encrypted RPC Descriptors#

When a function tagged with 'use server' is passed to a Client Component (for instance, via .bind()), the React runtime encrypts bound arguments using Action Closure Encryption:

tsxapp/users/page.tsx (Secure Server Action Prop)

import { deleteUserAction } from '@/app/actions/user';
import { DeleteUserButton } from './DeleteUserButton';

export default async function UsersPage() {
  const userId = 'usr_98741';

  // .bind() encrypts arguments into a closed cryptographic token in Flight Payload!
  // The client receives only an opaque RPC reference: $F1 = ["$ACTION_ID_123", ["usr_98741"]]
  const boundDelete = deleteUserAction.bind(null, userId);

  return <DeleteUserButton onDelete={boundDelete} />;
}

CHECKPOINT #2

Understanding Check: React Flight Native Serialization vs. JSON

+15 XP

Why is executing JSON.parse(JSON.stringify(data)) prior to passing props from Server Components to Client Components considered a harmful anti-pattern?

Common Pitfalls & Edge Cases#

Ошибка: The JSON.parse(JSON.stringify()) Anti-pattern: Destroys Flight Types

Attempting to sanitize props with JSON.parse(JSON.stringify(data)) breaks native types:

Date instances become ISO 8601 strings, forcing manual new Date() calls on the client.
BigInt primitives throw a fatal TypeError: Do not know how to serialize a BigInt.
Map and Set collections collapse into empty {} objects.

React Flight natively supports Date, BigInt, Map, Set, and ArrayBuffer!

Mitigation: Map query results through typed DTO functions without invoking JSON.stringify.

Ошибка: Data Leakage and Flight Payload Bloat from Oversized .bind() Closures

When binding arguments to Server Actions passed to Client Components, Next.js encrypts all bound arguments and ships them to the client in the Flight stream. Binding a 10,000-item array or internal API credentials bloats the payload by megabytes and exposes private server state to client devices.

Mitigation: Only bind minimal scalar identifiers (entity IDs). Resolve heavy dependencies and secrets server-side inside the Server Action body.

tsxSafe Identifier Passing in Server Actions

// ❌ DANGEROUS: Private API key leaks into bound action payload
// const boundAction = deleteUser.bind(null, userId, secretApiKey);

// ✅ CORRECT: Pass only public entity ID
// const boundAction = deleteUser.bind(null, userId);

Ошибка: Navigation Failures During Production Deployments (Version Skew)

A user opens a page on deployment v1. You roll out v2, altering JS chunk hashes. The user clicks a link:

The browser requests ?_rsc=... and receives a Flight Payload from v2.
The payload contains an I line with hash chunk-v2-abc.js.
The browser attempts to fetch the chunk, but stale CDN caches or missing assets return 404.

How Next.js Recovers: Next.js detects the version mismatch and automatically executes a Hard Navigation (full document reload), smoothly synchronizing the client to v2.

Ошибка: Direct Prop Mutation on the Client Breaks Subsequent Reconciliation

Objects deserialized from the Flight Payload are sealed by React using Object.freeze. Mutating props.user.name = 'Updated' throws an exception in strict mode or corrupts the reconciler on subsequent visits.

Senior / Staff Engineering Interview Q&A#

Interview Questions8 questions

Deep Dive: RSC Protocol and Internal Architecture

Why This Matters#

Mental Model#

1. Soft Navigation Architecture#

Syntax and API: React Flight Protocol#

Interactive Flight Stream Inspector#

React Flight Protocol Inspector (RSC Stream)

Client Reference Manifest ('use client' Directive)

Practical Patterns#

Pattern 1: Safe DTO Projection Preserving Native Types#

Pattern 2: Server Actions as Encrypted RPC Descriptors#

Common Pitfalls & Edge Cases#

Ошибка: The JSON.parse(JSON.stringify()) Anti-pattern: Destroys Flight Types

Ошибка: Data Leakage and Flight Payload Bloat from Oversized .bind() Closures

Ошибка: Navigation Failures During Production Deployments (Version Skew)

Ошибка: Direct Prop Mutation on the Client Breaks Subsequent Reconciliation

Senior / Staff Engineering Interview Q&A#

Why This Matters#

Mental Model#

1. Soft Navigation Architecture#

Syntax and API: React Flight Protocol#

Interactive Flight Stream Inspector#

React Flight Protocol Inspector (RSC Stream)

Client Reference Manifest ('use client' Directive)

Practical Patterns#

Pattern 1: Safe DTO Projection Preserving Native Types#

Pattern 2: Server Actions as Encrypted RPC Descriptors#

Common Pitfalls & Edge Cases#

Ошибка: The JSON.parse(JSON.stringify()) Anti-pattern: Destroys Flight Types

Ошибка: Data Leakage and Flight Payload Bloat from Oversized .bind() Closures

Ошибка: Navigation Failures During Production Deployments (Version Skew)

Ошибка: Direct Prop Mutation on the Client Breaks Subsequent Reconciliation

Senior / Staff Engineering Interview Q&A#