turbopack-core

The bundler-agnostic abstractions every Turbopack language plugin and target builds on.

Source: turbopack/crates/turbopack-core/src/. ~50 files, all #[turbo_tasks::value] types and #[turbo_tasks::function] functions.

Core trait surface

Five traits define the universe:

Trait	What it represents
Source	Raw input — a file, a virtual buffer, a data URI
Asset	Anything that could be emitted (a Source or a derivative)
Module	An asset interpreted as a module (has imports / exports)
Chunk	A bundled output unit
Output	The final artifact written to disk

graph LR
    Source --> Asset
    Asset --> Module[Module<br/>via context]
    Module --> Chunk
    Chunk --> Output
    Output --> Disk[(disk)]

Each is declared in its own small file:

• source.rs, asset.rs, module.rs, output.rs
• chunk/ directory (16 KB+ index)

References

A Module exposes references to other modules. References come in many flavors:

• EsmAssetReference — import / export from
• CommonJsAssetReference — require()
• CssAssetReference — @import / url()
• RawAssetReference — import.meta.url and friends
• AsyncAssetReference — import() / dynamic chunks
• ContextAssetReference — require.context (webpack compat)

reference/ and reference_type.rs (12 KB) define them. Each reference type carries metadata about how the dependency should be bundled.

Resolve

turbopack/crates/turbopack-core/src/resolve/ is the resolver. Inputs:

• A request (./foo, next/link, @/components/Button)
• A context directory
• A reference type (esm, cjs, css, etc.)

Output: a ResolveResult enum — Module(...), Unresolveable, Alternatives(...), etc.

The resolver knows about:

• Node's package.json resolution (exports, main, browser fields).
• Webpack-compatible resolve.alias.
• TypeScript's tsconfig.paths.
• The framework's per-layer overrides (e.g., react → react-server-dom-turbopack/server in the react-server layer).

The full resolver is in turbopack/crates/turbopack-resolve/; this resolve/ directory is just the trait surface.

Compile-time info

compile_time_info.rs (26 KB) is a top-level value passed through the bundle that describes the bundling environment:

• process.env.NODE_ENV value to inline.
• React version.
• Browser targets.
• Default chunk loading runtime.
• Node version (when targeting Node).

Language plugins read this to specialize output.

Environment

environment.rs (16 KB) defines Environment — a typed description of "browser version X" or "Node version Y" or "edge-runtime workerd". Used to decide which polyfills to emit and which APIs are available.

Code builder

code_builder.rs (13 KB) is the helper for producing source-mapped output. Language plugins emit code by appending fragments and mappings to a CodeBuilder; the result is a Code with text and source map.

Source maps

source_map/ and source_map.rs produce v3 source maps. Turbopack's source maps preserve the chain across multiple transformation passes.

Issues

issue/ is the diagnostic framework. Each issue has a category, severity, source span, and (optionally) suggested fix. Issues bubble up through the task graph and the dev server / CLI surface them in user-friendly forms.

Versioning

version.rs (10 KB) defines Version — a content-derived hash used as a chunk's cache buster. Two builds of the same project produce identical hashes when source content matches.

Module graph

module_graph/ is the connectivity analysis: given a set of entry modules, walk all references to produce the full reachable set. Used to build manifests, find circular imports, and split chunks.

Chunking

chunk/ is the chunk abstraction — generic over content type. It defines:

• ChunkingContext — knows how to allocate chunks (file paths, naming).
• Chunk — a unit of output content.
• ChunkItem — one module's worth of code inside a chunk.
• OutputAsset — a chunk emitted to disk.

Concrete chunkers live in turbopack-ecmascript, turbopack-css, etc.

Other

File	Purpose
context.rs	AssetContext — entry into the bundler from a target
target.rs	Compilation target description
loader.rs	webpack-loader-style asset transforms
package_json.rs	package.json reader
ident.rs	Asset identity / hashing
proxied_asset.rs	Proxy assets (forwards to another asset)
raw_module.rs	Module emitted unchanged
data_uri_source.rs	data: URL sources
virtual_source.rs	Synthesized in-memory sources
node_addon_module.rs	.node native modules

Integration

Every Turbopack language plugin registers types that implement the core traits. The plugin doesn't know about chunking strategy, persistence, or task scheduling — it just describes how its file format becomes modules with references. The framework handles the rest.

Key source files

File	Purpose
turbopack/crates/turbopack-core/src/lib.rs	Crate entry
turbopack/crates/turbopack-core/src/source.rs	Source trait
turbopack/crates/turbopack-core/src/asset.rs	Asset trait
turbopack/crates/turbopack-core/src/module.rs	Module trait
turbopack/crates/turbopack-core/src/output.rs	Output trait
turbopack/crates/turbopack-core/src/chunk/	Chunking abstractions
turbopack/crates/turbopack-core/src/reference/	Reference types
turbopack/crates/turbopack-core/src/reference_type.rs	Reference enum
turbopack/crates/turbopack-core/src/resolve/	Resolver trait surface
turbopack/crates/turbopack-core/src/compile_time_info.rs	Compile-time info
turbopack/crates/turbopack-core/src/environment.rs	Environment description
turbopack/crates/turbopack-core/src/code_builder.rs	Source-mapped output builder
turbopack/crates/turbopack-core/src/issue/	Diagnostic framework
turbopack/crates/turbopack-core/src/module_graph/	Module graph computation