---
title: "'use client' Directive Deep Dive: To the Edge of Client Boundaries"
tags:
- react
- nextjs
- frontend
published: true
date: 2026-05-01 12:00:00
description: "Module boundaries created by a single line of 'use client', build-time transformations, Flight serialization, and performance implications"
thumbnail: /thumbnails/2026/05/use-client-deep-dive.png
series: Directive Deep Dive
seriesOrder: 1
---
## Table of Contents
## Introduction
```tsx
'use client'
import {useState} from 'react'
export function Counter() {
const [count, setCount] = useState(0)
return
}
```
A single line: `'use client'`. The moment you write this at the top of a file, the meaning of this module changes. It's not simply a marker saying "code that runs on the client." More precisely, it's a marker that **this module is an entry point of the client bundle graph**. **The RSC renderer does not evaluate the body of this module.** Instead, it stops at the module boundary and serializes only a **reference** indicating "there's a client component here." However, the same component runs in a separate SSR layer on Next.js's initial response path, participating in initial HTML generation. **This means there isn't just one server-side rendering path — the RSC renderer creates a Flight Payload from the server component tree, and the SSR renderer consumes that result to generate initial HTML. In this process, client components are also rendered using their SSR build implementation.** We'll cover this distinction separately later.
In [a previous article](/2026/03/react-server-functions-deep-dive), we followed how `'use server'` transforms functions into RPC endpoints all the way to the end. This article goes in the opposite direction. When a client component appears in the middle of a server component tree, how are modules separated at build time, what tokens flow through the Flight stream at runtime, and how does the client load chunks and bring them to life as actual components?
Let's start by clarifying terminology.
- **Client Component**: A component exported from a `'use client'` module and used as a React element type. It runs on the client (or during SSR) and can use hooks, event handlers, and state.
- **Client Reference**: A metadata object that the RSC server uses instead of directly holding the value of a `'use client'` module export. It has `$$typeof`, `$$id`, and `$$async` properties. It could be a component function or any other export that can be passed as props to a Client Component.
- **Client Module Proxy**: A Proxy created at the module level. No matter which export you access, it generates a client reference for that export.
> The source code analysis in this article is based on **React 19.2** and **Next.js 16.2**. Internal implementations may vary depending on the version.
>
> Also, the code examples in this article follow the webpack path. While `next dev` defaults to Turbopack starting from Next.js 16, the `'use client'` handling in both bundlers is nearly identical — the core behavioral differences are covered separately in the [What's Different in Turbopack](#whats-different-in-turbopack) section later in the article.
## 'use client' is an Entry Point Marker
There's a common misconception we need to address first: the idea that "only components with `'use client'` become client components, and components they import need separate marking." It's exactly the opposite.
The `'use client'` directive **defines module graph boundaries**. More precisely, it's the starting point of a **unidirectional boundary** from server → client. When a module has `'use client'`, all modules it imports — even without their own `'use client'` — are automatically included in the client bundle graph.
```
app/page.tsx ← Server Component (default)
└─ import Layout ← Server Component
└─ import Counter ← 'use client' (boundary!)
└─ import { format } from './utils' ← automatically client
└─ import lodash ← automatically client
```
Conversely, a `'use client'` module cannot directly import server modules again. The import direction is one-way. However, **receiving server components through the `children` prop** is possible. This isn't importing — it's receiving serialized React elements passed as props. This is the most important mental model for `'use client'`.
```tsx
// app/page.tsx (Server Component)
import {ClientShell} from './ClientShell'
import {ServerContent} from './ServerContent'
export default function Page() {
return (
{/* OK — passed as children prop */}
)
}
```
```tsx
// ClientShell.tsx
'use client'
export function ClientShell({children}: {children: React.ReactNode}) {
return
{children}
}
```
`ClientShell` does not **import** `ServerContent`. The Server Component `Page` imports both components and composes them with children. This distinction underpins the entire composition model of React Server Components.
## Build-Time Transformation: Same Module, Different Builds per Layer
The `'use client'` directive has no runtime effect. The real work happens at **build time**. Moreover, a single module gets compiled into different forms across webpack's multiple layers — RSC server, SSR, browser client. It's the same file, but different transformation rules apply per layer.
### RSC Server Bundle: Stub with Body Removed
Next.js's `next-flight-loader` operates in webpack's RSC server layer and, when it encounters a `'use client'` module, **discards the entire original code** and replaces it with client references. For ESM modules, the transformation looks like this[^1]:
```ts
// Original: components/Counter.tsx
'use client'
import {useState} from 'react'
export function Counter({initial}: {initial: number}) {
const [count, setCount] = useState(initial)
return
}
```
The above code is transformed into something like this in the RSC server bundle:
```js
// Form that goes into RSC server bundle (conceptual)
import {registerClientReference} from 'react-server-dom-webpack/server'
export const Counter = registerClientReference(
function () {
throw new Error(
'Attempted to call Counter() from the server but Counter is on the client. ' +
"It's not possible to invoke a client function from the server, " +
'it can only be rendered as a Component or passed to props of a Client Component.',
)
},
'components/Counter.tsx',
'Counter',
)
```
Three key points:
1. **The original function body is gone.** `useState`, JSX, event handlers — code that only makes sense on the client isn't included in the RSC server bundle by even a single character.
2. **Metadata is injected into the stub function.** `registerClientReference` injects `$$typeof`, `$$id`, and `$$async`. When RSC serialization encounters this stub, it converts it to metadata instead of the body.
3. **Calling the stub throws an error.** When you mistakenly try to call it "like a function" on the server, it throws a clear error. Client components are targets for React to render, not functions to call directly.
For CommonJS modules, it takes a simpler path — replacing the entire module with a Proxy from `createClientModuleProxy` (covered later).
### Client Bundle: Original As-Is
The same module keeps its body intact in the client bundle. Webpack's client layer essentially ignores the `'use client'` directive (except for linting) and compiles the module as regular JavaScript. As a result, the real implementation of the `Counter` component **exists only in the client chunk**.
```
Original module → ┬─ RSC server build: metadata stub only
└─ Client build: body as-is + separate chunk
```
This separation is possible thanks to webpack's **layer** mechanism. Next.js defines multiple layers within the same webpack compilation — `WEBPACK_LAYERS.reactServerComponents` (RSC), `WEBPACK_LAYERS.serverSideRendering` (SSR), `WEBPACK_LAYERS.actionBrowser` (action browser), etc.[^2] — and applies different transformations to the same module depending on which layer imports it.
### Inside registerClientReference
Let's look directly at the React implementation. The answer is in `react-server-dom-webpack/src/ReactFlightWebpackReferences.js`[^3].
```js
const CLIENT_REFERENCE_TAG = Symbol.for('react.client.reference')
export function registerClientReference(proxyImplementation, id, exportName) {
return registerClientReferenceImpl(
proxyImplementation,
id + '#' + exportName,
false, // async = false
)
}
function registerClientReferenceImpl(proxyImplementation, id, async) {
return Object.defineProperties(proxyImplementation, {
$$typeof: {value: CLIENT_REFERENCE_TAG},
$$id: {value: id},
$$async: {value: async},
})
}
```
This is a mirror image of the `registerServerReference` we saw with server references (`'use server'`). The differences:
| Property | Client Reference | Server Reference |
| ---------- | -------------------------------------- | -------------------------------------- |
| `$$typeof` | `Symbol.for('react.client.reference')` | `Symbol.for('react.server.reference')` |
| `$$id` | `"moduleId#exportName"` | `"moduleId#exportName"` |
| `$$async` | Whether module uses top-level await | (none) |
| `$$bound` | (none) | Arguments accumulated by `.bind()` |
`$$async` is new. It indicates whether the module is asynchronous (top-level await, etc.). When loading chunks on the client side, it determines whether to finish with a synchronous require or await a Promise.
### createClientModuleProxy: Wrapping Entire Modules at Once
For CJS paths or cases where automatic manifest generation is difficult, the entire module is wrapped as a client reference at once. This is where `createClientModuleProxy` is used.
```js
export function createClientModuleProxy(moduleId) {
const clientReference = registerClientReferenceImpl({}, moduleId, false)
return new Proxy(clientReference, proxyHandlers)
}
const proxyHandlers = {
get: function (target, name, receiver) {
return getReference(target, name)
},
getOwnPropertyDescriptor: function (target, name) {
let descriptor = Object.getOwnPropertyDescriptor(target, name)
if (!descriptor) {
descriptor = {
value: getReference(target, name),
writable: false,
configurable: false,
enumerable: false,
}
Object.defineProperty(target, name, descriptor)
}
return descriptor
},
getPrototypeOf(target) {
return PROMISE_PROTOTYPE
},
set: function () {
throw new Error('Cannot assign to a client module from a server module.')
},
}
```
It creates a ClientReference with a module ID embedded in an empty object `{}`, then wraps it with a Proxy. The `get` trap of this Proxy is key — no matter which export name you access, `getReference(target, name)` gets called.
```js
function getReference(target, name) {
switch (name) {
case '$$typeof':
return target.$$typeof
case '$$id':
return target.$$id
case '$$async':
return target.$$async
case 'name':
return target.name
case 'defaultProps':
return undefined
case '_debugInfo':
return undefined
case 'toJSON':
return undefined
case Symbol.toPrimitive:
return Object.prototype[Symbol.toPrimitive]
case Symbol.toStringTag:
return Object.prototype[Symbol.toStringTag]
case '__esModule':
// ESM interop. Makes even default export lazy.
target.default = registerClientReferenceImpl(
function () {
throw new Error('...')
},
target.$$id + '#',
target.$$async,
)
return true
case 'then':
if (target.then) return target.then // cache hit
if (!target.$$async) {
// Sync module: masquerade as thenable.
// Create a then that holds itself as fulfilled value.
const clientReference = registerClientReferenceImpl(
{},
target.$$id,
true /* async */,
)
const proxy = new Proxy(clientReference, proxyHandlers)
target.status = 'fulfilled'
target.value = proxy
const then = (target.then = registerClientReferenceImpl(
function then(resolve, reject) {
return Promise.resolve(resolve(proxy))
},
target.$$id + '#then',
false,
))
return then
}
// async module: undefined. webpack handles its own thenable processing.
return undefined
}
if (typeof name === 'symbol') {
throw new Error(
'Cannot read Symbol exports. Only named exports are supported.',
)
}
// Other named exports — dynamically create and cache ClientReference
let cachedReference = target[name]
if (!cachedReference) {
const reference = registerClientReferenceImpl(
function () {
throw new Error('...')
},
target.$$id + '#' + name,
target.$$async,
)
Object.defineProperty(reference, 'name', {value: name})
cachedReference = target[name] = new Proxy(reference, deepProxyHandlers)
}
return cachedReference
}
```
When you first access an export called `Counter`, it creates a ClientReference with the ID `"components/Counter.tsx#Counter"` and caches it. From the second access onwards, it returns the same object. Thanks to this lazy creation pattern, there's no need to statically analyze what exports a module has at build time — they're created when accessed.
The `then` branch is most interesting. It works slightly counterintuitively.
- **Sync module** (`!$$async`) when accessing `then`: Dynamically creates and returns a `then` function. This then is a function that immediately resolves with itself (proxy). In other words, even though it's a sync module, it **makes it look like a thenable** externally, allowing it to pass through dynamic import's await path. This is a mechanism to ensure that when RSC server does `await import('./ClientCounter')`, it receives the module object without infinite loops or errors.
- **Async module** (`$$async`) when accessing `then`: Returns `undefined`. Since webpack handles async modules with a separate mechanism for thenable processing, we shouldn't create a then.
The `getPrototypeOf` returning `PROMISE_PROTOTYPE` follows the same logic. Since dynamic import results are Promises, making the client module Proxy's prototype look like `Promise.prototype` means external code can treat this object like a Promise without major issues. (Since the exact intent isn't directly documented in the React source, take the above reasoning as "the behavior is natural when treated this way" level interpretation.)
The `set` trap is firm — any attempt to overwrite a client module's export from server code always throws.
### Next.js's next-flight-loader: Two-Pronged Transformation
The entity that applies the above transformations on the Next.js side is `next-flight-loader`[^1]. It automatically detects module type (ESM/CJS) and handles them differently.
- **ESM**: Wraps each export with `registerClientReference(stub, resourceKey, exportName)` and replaces it with a stub. Only allows explicit named exports. Rejects `export *` — if you can't know what names are exported at build time, you can't create stubs.
- **CJS**: Replaces the entire module with a single line: `createProxy(resourceKey)`. Since it doesn't know what exports exist, it relies on the Proxy's lazy creation.
`resourceKey` is in the form of file path + additional query string. This is to distinguish cases where multiple exports are created from the same file, or when barrel optimizer splits different parts of the same file into different modules.
> **Summary so far.** Once the build is complete, the RSC server bundle contains not a single line of actual client component code. Only stubs with `moduleId#exportName` format IDs and `$$typeof`/`$$id`/`$$async` metadata remain. The real component body is stored separately in SSR bundles and client bundles. These stubs get converted to import chunk metadata during RSC serialization, and that transformation is the subject of the next section.
## Client Entry Point: flight-client-entry-plugin
Webpack fundamentally starts from an entry point and creates chunks by following the import graph. However, in RSC, server code doesn't import `'use client'` modules — the imports themselves have been transformed into `registerClientReference` calls. So how does webpack know about the existence of client modules?
Answer: **Create additional separate entry points**. This is the role of `flight-client-entry-plugin`[^2].
```
Server entry (RSC)
└─ Server Component
└─ "ClientShell exists here" (registerClientReference)
Client entry (auto-generated)
├─ ClientShell.tsx (actual code)
└─ Counter.tsx (actual code)
```
The plugin workflow goes like this:
1. `createClientEntries()` iterates through the entries of the server compilation.
2. `collectComponentInfoFromServerEntryDependency()` follows the dependency graph of each entry, examining build metadata (RSC meta information prepended by the loader) to identify client components and server actions.
3. `injectClientEntryAndSSRModules()` bundles the identified client modules as entries and injects them into webpack via `next-flight-client-entry-loader`. At this point, **two entries** are created simultaneously — **for client (browser) build** and **for SSR build**.
The reason the same client component gets built twice is SSR. Client components must also be rendered as HTML in the first page response (for progressive enhancement and content visibility before JS execution). Therefore:
- **Client entry**: Chunk to send to the browser. Becomes interactive component after hydration.
- **SSR entry**: For HTML rendering. Runs on a different layer from the RSC server, and results are streamed to the HTML of the first response.
In production, the same code gets built twice. This is an intentional cost.
## Client Manifest: ID → chunk URL
After the build completes, Next.js emits a manifest file called `client-reference-manifest.js`[^4]. This is the dictionary that RSC server references when serializing client references.
```ts
// Form of one manifest entry (conceptual)
{
id: "5234", // webpack module ID
name: "Counter", // export name. '*' means entire module
chunks: [
"12", "static/chunks/12-abc.js", // [chunkId, fileName] pair
"5234", "static/chunks/5234-def.js"
],
async: false,
}
```
This entry goes into several mappings within the manifest.
```ts
interface ClientReferenceManifest {
moduleLoading: {prefix: string; crossOrigin: string | null}
clientModules: Record // key = "moduleId#exportName"
ssrModuleMapping: Record>
edgeSSRModuleMapping: Record>
rscModuleMapping: Record>
edgeRscModuleMapping: Record>
entryCSSFiles: Record
}
```
`clientModules` is used by the RSC server for lookup when serializing client references. `ssrModuleMapping` and `edgeSSRModuleMapping` are used to find the SSR build module ID of the same component during SSR. Since the same component has different module IDs in the RSC layer, SSR layer, and client layer, mapping between them is necessary.
The form of the `chunks` field is somewhat unusual. It's an **alternating pair** — laid out flat like `[chunkId1, fileName1, chunkId2, fileName2, ...]`. It's a flat array rather than nested arrays, so serialization cost is lower. The client reads these pairs two at a time while fetching chunks.
File paths are encoded with `encodeURIPath()`. This is because chunk filenames created by webpack can contain reserved characters like `[`, `]` that can't be used directly as URLs.
## Serialization: serializeClientReference and $L Token
When the RSC server serializes the component tree with Flight Protocol, how does it encode ClientReference when encountered at some position? The answer: **it depends on the position**.
### Function Value Branching
`react-server/src/ReactFlightServer.js`[^5] branches whether a function value is ClientReference or ServerReference while serializing the tree.
```js
if (typeof value === 'function') {
if (isClientReference(value)) {
return serializeClientReference(request, parent, parentPropertyName, value)
}
if (isServerReference(value)) {
return serializeServerReference(request, value)
}
// Regular function that's neither → cannot serialize, error
}
export function isClientReference(reference) {
return reference.$$typeof === Symbol.for('react.client.reference')
}
```
The check is simple. It looks at whether `$$typeof` is the client reference tag.
### Two Branches of serializeClientReference
```js
function serializeClientReference(
request,
parent,
parentPropertyName,
clientReference,
) {
const clientReferenceKey = getClientReferenceKey(clientReference)
const writtenClientReferences = request.writtenClientReferences
const existingId = writtenClientReferences.get(clientReferenceKey)
if (existingId !== undefined) {
// Already serialized reference — reuse chunk
if (parent[0] === REACT_ELEMENT_TYPE && parentPropertyName === '1') {
return serializeLazyID(existingId) // "$L" + hex
}
return serializeByValueID(existingId) // "$" + hex
}
try {
const clientReferenceMetadata = resolveClientReferenceMetadata(
request.bundlerConfig,
clientReference,
)
request.pendingChunks++
const importId = request.nextChunkId++
emitImportChunk(request, importId, clientReferenceMetadata)
writtenClientReferences.set(clientReferenceKey, importId)
if (parent[0] === REACT_ELEMENT_TYPE && parentPropertyName === '1') {
return serializeLazyID(importId)
}
return serializeByValueID(importId)
} catch (x) {
request.pendingChunks++
const errorId = request.nextChunkId++
emitErrorChunk(request, errorId, ...)
return serializeByValueID(errorId)
}
}
function serializeLazyID(id) {
return '$L' + id.toString(16)
}
function serializeByValueID(id) {
return '$' + id.toString(16)
}
```
The key branch is `parent[0] === REACT_ELEMENT_TYPE && parentPropertyName === '1'`. **If the parent is a React element and the current position is the type slot (index 1)**, it becomes a `$L` (lazy) token. In other positions — for example, if a client reference is inside props — it becomes a `$` (by-value reference) token.
Let's recall the serialized form of React elements:
```
["$", "type", null, props]
↑ ↑
element marker
└─ This position is index 1, i.e., the type slot
```
A client reference in the type slot means "this component's code will be loaded lazily." A client reference in props — e.g., when passing a client component as a prop to children — is simply a reference pointing to import metadata.
### Import Chunk: Metadata as Separate Row
`emitImportChunk` emits metadata (`[id, chunks, name, async]`) looked up from the manifest as a separate chunk. Within Flight Protocol's row-based streaming structure, this chunk is serialized as an `I` row.
```
I:5:["5234",["12","static/chunks/12-abc.js"],"Counter",0]
0:["$","$L5",null,{"initial":42}]
```
- `I:5:...` — Chunk 5 is import metadata. `[moduleId, chunks array, exportName, async]` pair.
- `0:["$","$L5",null,{"initial":42}]` — Root element. `$L5` is embedded in the type position.
When the client receives this stream, it looks at the metadata of chunk 5 and begins fetching the chunk URL. Simultaneously, a React lazy component is created in the type slot of the root element — it resolves to the actual `Counter` component when the chunk arrives.
### Client Reference Tokens by Position in Flight Protocol
| Position | Token | Meaning |
| --------------------------------- | --------- | --------------------------------------------------------- |
| React element's type slot | `$L` | Wrapped as lazy node, enabling component-level suspension |
| Other positions (including props) | `$` | By-value reference — ID pointing to import metadata |
What this rule means is this: Client references in element type positions can be interpreted by React as lazy components, so they suspend on a per-component basis. References inside props are passed as regular value references, so they don't automatically take the same lazy processing path as type positions — the result depends on where the consuming side places that reference.
## Client Side: From $L to Actual Components
Now we turn our attention to the client side. When a Flight stream arrives, `react-client/src/ReactFlightClient.js`[^6] parses it line by line. The key function is `parseModelString` — when it encounters a token starting with `$`, it branches based on the second character.
```js
function parseModelString(response, parentObject, key, value) {
if (value[0] === '$') {
switch (value[1]) {
case '$':
return value.slice(1) // escaped $
case 'L': {
const id = parseInt(value.slice(2), 16)
const chunk = getChunk(response, id)
return createLazyChunkWrapper(chunk, 0)
}
case '@': {
const id = parseInt(value.slice(2), 16)
return getChunk(response, id) // Promise
}
case 'S':
return Symbol.for(value.slice(2))
case 'h': {
const ref = value.slice(2)
return getOutlinedModel(
response,
ref,
parentObject,
key,
loadServerReference,
)
}
case 'Q': {
const ref = value.slice(2)
return getOutlinedModel(response, ref, parentObject, key, createMap)
}
case 'W': {
const ref = value.slice(2)
return getOutlinedModel(response, ref, parentObject, key, createSet)
}
case 'B': {
const ref = value.slice(2)
return getOutlinedModel(response, ref, parentObject, key, createBlob)
}
case 'K': {
const ref = value.slice(2)
return getOutlinedModel(
response,
ref,
parentObject,
key,
createFormData,
)
}
case 'D':
return new Date(Date.parse(value.slice(2)))
case 'n':
return BigInt(value.slice(2))
case 'I':
return Infinity
case '-':
if (value === '$-0') return -0
return -Infinity
case 'N':
return NaN
case 'u':
return undefined
// ...
}
}
return value
}
```
Here's the token table we saw in the `'use server'` post, all gathered in one function. `$L` is a new addition.
### $L → React.lazy
```js
case 'L': {
const id = parseInt(value.slice(2), 16)
const chunk = getChunk(response, id)
return createLazyChunkWrapper(chunk, 0)
}
function createLazyChunkWrapper(chunk, validated) {
return {
$$typeof: REACT_LAZY_TYPE,
_payload: chunk,
_init: readChunk,
}
}
```
When it encounters `$L5`, it gets chunk 5 and creates a React lazy component. This has the exact same shape as a lazy component created with `React.lazy()`. When the React reconciler encounters this node, it calls `_init(_payload)` to attempt to resolve the chunk, and if it's still loading, throws a Promise so the nearest Suspense boundary shows its fallback.
### When a chunk is import metadata
Chunk 5 is the import metadata emitted as an `I:5:[...]` line above. When the client encounters this chunk, it follows this flow:
```js
function resolveModuleChunk(response, chunk, value) {
// ClientReference metadata goes into chunk.value
const resolvedChunk = chunk
resolvedChunk.status = RESOLVED_MODULE
resolvedChunk.value = value
// ...
}
function readChunk(chunk) {
switch (chunk.status) {
case RESOLVED_MODULE:
initializeModuleChunk(chunk)
break
}
// ...
switch (chunk.status) {
case INITIALIZED:
return chunk.value
case PENDING:
case BLOCKED:
throw chunk // Suspense
default:
throw chunk.reason
}
}
function initializeModuleChunk(chunk) {
try {
const value = requireModule(chunk.value)
chunk.status = INITIALIZED
chunk.value = value
} catch (error) {
chunk.status = ERRORED
chunk.reason = error
}
}
```
The key is `requireModule(chunk.value)`. `requireModule` is a bundler-specific implementation, and in webpack it works like this[^7]:
```js
// react-server-dom-webpack/src/client/ReactFlightClientConfigBundlerWebpack.js
export function preloadModule(metadata) {
const chunks = metadata[1]
const promises = []
for (let i = 0; i < chunks.length; i += 2) {
const chunkId = chunks[i]
const chunkFilename = chunks[i + 1]
const entry = chunkCache.get(chunkId)
if (entry === undefined) {
const thenable = loadChunk(chunkId, chunkFilename)
promises.push(thenable)
chunkCache.set(chunkId, thenable)
} else if (entry !== null) {
promises.push(entry)
}
}
if (metadata[3] /* async */) {
if (promises.length === 0) {
return requireAsyncModule(metadata[0])
}
return Promise.all(promises).then(() => requireAsyncModule(metadata[0]))
}
return promises.length === 0 ? null : Promise.all(promises)
}
export function requireModule(metadata) {
let moduleExports = __webpack_require__(metadata[0])
// For async modules, access via .value
if (metadata[3] /* async */) {
if (moduleExports.status === 'fulfilled') {
moduleExports = moduleExports.value
} else {
throw moduleExports.reason
}
}
if (metadata[2] /* exportName */ === '*') {
return moduleExports
}
if (metadata[2] === '') {
return moduleExports.__esModule ? moduleExports.default : moduleExports
}
return moduleExports[metadata[2]]
}
```
`metadata` is a `[id, chunks, name, async]` tuple.
1. `preloadModule`: Takes `chunks` pairs and feeds them to `loadChunk` to fetch chunk files. Skips already cached chunks. For sync modules, just receiving chunks is enough; for async modules, it additionally needs to await `requireAsyncModule`.
2. `requireModule`: Resolves the module with `__webpack_require__` and extracts exports based on `name`.
`*` means the entire module, `''` (empty string) means default export (with ESM interop), anything else is a named export. The `name` field in the build-time manifest is determined here.
### chunkCache: Load once and you're done
`chunkCache` is a chunk-level cache, not module-level. If 100 client components share the same chunk — which is common, since webpack creates vendor chunks — that chunk is loaded only once. From the second time onward, it's a cache hit.
What this means: **Even if the same module is imported in multiple places, chunk downloads happen only once on the client side**. RSC payloads include ClientReference metadata every time, but metadata is lightweight (dozens of bytes) and chunk URLs are deduped.
> **Summary so far.** When the RSC server traverses the tree and encounters a client reference, it pulls `[id, chunks, name, async]` from the manifest and emits it as an import chunk. If it's in an element type position, it gets a `$L` token; otherwise, a `$` token. When the client encounters `$L`, it creates a React lazy node, fetches chunks with `preloadModule`, and resolves the actual component with `requireModule` (`__webpack_require__`). Same chunks are deduped via `chunkCache`. This completes the serialization roundtrip — next up is another server-side renderer besides the RSC server: the SSR layer.
## SSR and RSC, and Two Component Trees
This is where mental models start to wobble. The simple picture looks like this:
```
[Browser's first request]
1. HTML rendering on server → Streaming
2. Browser hydration
[Subsequently]
3. Client makes RSC request to server → Receives Flight stream
```
But when RSC enters the picture, the server side becomes more complex:
```
[Browser's first request]
1. RSC server: Renders server component tree as Flight stream
- Client components are serialized as $L + import metadata
2. SSR server (same process, different layer): Receives Flight stream and
- When it encounters $L, requires client modules from SSR build for actual rendering
- Streams result as HTML
3. Browser: Receives and displays HTML + Flight stream + client chunks at the end
4. Hydration: When client chunks arrive, combines HTML and Flight stream to create React tree, attaches event listeners
```
The same Counter component — on the same page — is handled in three different environments:
| Environment | Build layer | Role |
| ---------------- | ----------------------- | ------------------------------------ |
| RSC server | `reactServerComponents` | Only serializes as client reference |
| SSR server | `serverSideRendering` | Actually renders first response HTML |
| Browser (client) | (default) | Hydration + subsequent interaction |
This is why the manifest has separate `ssrModuleMapping` and `clientModules`. For the same `"Counter.tsx#Counter"` key, the SSR layer's module ID and the client layer's module ID are different, and the RSC server needs to hold both mappings. The SSR layer uses `ssrModuleMapping` when consuming RSC payload to get modules via server-side webpack require, while the client uses `clientModules` to fetch chunk URLs.
### 'use client' doesn't prevent SSR either
A frequently asked question: "It's `'use client'`, so why does it render on the server too?" Answer: **SSR doesn't block client components.** Only the RSC server does. The SSR server normally executes client component bodies to create HTML. However, it's static HTML that only reflects initial values like `useState`'s initial state, and event handlers are attached after hydration.
Once you grasp this distinction, you can understand that "code that should never run on the server" — like code accessing `window.localStorage` — will break in SSR too. `'use client'` isn't enough; you need to wrap it in `useEffect` or check `typeof window !== 'undefined'`.
```tsx
'use client'
import {useState, useEffect} from 'react'
export function Theme() {
// ❌ Also runs in SSR. No window → error
// const [theme, setTheme] = useState(localStorage.getItem('theme'))
const [theme, setTheme] = useState(null)
// ✅ Only runs in browser
useEffect(() => {
setTheme(localStorage.getItem('theme'))
}, [])
return
...
}
```
## Props Serialization: What Can You Pass?
When a server component passes props to a client component, those props are **serialized via Flight Protocol** and carried in the RSC payload. The serialization token table covered in the `'use server'` post applies directly.
### Serializable / Non-serializable
| Type | Possible | Notes |
| ------------------------------------------------------------ | -------- | -------------------------------- |
| `string`, `number`, `bigint`, `boolean`, `undefined`, `null` | ✅ | Primitive types |
| `Symbol.for('name')` | ✅ | Only globally registered symbols |
| `Array`, `Map`, `Set`, `TypedArray`, `ArrayBuffer` | ✅ | |
| `Date`, `FormData`, `Promise` | ✅ | |
| Plain objects (`{}`, `{ key: value }`) | ✅ | Created with object initializer |
| Server Function (`'use server'` function) | ✅ | `$h` token |
| **Server Component (JSX) — children/slot** | ✅ | `$L` lazy or serialized tree |
| Regular functions, arrow functions, class methods | ❌ | Code can't cross the network |
| Class instances | ❌ | Can't restore prototype chain |
| DOM nodes, event objects | ❌ | Native, circular references |
| `Symbol()` not in global registry | ❌ | |
This table hints at the two most common traps in props serialization.
**You can't pass regular functions.** This is a common mistake:
```tsx
// ❌ Server Component creates handler and passes it to Client Component
export default function Page() {
return console.log('hi')} />
}
```
This won't work. `() => console.log('hi')` is a regular function and can't be serialized. There are two solutions:
1. **Make it a Server Function**: Add `'use server'` to make it an RPC endpoint.
2. **Define inside Client Component**: Put the handler in client code.
Most cases use (2). UI event handlers are generally part of client code.
**You can't pass event objects either:**
```tsx
// ❌ Passing event object directly to Server Function