This page introduces Rolldown, a high-performance JavaScript bundler written in Rust. It covers the project's purpose, core design principles, architectural layers, and package structure. For detailed information about specific subsystems, refer to the child pages in this section.
Rolldown is a fast JavaScript bundler written in Rust that aims to be a drop-in replacement for Rollup. It provides a Rollup-compatible API while delivering significantly improved performance through native code execution.
Core Implementation:
crates/ directoryrolldown crate (crates/rolldown/Cargo.toml1-96) implements the core bundling logicrolldown_binding crate (crates/rolldown_binding/Cargo.toml1-88) provides Node.js bindings via napi-rspackages/rolldown (packages/rolldown/package.json1-178) exposes the JavaScript APITechnology Stack:
oxc_parser v0.119.0 for AST generation (Cargo.toml237-248)oxc_resolver v11.19.1 for module resolution (Cargo.toml264-267)oxc with minifier, mangler, and transformer features (Cargo.toml237)Distribution Targets:
The napi.targets configuration in packages/rolldown/package.json150-166 defines 15 platform targets:
x86_64-apple-darwin, aarch64-apple-darwinx86_64-pc-windows-msvc, aarch64-pc-windows-msvcx86_64-unknown-linux-gnu, x86_64-unknown-linux-musl, aarch64-unknown-linux-gnu, aarch64-unknown-linux-musl, armv7-unknown-linux-gnueabihf, s390x-unknown-linux-gnu, powerpc64le-unknown-linux-gnux86_64-unknown-freebsdaarch64-linux-androidaarch64-unknown-linux-ohoswasm32-wasip1-threads for browser and WASI environmentsPlatform bindings are loaded via packages/rolldown/src/binding.cjs1-1014 with automatic fallback to WASI (packages/rolldown/src/rolldown-binding.wasi.cjs1-177).
Sources: Cargo.toml1-302 packages/rolldown/package.json1-178 crates/rolldown_binding/Cargo.toml1-88 packages/rolldown/src/binding.cjs1-1014
Rolldown aims for API compatibility with Rollup to enable seamless migration while providing faster build times. The project maintains compatibility through extensive testing against Rollup's official test suite.
Rollup Compatibility Goals
Compatibility Testing Infrastructure:
The packages/rollup-tests/package.json1-27 package runs Rollup's test suite with interception:
ROLLUP_TEST=1 mocha --file ./src/intercept/main.js test/test.jsacorn-import-assertions, fixturify, and source-map-support for test utilitiesVite Integration:
Rolldown is designed to serve as Vite's production bundler through:
crates/rolldown_plugin_vite_* (crates/rolldown_binding/src/options/plugin/binding_builtin_plugin.rs6-24)rolldown_dev crate (Cargo.toml100)Sources: packages/rollup-tests/package.json1-27 crates/rolldown_binding/src/options/plugin/binding_builtin_plugin.rs1-205 Cargo.toml98-145
Rolldown is structured as a multi-layer system, with each layer having distinct responsibilities:
High-Level Layered Architecture with Code Entities
Layer Descriptions:
| Layer | Responsibility | Key Components |
|---|---|---|
| User Interface | Entry points for users | CLI, Node.js API, Browser API |
| JavaScript/TypeScript | Configuration validation, plugin definitions | Valibot schemas, plugin hooks |
| NAPI Binding | JavaScript-Rust bridge | Type conversion, callback wrapping |
| Rust Core | Bundling logic | Scan-Link-Generate pipeline |
| Foundation | Low-level primitives | Oxc parser, transformer, minifier |
For detailed architecture information, see Architecture Overview.
Sources: packages/rolldown/package.json29-76 packages/rolldown/src/binding.cjs1-10
Rolldown's bundler executes a three-stage pipeline orchestrated by the Bundler::bundle() method in the rolldown crate:
Pipeline Flow with Code References
Implementation Details:
| Stage | Entry Point | Key Operations | Core Types |
|---|---|---|---|
| Scan | ScanStage | ModuleLoader parallel task execution, AST parsing via oxc_parser, AstScanner for import/export analysis | Module, ModuleTask, ScanStageCache |
| Link | LinkStage | bind_imports_and_exports() for symbol resolution, include_statements() for tree-shaking, wrap_modules() for wrapping | SymbolRefDb, LinkStageOutput |
| Generate | GenerateStage | generate_chunks() for chunking, ScopeHoistingFinalizer for AST finalization, finalize_assets() for hashing | Chunk, ChunkGraph, OutputAsset |
Plugin Integration Points:
resolveId, load, transform hooks executed during module loadingbuildStart, moduleParsed, buildEnd hooksrenderStart, renderChunk, generateBundle, writeBundle hooksParallelization:
tokio runtime and async-channelrayon (configured with num_cpus)ParallelJsPlugin with worker threadsFor detailed pipeline documentation, see Three-Stage Pipeline and Module Processing Pipeline.
Sources: Cargo.toml209 crates/rolldown/Cargo.toml1-96 crates/rolldown_plugin/Cargo.toml1-65
Rolldown uses a monorepo structure managed by pnpm workspaces (pnpm-workspace.yaml1-107):
Monorepo Package Structure with npm Names
Platform-Specific Loading Logic:
The binding loader in packages/rolldown/src/binding.cjs1-1014 implements a fallback chain:
NAPI_RS_NATIVE_LIBRARY_PATH environment variable for custom binding pathprocess.platform and process.arch@rolldown/binding-{platform}-{arch} package namerequire() the platform-specific packagePlatform Package Mapping:
| Platform | Architecture | npm Package |
|---|---|---|
| darwin | x64 | @rolldown/binding-darwin-x64 |
| darwin | arm64 | @rolldown/binding-darwin-arm64 |
| win32 | x64 | @rolldown/binding-win32-x64-msvc |
| win32 | arm64 | @rolldown/binding-win32-arm64-msvc |
| linux (glibc) | x64 | @rolldown/binding-linux-x64-gnu |
| linux (musl) | x64 | @rolldown/binding-linux-x64-musl |
| linux (glibc) | arm64 | @rolldown/binding-linux-arm64-gnu |
| linux (musl) | arm64 | @rolldown/binding-linux-arm64-musl |
| freebsd | x64 | @rolldown/binding-freebsd-x64 |
The isMusl() function in packages/rolldown/src/binding.cjs10-33 detects musl vs glibc on Linux.
Browser Support:
The @rolldown/browser package (packages/browser/package.json1-66) provides browser compatibility:
@napi-rs/wasm-runtime as a dependency (packages/browser/package.json63-65)memfs virtual filesystem via experimental.memfs export (packages/rolldown/src/experimental-index.ts83-86)wasi-worker-browser.mjsPackage Exports Configuration:
The packages/rolldown/package.json36-77 defines modular exports:
"." → dist/index.mjs (main bundler API)"./config" → dist/config.mjs (defineConfig helper)"./experimental" → dist/experimental-index.mjs (dev mode, parallel plugins)"./utils" → dist/utils-index.mjs (parse, minify, transform)"./plugins" → dist/plugins-index.mjs (built-in plugin constructors)"./filter" → dist/filter-index.mjs (filter utilities)Sources: packages/rolldown/src/binding.cjs1-1014 packages/browser/package.json1-66 packages/rolldown/package.json36-77 packages/rolldown/src/experimental-index.ts83-86
Installation:
Basic Usage:
CLI Usage:
For complete API documentation, see:
Sources: packages/rolldown/package.json20-22 package.json13-14
Rolldown is in active development with release candidate versions published to npm. The project maintains Rollup compatibility through extensive testing.
Version and Requirements:
^20.19.0 || >=22.12.0 (package.json47-49)[email protected] (package.json50)0.115.0 (pinned via catalog in pnpm-workspace.yaml24-25)Test Infrastructure with Commands:
Rollup Compatibility Testing:
The packages/rollup-tests package (packages/rollup-tests/package.json1-28) runs Rollup's official test suite:
ROLLUP_TEST=1 mocha --file ./src/intercept/main.js test/test.jsfixturify for file system fixturesTest Classification:
Tests are categorized as:
Status tracking managed via scripts in scripts/ directory.
CI/CD Pipeline:
Workflow automation via justfile (justfile1-252):
just roll - Run all checks (rust + node + repo)just test - Run test suites and update snapshotsjust lint - Run linters (clippy, oxlint, formatting)just build - Build native bindings and TypeScriptFor testing documentation, see Testing and Quality Assurance.
Sources: package.json47-50 packages/rollup-tests/package.json1-28 packages/rolldown/tests/package.json1-37 justfile1-252 rust-toolchain.toml1-4
Rolldown is built on the Oxc ecosystem (version 0.115.0), with dependencies defined in Cargo.toml236-267:
Core Oxc Dependencies:
| Component | Version | Crate Location | Purpose |
|---|---|---|---|
oxc | 0.115.0 | Workspace | Unified API with features: ast_visit, transformer, minifier, mangler, semantic, codegen, serialize, isolated_declarations, regular_expression, cfg |
oxc_allocator | 0.115.0 | Workspace | Memory arena allocation with pool support |
oxc_ecmascript | 0.115.0 | Workspace | ECMAScript utilities |
oxc_traverse | 0.115.0 | Workspace | AST traversal |
oxc_index | 4.x | External | Index types with rayon and serde support |
oxc_resolver | 11.17.1 | External | Module resolution with yarn_pnp support |
oxc_sourcemap | 6.x | External | Source map handling |
NAPI Bindings:
The crates/rolldown_binding crate integrates Oxc NAPI packages:
oxc_napi - NAPI infrastructureoxc_minify_napi - Exposed minification API (packages/rolldown/src/binding.d.cts137-155)oxc_parser_napi - Exposed parsing API (packages/rolldown/src/binding.d.cts329-382)oxc_transform_napi - Exposed transformation APIoxc_resolver_napi - Exposed resolver APIRuntime Helpers Plugin:
The rolldown_plugin_oxc_runtime crate (crates/rolldown_plugin_oxc_runtime/src/generated/embedded_helpers.rs1-10) embeds runtime helpers from @oxc-project/[email protected]:
Key helpers include:
__commonJSMin - CommonJS module wrapping__toESM - CJS-to-ESM conversion__export - ESM export handlingasyncToGenerator - Async/await transformationapplyDecs - Decorator applicationAwaitValue - Await value handlingThese helpers are auto-generated and embedded as string constants for injection during module wrapping.
Catalog Version Pinning:
The pnpm-workspace.yaml (pnpm-workspace.yaml16-98) defines version pins in the catalog:
@oxc-project/runtime: '=0.115.0'@oxc-project/types: '=0.115.0'oxc-minify: '=0.115.0'oxc-parser: '=0.115.0'oxc-transform: '=0.115.0'This ensures consistent Oxc versions across JavaScript and Rust layers.
For Oxc integration details, see OXC Tool Integration.
Sources: Cargo.toml233-264 crates/rolldown_plugin_oxc_runtime/src/generated/embedded_helpers.rs1-10 pnpm-workspace.yaml22-24 packages/rolldown/src/binding.d.cts137-155
Repository Structure:
crates/packages/justfileCommon Development Commands:
The justfile1-252 provides task automation:
Build System:
Build scripts are defined in packages/rolldown/package.json97-119:
build-binding → Compiles Rust via napi-rs to .node filesbuild-node → Compiles TypeScript to dist/*.mjsbuild-js-glue → Runs both TypeScript and type-checkbuild-native:debug → Full debug build (binding + JS)build-native:release → Full release build with optimizationsCI/CD Pipeline:
For development workflow documentation, see Development Workflow.
Sources: justfile1-52 package.json7-22 CHANGELOG.md1-70
This overview provides entry-level context for Rolldown. For deeper exploration:
Core Concepts:
Configuration and Plugins:
Advanced Topics:
Development: