Rolldown

Common errors

• TypeError: (0 , rolldown__WEBPACK_IMPORTED_MODULE_0__.BindingMagicString) is not a constructor

  cause 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

  cause 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.

  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.
  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".

  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.
  fix Remove or update the unsupported option. Consult the Rolldown Options & APIs Reference for supported configuration properties.

Warnings

• breaking 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.
  Fix: Update imports from `BindingMagicString` to `RolldownMagicString`.
• gotcha 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.
  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.
• gotcha Rolldown 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).
• gotcha 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.
  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.
• gotcha 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.
  Fix: For files containing CommonJS syntax that require non-strict mode, change their extension to `.cjs` as a workaround.
• gotcha 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.
  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.

Install

• npm install rolldown npm
• yarn add rolldown yarn
• pnpm add rolldown pnpm

Imports

• rolldown
  wrong:

  const rolldown = require('rolldown');

  correct:

  import { rolldown } from 'rolldown';

  Rolldown is primarily an ESM-first package. Use named imports for the main `rolldown` function.
• defineConfig
  wrong:

  import defineConfig from 'rolldown';

  correct:

  import { defineConfig } from 'rolldown';

  The `defineConfig` helper is a named export, primarily used for type inference in configuration files.
• RolldownInputOptions, RolldownOutputOptions
  wrong:

  import { RolldownInputOptions, RolldownOutputOptions } from 'rolldown';

  correct:

  import type { RolldownInputOptions, RolldownOutputOptions } from 'rolldown';

  These are TypeScript types; use `import type` to ensure they are not bundled as runtime values.

Quickstart

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;