chunking

Explains the chunking architecture in Next.js Turbopack, covering graph walk, module batching, merging, chunk splitting, and output generation.

vercel

May 2, 2026

0 downloads

0 views

ai rag

View source

What this file does

Explains the chunking architecture in Next.js Turbopack, covering graph walk, module batching, merging, chunk splitting, and output generation.

When to use it

Contributing to Next.js Turbopack chunking logic
Understanding how modules become bundles in a Rust-based bundler
Designing a custom chunking strategy for a web bundler
Debugging chunk splitting behavior in development or production

Assumes this stack

RustNext.jsTurbopack

Chunking is the process that decides which modules are placed into which bundles, and the relationship between these bundles.

For this process a few intermediate concepts are used:

ChunkingContext: A context trait which controls the chunking process.
ChunkItem: A derived object from a Module which combines the module with the ChunkingContext and ModuleGraph.
ChunkableModule: A trait which defines how a specific Module can be converted into a ChunkItem.
ModuleReference::chunking_type(): A method on the ModuleReference trait returning Option<ChunkingType>, which defines how a reference interacts with chunking. References returning None are not followed during the chunking graph walk.
ChunkType: A trait which defines how to create a Chunk from ChunkItems.
Chunk: A trait which represents a bundle of ChunkItems.

<figure style="display: flex; flex-direction: column; justify-content: center;"> <img alt="A chart of the type hierarchy" width="800px" src="https://h8dxkfmaphn8o0p3.public.blob.vercel-storage.com/rustdoc-images/chunking.mermaid.png"> </figure>

Graph Walk

A Module must implement the ChunkableModule trait to be considered for chunking. References returned by a module that have a non-None chunking_type() are followed during the chunking graph walk. The ChunkingType enum controls how each reference is handled.

The chunking algorithm walks the module graph via a DFS traversal following these chunkable references to find all modules that should be bundled together.

Module Batching

Before modules become chunk items, they may be grouped into module batches (ModuleBatch). This intermediate batching layer groups related modules together. Batches are organized into batch groups (ModuleBatchGroup) which are carried through the chunking process.

Module Merging (Scope Hoisting)

Modules implementing the MergeableModule trait can be merged together (scope hoisting). When module merging is enabled on the ChunkingContext, multiple modules may be combined into a single module before chunk item creation, reducing the number of individual chunk items and improving runtime performance.

Chunk Item Creation

Modules (or module batches) are converted into ChunkItems via ChunkableModule::as_chunk_item().

Chunk Splitting

A splitting algorithm decides which ChunkItems are placed into which Chunks. Only ChunkItems with the same ChunkType can be placed into the same Chunk. Beyond that, the splitting strategy differs between development and production:

Development mode splits chunks using a hierarchical strategy:

App code vs. vendor code (based on node_modules path presence)
Package name within vendor code
Directory structure within app code
Size thresholds to avoid overly small or large chunks

Production mode splits chunks based on:

Chunk group membership: modules are grouped by which pages/entries they belong to, so modules shared by the same set of pages end up together.
Size constraints: ChunkingConfig controls merging of small chunks and splitting of large ones.

Once the ChunkItems that should be placed together are determined, a Chunk is created for each group by calling ChunkType::chunk().

Output

An OutputAsset is generated for each Chunk. The ChunkingContext implementation decides how each Chunk is transformed into an OutputAsset (e.g. BrowserChunkingContext wraps EcmascriptChunks in an EcmascriptBrowserChunk that adds runtime loading code). CssChunks directly implement OutputAsset. These OutputAssets that are loaded together form a chunk group.

Available Modules

The chunking process tracks which modules are already available in parent chunk groups via AvailableModules, to avoid duplication in nested chunk groups.

What's inside

6 conceptual sections, 8 trait/struct definitions, 1 Mermaid diagram, 2 splitting strategy descriptions

Change this for your project

Replace crate::chunk::ChunkingContext with your own module path
Replace BrowserChunkingContext and NodeJsChunkingContext with your context implementations
Replace EcmascriptChunk and CssChunk with your chunk types

Where it goes

Keep it in your repository where the agent or team that needs it will read it.

Worth borrowing

Using a trait-based ChunkingContext to decouple chunking from output generation
Introducing a ChunkingType enum to control which references are followed during graph walk
Separating development and production chunk splitting strategies