---
url: /guide/getting-started.md
---
# Getting Started

:::tip Looking for specific use cases?
For most applications, using [Rolldown through Vite](https://vite.dev/guide/rolldown.html#how-to-try-rolldown) 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](https://tsdown.dev/).
:::

## Installation

::: code-group

```sh [vp]
$ vp add -D rolldown
```

```sh [npm]
$ npm install -D rolldown
```

```sh [pnpm]
$ pnpm add -D rolldown
```

```sh [yarn]
$ yarn add -D rolldown
```

```sh [bun]
$ 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](https://github.com/nodejs/node/blob/v24.x/BUILDING.md#platform-list)):

* Tier 1
  * Linux x64 glibc (`x86_64-unknown-linux-gnu`)
  * Linux arm64 glibc (`aarch64-unknown-linux-gnu`)
  * Windows x64 (`x86_64-pc-windows-msvc`)
  * Apple x64 (`x86_64-apple-darwin`)
  * Apple arm64 (`aarch64-apple-darwin`)
* Tier 2
  * Windows arm64 (`aarch64-pc-windows-msvc`)
  * Linux s390x glibc (`s390x-unknown-linux-gnu`)
  * Linux ppc64le glibc (`powerpc64le-unknown-linux-gnu`)
* Experimental
  * Linux x64 musl (`x86_64-unknown-linux-musl`)
  * Linux armv7 (`armv7-unknown-linux-gnueabihf`)
  * 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`)
  * Android armv7 (`armv7-linux-androideabi`)
  * 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`:
       ```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=error` environment variable.
* Build from source
  1. Clone the repository.
  2. Setup the project by following [the setup instructions](/development-guide/setup-the-project).
  3. Build the project by following [the build instructions](/development-guide/building-and-running).
  4. Set the `NAPI_RS_NATIVE_LIBRARY_PATH` environment variable to the path of `packages/rolldown` in the cloned repository.

:::

### Release Channels

* [latest](https://npmx.dev/package/rolldown#versions): currently `1.x.x`.
* [pkg.pr.new](https://pkg.pr.new/~/rolldown/rolldown): 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](https://pkg.pr.new/~/rolldown/rolldown).

## Using the CLI

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

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

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

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

### Your first bundle

Let's create two source JavaScript files:

```js [src/main.js]
import { hello } from './hello.js';

hello();
```

```js [src/hello.js]
export function hello() {
  console.log('Hello Rolldown!');
}
```

Then run the following in the command line:

```sh
$ ./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:

```sh
$ node bundle.js
```

You should see `Hello Rolldown!` printed.

### Adding a package.json build script

To avoid typing the long command, we can move it inside a `package.json` script:

```json{5} [package.json]
{
  "name": "my-rolldown-project",
  "type": "module",
  "scripts": {
    "build": "rolldown src/main.js --file bundle.js"
  },
  "devDependencies": {
    "rolldown": "^1.0.0"
  }
}
```

Now we can run the build with just:

::: code-group

```sh [vp]
$ vp run build
```

```sh [npm]
$ npm run build
```

```sh [pnpm]
$ pnpm run build
```

```sh [yarn]
$ yarn build
```

```sh [bun]
$ bun run build
```

:::

## Using the Config File

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:

```js [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](https://rollupjs.org/configuration-options), with some [notable additional features](./notable-features). See the [reference](/reference/) for the full list of options.

While exporting a plain object also works, it is recommended to utilize the [`defineConfig`](/reference/Function.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):

```json{5} [package.json]
{
  "name": "my-rolldown-project",
  "type": "module",
  "scripts": {
    "build": "rolldown -c"
  },
  "devDependencies": {
    "rolldown": "^1.0.0"
  }
}
```

### Multiple builds in the same config

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

```js [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](./notable-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](/builtin-plugins/) for more information.

Community plugins that are published to npm are listed in [Vite Plugin Registry](https://registry.vite.dev/plugins).

## Using the API

Rolldown provides a JavaScript API that is compatible with [Rollup's](https://rollupjs.org/javascript-api/), which separates `input` and `output` options:

```js
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:

```js
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](https://rollupjs.org/javascript-api/#rollup-watch).

```js
import { watch } from 'rolldown';

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

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

await watcher.close(); // This is different than rollup: rolldown returns a promise here.
```