{"id":11955,"library":"rolldown","title":"Rolldown","description":"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.","status":"active","version":"1.0.0-rc.16","language":"javascript","source_language":"en","source_url":"https://github.com/rolldown/rolldown","tags":["javascript","bundler","esbuild","parcel","rolldown","rollup","webpack","typescript"],"install":[{"cmd":"npm install rolldown","lang":"bash","label":"npm"},{"cmd":"yarn add rolldown","lang":"bash","label":"yarn"},{"cmd":"pnpm add rolldown","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Rolldown is primarily an ESM-first package. Use named imports for the main `rolldown` function.","wrong":"const rolldown = require('rolldown');","symbol":"rolldown","correct":"import { rolldown } from 'rolldown';"},{"note":"The `defineConfig` helper is a named export, primarily used for type inference in configuration files.","wrong":"import defineConfig from 'rolldown';","symbol":"defineConfig","correct":"import { defineConfig } from 'rolldown';"},{"note":"These are TypeScript types; use `import type` to ensure they are not bundled as runtime values.","wrong":"import { RolldownInputOptions, RolldownOutputOptions } from 'rolldown';","symbol":"RolldownInputOptions, RolldownOutputOptions","correct":"import type { RolldownInputOptions, RolldownOutputOptions } from 'rolldown';"}],"quickstart":{"code":"import { rolldown, defineConfig } from 'rolldown';\nimport path from 'path';\n\nasync function buildMyProject() {\n  const inputDir = path.resolve(__dirname, 'src');\n  const outputDir = path.resolve(__dirname, 'dist');\n\n  const options = defineConfig({\n    input: path.join(inputDir, 'main.ts'),\n    output: {\n      dir: outputDir,\n      format: 'esm',\n      entryFileNames: '[name]-[hash].js',\n      chunkFileNames: 'chunks/[name]-[hash].js',\n      sourcemap: true,\n      minify: process.env.NODE_ENV === 'production' ? 'dce-only' : false, // DCE-only minification is default since v1.0.0-rc.7\n    },\n    plugins: [\n      // Example: A simple plugin to log file IDs during resolution\n      {\n        name: 'log-resolve-id',\n        resolveId(source, importer, options) {\n          console.log(`Resolving: ${source} (imported by ${importer || 'entry'})`);\n          return null; // Let other resolvers handle it\n        }\n      }\n    ],\n    // Rolldown handles TypeScript and Node.js module resolution out of the box\n    // No need for @rollup/plugin-typescript or @rollup/plugin-node-resolve\n    tsconfig: true, // Auto-detect tsconfig.json\n  });\n\n  console.log('Starting Rolldown build...');\n  const bundle = await rolldown(options);\n\n  console.log('Writing bundle to disk...');\n  await bundle.write(options.output);\n  console.log('Build complete!');\n}\n\n// Run the build process\nbuildMyProject().catch(console.error);\n\n// Example of an entry file (src/main.ts)\n// export * from './utils';\n// console.log('Hello from main.ts');\n\n// Example of a utility file (src/utils.ts)\n// export const sum = (a: number, b: number) => a + b;\n","lang":"typescript","description":"This quickstart demonstrates how to programmatically use Rolldown to bundle a TypeScript project, including basic configuration, output options, and a simple custom plugin."},"warnings":[{"fix":"Update imports from `BindingMagicString` to `RolldownMagicString`.","message":"The `BindingMagicString` export was renamed to `RolldownMagicString` in `v1.0.0-rc.9`. If you were directly importing or referencing `BindingMagicString`, your code will break.","severity":"breaking","affected_versions":">=1.0.0-rc.9"},{"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.","message":"Rolldown 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.","severity":"gotcha","affected_versions":">=1.0.0-rc.1"},{"fix":"Upgrade your Node.js environment to a compatible version (e.g., Node.js 20.x LTS or 22.x).","message":"Rolldown requires Node.js version `^20.19.0 || >=22.12.0`. Older Node.js versions will not be supported.","severity":"gotcha","affected_versions":"<20.19.0 || <22.12.0"},{"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.","message":"Since `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.","severity":"gotcha","affected_versions":">=1.0.0-rc.7"},{"fix":"For files containing CommonJS syntax that require non-strict mode, change their extension to `.cjs` as a workaround.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0-rc.1"},{"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.","message":"Rolldown 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.","severity":"gotcha","affected_versions":">=1.0.0-rc.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Replace all occurrences of `BindingMagicString` with `RolldownMagicString` in your code.","cause":"The `BindingMagicString` export was renamed to `RolldownMagicString` in `v1.0.0-rc.9`.","error":"TypeError: (0 , rolldown__WEBPACK_IMPORTED_MODULE_0__.BindingMagicString) is not a constructor"},{"fix":"Upgrade your Node.js installation to version 20.19.0 or newer, or 22.12.0 or newer.","cause":"Your Node.js environment is older than the minimum required version for Rolldown.","error":"Error: Minimum Node.js version not met: rolldown requires Node.js >= 20.19.0 || >=22.12.0"},{"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.","cause":"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.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ...rolldown.js from ...your-script.js not supported."},{"fix":"Remove or update the unsupported option. Consult the Rolldown Options & APIs Reference for supported configuration properties.","cause":"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.","error":"Warning: validate output options. For the \"generatedCode\". Invalid key: Expected never but received \"generatedCode\"."}],"ecosystem":"npm"}