Registry / web-framework / rolldown

rolldown

JSON →
library1.0.0-rc.16jsnpmunverified

Rolldown is a high-performance JavaScript and TypeScript bundler written in Rust, aiming to unify and replace esbuild and Rollup in build pipelines like Vite. It offers 10-30x faster builds than Rollup due to its Rust-based, parallel processing architecture. Currently at version `1.0.0-rc.16`, Rolldown is in a Release Candidate phase, signaling API stability with no planned breaking changes before the 1.0 stable release, though experimental features like minification may still have rough edges. It features a Rollup-compatible plugin API, built-in transforms for TypeScript and JSX powered by Oxc, native CJS/ESM interoperability without additional plugins, and granular code splitting akin to Webpack's `optimization.splitChunks`. Rolldown is designed to serve as Vite 8+'s default bundler but can also be used as a standalone tool, offering more control than esbuild when complex chunking is required.

npm install rolldown
INSTALL
IMPORT
SIG · ROLLDOWN
R
rolldown
web-frameworkjavascriptv1.0.0-rc.16
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

rolldown
import { rolldown } from 'rolldown';
const rolldown = require('rolldown');
Rolldown is primarily an ESM-first package. Use named imports for the main `rolldown` function.
defineConfig
import { defineConfig } from 'rolldown';
import defineConfig from 'rolldown';
The `defineConfig` helper is a named export, primarily used for type inference in configuration files.
RolldownInputOptions, RolldownOutputOptions
import type { RolldownInputOptions, RolldownOutputOptions } from 'rolldown';
import { RolldownInputOptions, RolldownOutputOptions } from 'rolldown';
These are TypeScript types; use `import type` to ensure they are not bundled as runtime values.

This quickstart demonstrates how to programmatically use Rolldown to bundle a TypeScript project, including basic configuration, output options, and a simple custom plugin.

import { rolldown, defineConfig } from 'rolldown'; import path from 'path'; async function buildMyProject() { const inputDir = path.resolve(__dirname, 'src'); const outputDir = path.resolve(__dirname, 'dist'); const options = defineConfig({ input: path.join(inputDir, 'main.ts'), output: { dir: outputDir, format: 'esm', entryFileNames: '[name]-[hash].js', chunkFileNames: 'chunks/[name]-[hash].js', sourcemap: true, minify: process.env.NODE_ENV === 'production' ? 'dce-only' : false, // DCE-only minification is default since v1.0.0-rc.7 }, plugins: [ // Example: A simple plugin to log file IDs during resolution { name: 'log-resolve-id', resolveId(source, importer, options) { console.log(`Resolving: ${source} (imported by ${importer || 'entry'})`); return null; // Let other resolvers handle it } } ], // Rolldown handles TypeScript and Node.js module resolution out of the box // No need for @rollup/plugin-typescript or @rollup/plugin-node-resolve tsconfig: true, // Auto-detect tsconfig.json }); console.log('Starting Rolldown build...'); const bundle = await rolldown(options); console.log('Writing bundle to disk...'); await bundle.write(options.output); console.log('Build complete!'); } // Run the build process buildMyProject().catch(console.error); // Example of an entry file (src/main.ts) // export * from './utils'; // console.log('Hello from main.ts'); // Example of a utility file (src/utils.ts) // export const sum = (a: number, b: number) => a + b;
rolldown --version
Debug
Known issues
breakingThe `BindingMagicString` export was renamed to `RolldownMagicString` in `v1.0.0-rc.9`. If you were directly importing or referencing `BindingMagicString`, your code will break.
fix
Update imports from `BindingMagicString` to `RolldownMagicString`.
affects: >=1.0.0-rc.9
gotchaRolldown is still in Release Candidate (RC) status (`1.0.0-rc.16`), meaning while API stability is largely expected, some experimental features (like minification) might still be in progress, and unexpected bugs or rough edges may exist.
fix
Review the changelog and documentation for each RC release. Report any issues encountered to the Rolldown GitHub repository. Consider pinning specific RC versions in production for stability.
affects: >=1.0.0-rc.1
gotchaRolldown requires Node.js version `^20.19.0 || >=22.12.0`. Older Node.js versions will not be supported.
fix
Upgrade your Node.js environment to a compatible version (e.g., Node.js 20.x LTS or 22.x).
affects: <20.19.0 || <22.12.0
gotchaSince `v1.0.0-rc.7`, DCE-only minification and smart constant inlining are enabled by default. This change might subtly alter output bundles compared to previous RC versions, potentially affecting debugging or manual optimizations.
fix
If unintended minification or inlining occurs, explicitly set `output.minify` to `false` or adjust `optimization` options in your Rolldown configuration to fine-tune its behavior. Note that `output.minify` is still considered 'WIP' or 'alpha' status.
affects: >=1.0.0-rc.7
gotchaWhen bundling CJS modules, Rolldown defaults to parsing `.js` files as ESM without falling back to CJS. This means non-strict mode (sloppy mode) syntaxes in `.js` files will be rejected.
fix
For files containing CommonJS syntax that require non-strict mode, change their extension to `.cjs` as a workaround.
affects: >=1.0.0-rc.1
gotchaRolldown handles output generation for multiple configurations separately. Plugins that maintain state across the entire build process might behave differently compared to Rollup, where all outputs are generated in a single process.
fix
Review any Rollup plugins that rely on shared state across multiple output bundles. Adjust plugin logic or reconsider plugin choice if behavior is inconsistent when migrating to Rolldown.
affects: >=1.0.0-rc.1
Errors
Common errors & fixes
TypeError: (0 , rolldown__WEBPACK_IMPORTED_MODULE_0__.BindingMagicString) is not a constructor
The `BindingMagicString` export was renamed to `RolldownMagicString` in `v1.0.0-rc.9`.
fix
Replace all occurrences of `BindingMagicString` with `RolldownMagicString` in your code.
Error: Minimum Node.js version not met: rolldown requires Node.js >= 20.19.0 || >=22.12.0
Your Node.js environment is older than the minimum required version for Rolldown.
fix
Upgrade your Node.js installation to version 20.19.0 or newer, or 22.12.0 or newer.
Error [ERR_REQUIRE_ESM]: require() of ES Module ...rolldown.js from ...your-script.js not supported.
You are attempting to import Rolldown using CommonJS `require()` syntax in an environment that expects ESM, or your project's `type` is `commonjs` without proper interop setup.
fix
Ensure your project is configured for ESM (`"type": "module"` in `package.json`) and use `import { rolldown } from 'rolldown';` for programmatic usage. If using CommonJS, consider dynamic `import('rolldown')` or ensure your toolchain handles ESM-to-CJS transpilation if supported by Rolldown in that context.
Warning: validate output options. For the "generatedCode". Invalid key: Expected never but received "generatedCode".
You are passing a Rollup output option (`generatedCode`) that is not supported or recognized by Rolldown's API. Rolldown aims for Rollup *API compatibility* but may not support every option identically.
fix
Remove or update the unsupported option. Consult the Rolldown Options & APIs Reference for supported configuration properties.
Upgrade
Version history
1.0.0-rc.16latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
rolldown — npm install rolldown · libregistry