Turbopack

Turbopack is the bundler and the underlying incremental computation engine. It became part of vercel/next.js in August 2024 via a git subtree merge from the standalone vercel/turbo repo, and the consolidated history is preserved in the canary branch.

Source: turbopack/crates/. 54 Cargo crates, ~200,000+ lines of Rust. The biggest single Rust file in the framework is turbo-tasks-backend/src/backend/mod.rs at 6,180 lines.

This page is the index. Subpages cover the major component groups.

Mental model

graph TD
    Code[turbo-tasks framework] --> Engine[Incremental computation<br/>memoized async fns]
    Engine --> CoreLayer[turbopack-core<br/>generic bundler]
    CoreLayer --> Languages[Language plugins<br/>ecmascript, css, mdx, image, static]
    CoreLayer --> Resolve[turbopack-resolve]
    CoreLayer --> Targets[Target platforms<br/>browser, nodejs]
    Targets --> Hosts[Host integrations<br/>dev-server, cli]
    Engine --> Persistence[turbo-persistence<br/>on-disk store]
    Engine --> Tracing[turbopack-tracing<br/>trace-server]

The architecture is intentionally layered so each layer can be tested in isolation:

1. turbo-tasks framework — the incremental computation engine. Generic, no bundling knowledge.
2. turbopack-core — bundler-agnostic abstractions: assets, modules, chunks, references.
3. Language plugins — JavaScript/TypeScript, CSS, MDX, images, static files.
4. Resolve / env / fetch — module resolution, env-var injection, network fetching.
5. Targets — browser bundles, Node.js bundles, edge bundles.
6. Hosts — turbopack-cli, turbopack-dev-server, integration into Next.js.
7. Persistence and tracing — on-disk caching, profiling.

Crate map

Framework / engine

Crate	What
turbopack/crates/turbo-tasks	Incremental computation framework
turbopack/crates/turbo-tasks-backend	Storage backend (in-memory + persistent)
turbopack/crates/turbo-tasks-macros	#[turbo_tasks::function] proc macros
turbopack/crates/turbo-tasks-fs	Async, memoized filesystem
turbopack/crates/turbo-tasks-fetch	Memoized HTTP fetching
turbopack/crates/turbo-tasks-env	Env-var injection
turbopack/crates/turbo-tasks-hash	Stable hashing utilities
turbopack/crates/turbo-tasks-bytes	Bytes / streams
turbopack/crates/turbo-tasks-malloc	Allocation tracking
turbopack/crates/turbo-tasks-testing	Test harness

→ See turbo-tasks.

Core bundler

Crate	What
turbopack/crates/turbopack	Top-level facade; assembles the bundler
turbopack/crates/turbopack-core	Asset / module / chunk / reference abstractions
turbopack/crates/turbopack-resolve	Module resolution
turbopack/crates/turbopack-env	Env-var handling
turbopack/crates/turbopack-analyze	Bundle analysis

→ See turbopack-core.

Language plugins

Crate	What
turbopack/crates/turbopack-ecmascript	JS/TS/JSX/TSX support
turbopack/crates/turbopack-ecmascript-runtime	User-facing runtime (chunk loader, hmr, modules.js)
turbopack/crates/turbopack-ecmascript-plugins	Custom transforms
turbopack/crates/turbopack-ecmascript-hmr-protocol	HMR wire protocol
turbopack/crates/turbopack-css	CSS / CSS Modules
turbopack/crates/turbopack-mdx	MDX support
turbopack/crates/turbopack-image	Image-asset handling
turbopack/crates/turbopack-static	Static assets
turbopack/crates/turbopack-wasm	wasm modules
turbopack/crates/turbopack-nft	Node File Tracer integration

→ See turbopack-ecmascript and turbopack-css.

Targets / hosts

Crate	What
turbopack/crates/turbopack-browser	Browser-bundle target
turbopack/crates/turbopack-nodejs	Node-bundle target
turbopack/crates/turbopack-node	Node-runtime helpers used at build time
turbopack/crates/turbopack-dev-server	Dev server / HMR endpoint
turbopack/crates/turbopack-cli	Standalone Turbopack CLI
turbopack/crates/turbopack-cli-utils	Pretty-printing / progress reporting

→ See turbopack-dev-server.

Persistence / tracing / utilities

Crate	What
turbopack/crates/turbo-persistence	LSM-style on-disk store
turbopack/crates/turbo-persistence-tools	Maintenance / inspection
turbopack/crates/turbopack-tracing	Tracing-subscriber integration
turbopack/crates/turbopack-trace-server	Trace UI server
turbopack/crates/turbopack-trace-utils	Tracing helpers
turbopack/crates/turbo-prehash	Pre-hashed string support
turbopack/crates/turbo-rcstr	Reference-counted strings
turbopack/crates/turbo-bincode	Bincode helpers
turbopack/crates/turbo-dyn-eq-hash	Dyn-trait Eq/Hash
turbopack/crates/turbo-esregex	ECMAScript regex
turbopack/crates/turbo-frozenmap	Immutable maps
turbopack/crates/turbo-unix-path	Unix-style path manipulation
turbopack/crates/turbopack-swc-utils	SWC integration helpers
turbopack/crates/turbopack-swc-ast-explorer	AST debugging tool
turbopack/crates/turbopack-test-utils	Test fixtures
turbopack/crates/turbopack-tests	Integration tests
turbopack/crates/turbopack-bench	Benchmarks
turbopack/crates/turbopack-create-test-app	Generator for test fixtures

→ See turbo-persistence.

Subtree merge

Turbopack lived in vercel/turbo until August 2024. The history was merged with git subtree merge so commits before August 2024 still appear under turbopack/ paths in git log. The canary branch retains the consolidated history. Some pre-merge tags reference paths that no longer exist; reach for git log --follow when chasing pre-merge changes.

Cross-cutting refactors that touched both vercel/turbo and vercel/next.js simultaneously (e.g., napi version bumps) sometimes require coordinated reverts; see the documented procedure in AGENTS.md.

Build

# Build everything in the workspace
cargo build --workspace --release

# Build just one Turbopack crate
cargo build --release -p turbopack-ecmascript

# Run tests
cargo test --workspace

The xtask crate at turbopack/xtask/ provides higher-level workspace operations:

cargo xtask run-tests

How Next.js consumes Turbopack

The Next.js Rust crates (crates/next-core, crates/next-api) depend on Turbopack via the workspace. There's no published turbopack npm package — Turbopack ships as part of @next/swc-{platform} (the next-napi-bindings build).

For the standalone turbopack CLI use case, build turbopack-cli directly:

cargo build --release -p turbopack-cli

Performance notes

• All Turbopack work is tokio-async and parallelized.
• Each cached unit is a Vc<T> (a "virtual computation"). Two callers asking for the same Vc get the same result without re-running.
• The on-disk persistence layer (turbo-persistence) is essentially an LSM tree tuned for Turbopack's access patterns. Compaction is lazy.

Subpages

• turbo-tasks framework
• turbopack-core
• turbopack-ecmascript
• turbopack-css
• turbopack-dev-server
• turbo-persistence