docs/guide/getting-started.md
:::warning 🚧 Release Candidate Rolldown is currently in RC 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. :::
:::tip Looking for specific use cases? For most applications, using Rolldown through Vite is the recommended approach, as it provides a complete development experience with dev server, HMR, and optimized production builds.
For library bundling, check out tsdown. :::
::: code-group
$ npm install -D rolldown
$ pnpm add -D rolldown
$ yarn add -D rolldown
$ bun add -D rolldown
:::
::: details Using a minor platform (CPU architecture, OS) ?
Prebuilt binaries are distributed for the following platforms (grouped by Node.js v24 platform support tier):
x86_64-unknown-linux-gnu)aarch64-unknown-linux-gnu)x86_64-pc-windows-msvc)x86_64-apple-darwin)aarch64-apple-darwin)aarch64-pc-windows-msvc)s390x-unknown-linux-gnu)powerpc64le-unknown-linux-gnu)x86_64-unknown-linux-musl)armv7-unknown-linux-gnueabihf)x86_64-unknown-freebsd)aarch64-unknown-linux-ohos)aarch64-unknown-linux-musl)aarch64-linux-android)wasm32-wasip1-threads)If you are using a platform that a prebuilt binary is not distributed, you have the following options:
npm install --cpu wasm32 --os wasip1-threads..yarnrc.yaml or pnpm-workspace.yaml:
supportedArchitectures:
os:
- wasip1-threads
cpu:
- wasm32
NAPI_RS_FORCE_WASI=error environment variable.NAPI_RS_NATIVE_LIBRARY_PATH environment variable to the path of packages/rolldown in the cloned repository.:::
1.0.0-rc.*.main branch. Install with npm i https://pkg.pr.new/rolldown@sha where sha is a successful build listed on pkg.pr.new.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
Let's create two source JavaScript files:
import { hello } from './hello.js';
hello();
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.
To avoid typing the long command, we can move it inside an npm script:
{
"name": "my-rolldown-project",
"type": "module",
"scripts": {
"build": "rolldown src/main.js --file bundle.js"
},
"devDependencies": {
"rolldown": "^1.0.0-rc.1"
}
}
Now we can run the build with just:
$ npm run build
When more options are needed, it is recommended to use a config file for more flexibility. A config file can be written in .js, .cjs, .mjs, .ts, .mts, or .cts formats. Let's create the following config file:
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. See the reference for the full list of options.
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):
{
"name": "my-rolldown-project",
"type": "module",
"scripts": {
"build": "rolldown -c"
},
"devDependencies": {
"rolldown": "^1.0.0-rc.1"
}
}
You can also specify multiple configurations as an array, and Rolldown will bundle them in parallel.
import { defineConfig } from 'rolldown';
export default defineConfig([
{
input: 'src/main.js',
output: {
format: 'esm',
},
},
{
input: 'src/worker.js',
output: {
format: 'iife',
dir: 'dist/worker',
},
},
]);
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.
Also Rolldown provides some builtin plugins that can be used for some use cases. See Builtin Plugins for more information.
Community plugins that are published to npm are listed in Vite Plugin Registry.
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',
},
});
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(); // This is different than rollup: rolldown returns a promise here.