Getting Started

🚧 Beta Software

Rolldown is currently in beta status. While it can already handle most production use cases, there may still be bugs and rough edges. Most notably, the built-in minification feature is still in early work-in-progress status.

Installation

npm

$ npm install -D rolldown

pnpm

$ pnpm add -D rolldown

yarn

$ yarn add -D rolldown

bun

$ bun add -D rolldown

Using a minor platform (CPU architecture, OS) ?

Prebuilt binaries are distributed for the following platforms (grouped by Node.js v22 platform support tier):

• Tier 1
  • Linux x64 glibc (x86_64-unknown-linux-gnu)
  • Linux arm64 glibc (aarch64-unknown-linux-gnu)
  • Linux armv7 (armv7-unknown-linux-gnueabihf)
  • Windows x64 (x86_64-pc-windows-msvc)
  • Windows x86 (i686-pc-windows-msvc)
  • Apple x64 (x86_64-apple-darwin)
  • Apple arm64 (aarch64-apple-darwin)
• Tier 2
  • Windows arm64 (aarch64-pc-windows-msvc)
• Experimental
  • Linux x64 musl (x86_64-unknown-linux-musl)
  • FreeBSD x64 (x86_64-unknown-freebsd)
  • OpenHarmony arm64 (aarch64-unknown-linux-ohos)
• Other
  • Linux arm64 musl (aarch64-unknown-linux-musl)
  • Android arm64 (aarch64-linux-android)
  • Wasm + Wasi (wasm32-wasip1-threads)

If you are using a platform that a prebuilt binary is not distributed, you have the following options:

• Use the Wasm build
  1. Download the Wasm build.
     • For npm, you can run npm install --cpu wasm32 --os wasip1-threads.
     • For yarn or pnpm, you need to add the following content to your .yarnrc.yaml or pnpm-workspace.yaml:

       supportedArchitectures:
         os:
           - wasip1-threads
         cpu:
           - wasm32

  2. Make Rolldown load the Wasm build.
     • If the prebuilt binary is not available, Rolldown will fallback to the Wasm binary automatically.
     • In case you need to force Rolldown to use the Wasm build, you can set NAPI_RS_FORCE_WASI=1 environment variable.
• Build from source
  1. Clone the repository.
  2. Setup the project by following the setup instructions.
  3. Build the project by following the build instructions.
  4. Set the NAPI_RS_NATIVE_LIBRARY_PATH environment variable to the path of packages/rolldown in the cloned repository.

Release Channels

• latest: currently 1.0.0-beta.*.
• pkg.pr.new: continuously released from the main branch. Install with npm i https://pkg.pr.new/rolldown@sha where sha is a successful build listed on pkg.pr.new.

Using the CLI

To verify Rolldown is installed correctly, run the following in the directory where you installed it:

$ ./node_modules/.bin/rolldown --version

You can also check out the CLI options and examples with:

$ ./node_modules/.bin/rolldown --help

Your first bundle

Let's create two source JavaScript files:

src/main.js

import { hello } from './hello.js';

hello();

src/hello.js

export function hello() {
  console.log('Hello Rolldown!');
}

Then run the following in the command line:

$ ./node_modules/.bin/rolldown src/main.js --file bundle.js

You should see the content written to bundle.js in your current directory. Let's run it to verify it's working:

$ node bundle.js

You should see Hello Rolldown! printed.

Using the CLI in npm scripts

To avoid typing the long command, we can move it inside an npm script:

package.json

{
  "name": "my-rolldown-project",
  "type": "module",
  "scripts": {
    "build": "rolldown src/main.js --file bundle.js"
  },
  "devDependencies": {
    "rolldown": "^1.0.0-beta.1"
  }
}

Now we can run the build with just:

$ npm run build

Using the Config File

When more options are needed, it is recommended to use a config file for more flexibility. Let's create the following config file:

rolldown.config.js

import { defineConfig } from 'rolldown';

export default defineConfig({
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
  },
});

Rolldown supports most of the Rollup config options, with some notable additional features.

While exporting a plain object also works, it is recommended to utilize the defineConfig helper method to get options intellisense and auto-completion. This helper is provided purely for the types and returns the options as-is.

Next, in the npm script, we can instruct Rolldown to use the config file with the --config CLI option (-c for short):

package.json

{
  "name": "my-rolldown-project",
  "type": "module",
  "scripts": {
    "build": "rolldown -c"
  },
  "devDependencies": {
    "rolldown": "^1.0.0-beta.1"
  }
}

TypeScript config file

TypeScript config file is also supported out of the box:

package.json

{
  "name": "my-rolldown-project",
  "type": "module",
  "scripts": {
    "build": "rolldown -c rolldown.config.ts"
  },
  "devDependencies": {
    "rolldown": "^1.0.0-beta.1"
  }
}

rolldown.config.ts

import { defineConfig } from 'rolldown';

export default defineConfig({
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
  },
});

Specifying config file name

The default config file used with the -c flag is rolldown.config.js. If you are using .ts or .mjs extensions, make sure to specify the full filename with e.g. rolldown -c rolldown.config.ts.

Multiple builds in the same config

You can also specify multiple configurations as an array, and Rolldown will bundle them in parallel.

rolldown.config.js

import { defineConfig } from 'rolldown';

export default defineConfig([
  {
    input: 'src/main.js',
    output: {
      format: 'esm',
    },
  },
  {
    input: 'src/worker.js',
    output: {
      format: 'iife',
      dir: 'dist/worker',
    },
  },
]);

Using Plugins

Rolldown's plugin API is identical to that of Rollup's, so you can reuse most of the existing Rollup plugins when using Rolldown. That said, Rolldown provides many built-in features that make it unnecessary to use plugins.

Using the API

Rolldown provides a JavaScript API that is compatible with Rollup's, which separates input and output options:

import { rolldown } from 'rolldown';

const bundle = await rolldown({
  // input options
  input: 'src/main.js',
});

// generate bundles in memory with different output options
await bundle.generate({
  // output options
  format: 'esm',
});
await bundle.generate({
  // output options
  format: 'cjs',
});

// or directly write to disk
await bundle.write({
  file: 'bundle.js',
});

Alternatively, you can also use the more concise build API, which accepts the exact same options as the config file export:

import { build } from 'rolldown';

// build writes to disk by default
await build({
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
  },
});

Using the Watcher

The rolldown watcher api is compatible with rollup watch.

import { watch } from 'rolldown';

const watcher = watch({
  /* option */
}); // or watch([/* multiply option */] )

watcher.on('event', () => {});

await watcher.close(); // Here is different with rollup, the rolldown returned the promise at here.