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
muslnode 18–226 runs
build_error
glibcnode 18–226 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.fixUpdate 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.fixReview 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.fixUpgrade 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.fixIf 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.fixFor 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.fixReview 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`.
fixReplace 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.
fixUpgrade 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.
fixEnsure 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.
fixRemove or update the unsupported option. Consult the Rolldown Options & APIs Reference for supported configuration properties.
Audit
Dependencies
No dependency data recorded yet.