---
url: /guide/in-depth/use-strict.md
---
# `"use strict"`

Before we dive into the details, let's first add a bit of context.

* ESM (ECMAScript Modules) is always in strict mode implicitly. [link](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode#strict_mode_for_modules).

This means that if you're using ESM, you don't need to add `"use strict"` at the top of your files. It's enabled by default.

* Strict mode isn't just a subset: it intentionally has different semantics from normal code.

## `format: 'esm'`

You don't need to care about `"use strict"`, if all your files are ESM.

Things will be a bit complicated, if your files contain commonjs modules. Since you want to emit ESM output, you have to ensure that your code of commonjs files is valid in strict mode. Rolldown will parse it in strict mode, and will throw an error if it's not valid.

With `format: 'esm'`, rolldown will parse you code in strict mode, and will throw an error that is related to strict mode. After parsing, rolldown will simply removes `"use strict"` from every module if it's present.

Emitted code will not contain `"use strict"`, because ESM is already in strict mode.

## `format: 'cjs'`

There will be several strategies to handle `"use strict"` while emitting commonjs output.

Rollup will always add `"use strict"` at the top of the output file, because it only accepts ESM input.

Esbuild emit `"use strict"` conditionally([link](https://github.com/evanw/esbuild/issues/2264#issuecomment-1138927861)) but not perfectly.

Esbuild also explains that it's almost not possible to handle `"use strict"` perfectly with mixed ESM and CJS modules with enabling scope hoisting([link](https://github.com/evanw/esbuild/issues/2381#issuecomment-1179765091)).

Rolldown choose to emit runnable code in maximum possibility.

Rolldown will only add `"use strict"` in each chunk, if all modules of that chunk are satisfied in following conditions:

* ESM
* Commonjs module with `"use strict"` at the top of the file

Otherwise, it will not add `"use strict"` in the chunk. Notice that, this changes the semantics of the original ESM code, because `"use strict"` is not added in the chunk.

With `format: 'cjs'`, rolldown will first parse your code in strict mode, and will re-parse it in non-strict mode if it throws an error in the first parsing.

See here for more details about what are affected by `"use strict"` [link](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode#changes_in_strict_mode).

---

---
url: /guide/in-depth/advanced-chunks.md
---
# Advanced Chunks

Advanced chunks are a powerful feature that allows you manually control the chunking of your code. This is useful when you want to optimize the loading of your application by splitting it into smaller, more manageable pieces.

## Limitations

### Why there's always a `runtime.js` chunk?

tl;dr: If you used `advancedChunks` option, rolldown will forcefully generate a `runtime.js` chunk to ensure that the runtime code is always executed before any other chunks.

The `runtime.js` chunk is a special chunk that **only** contains the runtime code necessary for loading and executing your application. It is generated forcefully by the bundler to ensure that the runtime code is always executed before any other chunks.

Since advanced chunks allows you to move modules between chunks, it's easily to create a circular import in the output code. This can lead to a situation where the runtime code is not executed before the other chunks, causing errors in your application.

A example output code with circular import:

```js
// first.js
import { __esm, __export, init_second, value$1 as value } from './second.js';
var first_exports = {};
__export(first_exports, { value: () => value$1 });
var value$1;
var init_first = __esm({
  'first.js'() {
    init_second();
    // ...
  },
});
export { first_exports, init_first, value$1 as value };

// main.js
import { first_exports, init_first } from './first.js';
import { __esm, init_second, second_exports } from './second.js';

var init_main = __esm({
  'main.js'() {
    init_first();
    init_second();
    // ...
  },
});

init_main();

// second.js
import { init_first, value } from './first.js';
var __esm = '...';
var __export = '...';

var second_exports = {};
__export(second_exports, { value: () => value$1 });
var value$1;
var init_second = __esm({
  'second.js'() {
    init_first();
    // ...
  },
});

export { __esm, __export, init_second, second_exports, value$1 };
```

When we run `node ./main.js`, the traversal order of the modules would be `main.js` -> `first.js` -> `second.js`. The module execution order would be `second.js` -> `first.js` -> `main.js`.

`second.js` tries to call `__esm` function before it gets initialized. This will lead to a runtime error which is trying to call `undefined` as a function.

With forcefully generated `runtime.js`, the bundler ensures any chunk that depends on runtime code would first load `runtime.js` before executing itself. This guarantees that the runtime code is always executed before any other chunks, preventing circular import issues.

---

---
url: /reference/bundler-api.md
---
# Bundler API

:::warning 🚧 Under Construction
We are working on creating a more detailed reference. For now, please refer to [Getting Started](/guide/getting-started#using-the-api).
:::

---

---
url: /guide/in-depth/bundling-cjs.md
---
# Bundling CJS

Rolldown provides first-class support for CommonJS modules. This document explains how Rolldown handles CJS modules and their interoperability with ES modules.

## Key Features

### Native CJS Support

Rolldown automatically recognizes and processes CommonJS modules without requiring any additional plugins or packages. This native support means:

* No need to install extra dependencies
* Better performance compared to plugin-based solutions

### On-demand Execution

Rolldown preserves the on-demand execution semantics of CommonJS modules, which is a key feature of the CommonJS module system. This means modules are only executed when they are actually required.

Here's an example:

```js
// index.js
import { value } from './foo.js';

const getFooExports = () => require('./foo.js');

// foo.js
module.exports = { value: 'foo' };
```

When bundled, it produces:

```js
// #region rolldown:runtime
// ...runtime code
// #endregion

// #region foo.js
var require_foo = __commonJS({
  'foo.js'(exports, module) {
    module.exports = { value: 'foo' };
  },
});

// #endregion
// #region index.js
const getFooExports = () => require_foo();
// #endregion
```

In this example, the `foo.js` module won't be executed until `getFooExports()` is called, maintaining the lazy-loading behavior of CommonJS.

### ESM/CJS Interoperability

Rolldown provides seamless interoperability between ES modules and CommonJS modules.

Example of ESM importing from CJS:

```js
// index.js
import { value } from './foo.js';

console.log(value);

// foo.js
module.exports = { value: 'foo' };
```

Bundled output:

```js
// #region rolldown:runtime
// ...runtime code
// #endregion

// #region foo.js
var require_foo = __commonJS({
  'foo.js'(exports, module) {
    module.exports = { value: 'foo' };
  },
});

// #endregion
// #region index.js
var import_foo = __toESM(require_foo());
console.log(import_foo.value);

// #endregion
```

The `__toESM` helper ensures that CommonJS exports are properly converted to ES module format, allowing seamless access to the exported values.

## `require` external modules

When [`platform: 'node'`](../features.md#platform-presets) is set, Rolldown will generate a `require` function from [`module.createRequire`](https://nodejs.org/docs/latest/api/module.html#modulecreaterequirefilename).

For other platforms, Rolldown will leave it as it is, so ensure that the running environment provides a `require` function or inject one manually.

For example, you can inject the `require` function that returns the value obtained by `import` by using [`inject` feature](../features.md#inject).

::: code-group

```js [rolldown.config.js]
import path from 'node:path';
export default {
  inject: {
    require: path.resolve('./require.js'),
  },
};
```

```js [require.js]
import fs from 'node:fs';

export default (id) => {
  if (id === 'node:fs') {
    return fs;
  }
  throw new Error(`Requiring ${JSON.stringify(id)} is not allowed.`);
};
```

:::

## Future Plans

Rolldown's first-class support for CommonJS modules enables several potential optimizations:

* Advanced tree-shaking capabilities for CommonJS modules
* Better dead code elimination

---

---
url: /reference/cli.md
---
# Command Line Interface

:::warning 🚧 Under Construction
For now this is just the output of `rolldown --help`.
:::

```sh
USAGE rolldown -c <config> or rolldown <input> <options>

OPTIONS

  --config -c, <filename>     Path to the config file (default: rolldown.config.js).
  --dir -d, <dir>             Output directory, defaults to dist if file is not set.
  --external -e, <external>   Comma-separated list of module ids to exclude from the bundle <module-id>,....
  --format -f, <format>       Output format of the generated bundle (supports esm, cjs, and iife).
  --globals -g, <globals>     Global variable of UMD / IIFE dependencies (syntax: key=value).
  --help -h,                  Show help.
  --minify -m,                Minify the bundled file.
  --name -n, <name>           Name for UMD / IIFE format outputs.
  --file -o, <file>           Single output file.
  --platform -p, <platform>   Platform for which the code should be generated (node, browser, neutral).
  --sourcemap -s, <sourcemap> Generate sourcemap (-s inline for inline, or pass the -s on the last argument if you want to generate .map file).
  --version -v,               Show version number.
  --watch -w,                 Watch files in bundle and rebuild on changes.
  --advanced-chunks.min-share-count <advanced-chunks.min-share-count>Minimum share count of the chunk.
  --advanced-chunks.min-size <advanced-chunks.min-size>Minimum size of the chunk.
  --asset-file-names <name>   Name pattern for asset files.
  --banner <banner>           Code to insert the top of the bundled file (outside the wrapper function).
  --checks.circular-dependency Whether to emit warnings when detecting circular dependencies.
  --chunk-file-names <name>   Name pattern for emitted secondary chunks.
  --comments <comments>       Control comments in the output.
  --css-chunk-file-names <css-chunk-file-names>Name pattern for emitted css secondary chunks.
  --css-entry-file-names <css-entry-file-names>Name pattern for emitted css entry chunks.
  --cwd <cwd>                 Current working directory.
  --define <define>           Define global variables.
  --drop-labels <drop-labels> Remove labeled statements with these label names.
  --entry-file-names <name>   Name pattern for emitted entry chunks.
  --es-module                 Always generate __esModule marks in non-ESM formats, defaults to if-default-prop (use --no-esModule to always disable).
  --exports <exports>         Specify a export mode (auto, named, default, none).
  --extend                    Extend global variable defined by name in IIFE / UMD formats.
  --footer <footer>           Code to insert the bottom of the bundled file (outside the wrapper function).
  --hash-characters <hash-characters>Use the specified character set for file hashes.
  --inject <inject>           Inject import statements on demand.
  --inline-dynamic-imports    Inline dynamic imports.
  --intro <intro>             Code to insert the top of the bundled file (inside the wrapper function).
  --jsx.development           Development specific information.
  --jsx.factory <jsx.factory> Jsx element transformation.
  --jsx.fragment <jsx.fragment>Jsx fragment transformation.
  --jsx.import-source <jsx.import-source>Import the factory of element and fragment if mode is classic.
  --jsx.jsx-import-source <jsx.jsx-import-source>Import the factory of element and fragment if mode is automatic.
  --jsx.mode <jsx.mode>       Jsx transformation mode.
  --jsx.refresh               React refresh transformation.
  --log-level <log-level>     Log level (silent, info, debug, warn).
  --module-types <types>      Module types for customized extensions.
  --no-external-live-bindings Disable external live bindings.
  --no-treeshake              Disable treeshaking.
  --outro <outro>             Code to insert the bottom of the bundled file (inside the wrapper function).
  --shim-missing-exports      Create shim variables for missing exports.

EXAMPLES

  1. Bundle with a config file rolldown.config.mjs:
    rolldown -c rolldown.config.mjs

  2. Bundle the src/main.ts to dist with cjs format:
    rolldown src/main.ts -d dist -f cjs

  3. Bundle the src/main.ts and handle the .png assets to Data URL:
    rolldown src/main.ts -d dist --moduleTypes .png=dataurl

  4. Bundle the src/main.tsx and minify the output with sourcemap:
    rolldown src/main.tsx -d dist -m -s

  5. Create self-executing IIFE using external jQuery as $ and _:
    rolldown src/main.ts -d dist -n bundle -f iife -e jQuery,window._ -g jQuery=$

NOTES

  * Due to the API limitation, you need to pass -s for .map sourcemap file as the last argument.
  * If you are using the configuration, please pass the -c as the last argument if you ignore the default configuration file.
  * CLI options will override the configuration file.
  * For more information, please visit https://rolldown.rs/.
```

---

---
url: /reference/config-options.md
---
# Config Options

:::warning 🚧 Under Construction
We are working on generating a more detailed reference. For now, please refer to [Rollup's Config Options Reference](https://rollupjs.org/configuration-options/) and documentation on additional [notable features](/guide/features).
:::

---

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

:::warning 🚧 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

::: code-group

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

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

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

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

:::

### Release Channels

* [latest](https://www.npmjs.com/package/rolldown?activeTab=versions): currently `1.0.0-beta.*`.
* [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.

### Using the CLI in npm scripts

To avoid typing the long command, we can move it inside an npm 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-beta.1"
  }
}
```

Now we can run the build with just:

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

```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](./features.md).

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):

```json{5} [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:

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

```js [rolldown.config.ts]
import { defineConfig } from 'rolldown';

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

:::warning 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.

```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](./features.md) that make it unnecessary to use 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([/* multiply option */] )

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

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

---

---
url: /guide.md
---
# Introduction

## What is a Bundler

In JavaScript development, a bundler is responsible for compiling small pieces of code (ESM or CommonJS modules) into something larger and more complex, such as a library or application.

For web applications, this makes your application load and run significantly faster (even with HTTP/2). For libraries, this can avoid your consuming application having to bundle the source again, and can also improve runtime execution performance.

For those interested in the details, we have written a deeper analysis on [why bundlers are still needed](/guide/in-depth/why-bundlers).

## Why Rolldown

Rolldown is primary designed to serve as the underlying bundler in [Vite](https://vite.dev/), with the goal to replace [esbuild](https://esbuild.github.io/) and [Rollup](https://rollupjs.org/) (which are currently used in Vite as dependencies) with one unified build tool. Here's why we are implementing a new bundler from the ground up:

* **Performance**: Rolldown is written in Rust. It is on the same performance level with esbuild and [10~30 times faster than Rollup](https://github.com/rolldown/benchmarks). Its WASM build is also [significantly faster than esbuild's](https://x.com/youyuxi/status/1869608132386922720) (due to Go's sub-optimal WASM compilation).

* **Ecosystem Compatibility**: Rolldown supports the same plugin API with Rollup / Vite, ensuring compatibility with Vite's existing ecosystem.

* **Additional Features**: Rolldown provides some important features needed in Vite but unlikely to be implemented by esbuild and Rollup (details below).

Although designed for Vite, Rolldown is also fully capable of being used as a standalone, general-purpose bundler. It can serve as a drop-in replacement for Rollup in most cases, and can also be used as an esbuild alternative when better chunking control is needed.

## Rolldown's Feature Scope

Rolldown provides largely compatible APIs (especially the plugin interface) with Rollup, and has similar treeshaking capabilities for bundle size optimization.

However, Rolldown's feature scope is more similar to esbuild, offering these [additional features](./features.md) as built-in:

* Platform presets
* TypeScript / JSX / syntax lowering transforms
* Node.js compatible module resolution
* ESM / CJS module interop
* `define`
* `inject`
* CSS bundling (Experimental)
* Minification (WIP)

Rolldown also has a few concepts that have close equivalents in esbuild, but do not exist in Rollup:

* [Module Types](./features#module-types) (Experimental)
* [Plugin hook filters](./plugin-development#plugin-hook-filters)

Finally, Rolldown provides some features that esbuild and Rollup do not (and may not intend to) implement:

* [Advanced chunk splitting control](./features#advanced-chunks) (Experimental)
* HMR support (WIP)
* Module Federation (planned)

## Credits

Rolldown wouldn't exist without all the lessons we learned from other bundlers like [esbuild](https://esbuild.github.io/), [Rollup](https://rollupjs.org/), [webpack](https://webpack.js.org/), and [Parcel](https://parceljs.org/). We have the utmost respect and appreciation towards the authors and maintainers of these important projects.

---

---
url: /guide/in-depth/module-types.md
---
# Module Types

As a web bundler, JavaScript is not the only file type with built-in support in Rolldown. For example, Rolldown can handle TypeScript and JSX files directly, parsing and transforming them to JavaScript before bundling them. We refer to these file types with first-class support in Rolldown as **Module Types**.

## How module types affect users

End users usually do not need to concern themselves with Module Types, since Rolldown automatically recognizes and handles known Module Types.

By default, Rolldown determines the module type of a module based on its file extension. However, in some cases this may not be sufficient. For example, imagine a file containing JSON data, but its extension is `.data`. Rolldown can't recognize it as a JSON file because the extension is not `.json`.

In this case, users need to explicitly tell Rolldown that files with the `.data` extension should be treated as the JSON module type. This can be done via the `moduleTypes` option in the config:

```js [rolldown.config.js]
export default {
  moduleTypes: {
    '.data': 'json',
  },
};
```

## Module types and plugins

Plugins can specify the module type of a specific file via the `load` hook and the `transform` hook:

```js
const myPlugin = {
  load(id) {
    if (id.endsWith('.data')) {
      return {
        code: '...',
        moduleType: 'json',
      };
    }
  },
};
```

The main significance of module types is that it provides a central convention for supported types, making it easier to chain multiple plugins that need to operate on the same module type.

For example, `@vitejs/plugin-vue` currently creates virtual css modules for the style blocks in `.vue` files and append `?lang=css` to the id of a virtual module, allowing these modules to be recognized as css by the vue plugin. However, this is only a convention of the vue plugin - other plugins may ignore the query string and thus not recognize the convention.

With module types, `@vitejs/plugin-vue` can explicitly specify the module type of virtual css modules as `css`, and other plugins like the postcss plugin can process these css modules without being aware of the vue plugin.

Another example: to add support for `.jsonc` files, a plugin could simply strip comments of `.jsonc` files in the `load` hook and return `moduleType: 'json'`. Rolldown will handle the rest.

---

---
url: /guide/features.md
---
# Notable Features

This page documents some notable features in Rolldown that do not have built-in equivalents in Rollup.

## Platform presets

* Configurable via the `platform` option.
* Default: `browser`
* Possible values: `browser | node | neutral`

Similar to [esbuild's `platform` option](https://esbuild.github.io/api/#platform), this option provides some sensible defaults regarding module resolution and how to handle `process.env.NODE_ENV`.

**Notable differences from esbuild:**

* The default output format is always `esm` regardless of platform.
* No `</script>` escape behavior when platform is `browser`.

:::tip
Rolldown does not polyfill Node built-ins when targeting the browser. You can opt-in to it with [rolldown-plugin-node-polyfills](https://github.com/rolldown/rolldown-plugin-node-polyfills).
:::

## Built-in transforms

Rolldown supports the following transforms out of the box, powered by [Oxc](https://github.com/oxc-project/oxc):

* TypeScript
* JSX
  * Configurable via the `jsx` option, aligned with [Rollup's `jsx` option](https://rollupjs.org/configuration-options/#jsx)
* Syntax lowering transforms WIP
  * Landing soon, configurable via the `target` option

## ESM / CJS Interop

Rolldown handles mixed ESM / CJS module graphs out of the box, without the need for `@rollup/plugin-commonjs`. It largely follows esbuild's semantics and [passes all esbuild ESM / CJS interop tests](https://github.com/rolldown/bundler-esm-cjs-tests).

## Module resolution

* Powered by [oxc-resolver](https://github.com/oxc-project/oxc-resolver), aligned with webpack's [enhanced-resolve](https://github.com/webpack/enhanced-resolve)
* `node_modules` resolution is enabled by default (equivalent of `@rollup/plugin-node-resolve`)
* tsconfig paths supported via `resolve.tsconfigFilename`.
* Configurable via the `resolve` option:

  ```ts
  interface InputOptions {
    resolve?: {
      alias?: Record<string, string[] | string>;
      aliasFields?: string[][];
      conditionNames?: string[];
      extensionAlias?: Record<string, string[]>;
      exportsFields?: string[][];
      extensions?: string[];
      mainFields?: string[];
      mainFiles?: string[];
      modules?: string[];
      symlinks?: boolean;
      tsconfigFilename?: string;
    };
  }
  ```

  When `tsconfigFilename` is provided, the resolver will respect `compilerOptions.paths` in the specified `tsconfig.json`.

## Define

* Configurable via the `define` option.

This feature provides a way to replace global identifiers with constant expressions. Aligns with the respective options in [Vite](https://vite.dev/config/shared-options.html#define) and [esbuild](https://esbuild.github.io/api/#define).

Note it behaves differently from [`@rollup/plugin-replace`](https://github.com/rollup/plugins/tree/master/packages/replace) as the replacement is AST-based, so the value to be replaced must be a valid identifier or member expression.

## Inject

* Configurable via the `inject` option.

This is the feature equivalent of [esbuild's `inject` option](https://esbuild.github.io/api/#inject) and [`@rollup/plugin-inject`](https://github.com/rollup/plugins/tree/master/packages/inject).

The API is aligned with `@rollup/plugin-inject`:

```js [rolldown.config.js]
export default {
  inject: {
    // import { Promise } from 'es6-promise'
    Promise: ['es6-promise', 'Promise'],

    // import { Promise as P } from 'es6-promise'
    P: ['es6-promise', 'Promise'],

    // import $ from 'jquery'
    $: 'jquery',

    // import * as fs from 'node:fs'
    fs: ['node:fs', '*'],

    // Inject shims for property access pattern
    'Object.assign': path.resolve('src/helpers/object-assign.js'),
  },
};
```

## CSS bundling

* ⚠️ Experimental

Rolldown supports bundling CSS imported from JS out of the box. Note this feature currently does not support CSS Modules and minification.

## Advanced Chunks

* ⚠️ Experimental
* Similar to webpack's [`optimization.splitChunks`](https://webpack.js.org/plugins/split-chunks-plugin/#optimizationsplitchunks)
* Configurable via `output.advancedChunks`:

```ts
interface OutputOptions {
  advancedChunks?: {
    minSize?: number;
    minShareCount?: number;
    groups?: {
      name: string;
      test?: StringOrRegExp;
      priority?: number;
      minSize?: number;
      minShareCount?: number;
    }[];
  };
}
```

## Module types

* ⚠️ Experimental

This is conceptually similar to [esbuild's `loader` option](https://esbuild.github.io/api/#loader), allowing users to globally associate file extensions to built-in module types via the `moduleTypes` option, or specify module type of a specific module in plugin hooks. It is discussed in more details [here](/guide/in-depth/module-types).

## Minification

* ⚠️ WIP
* Configurable via the `output.minify` option.

This is powered by [`oxc-minifier`](https://github.com/oxc-project/oxc/tree/main/crates/oxc_minifier), which is currently still work-in-progress. There is no configurability yet and the compression quality is not production ready. Expect improvements in the future!

For now, it is recommended to use an external minifier for production use cases. Rolldown is compatible with Rollup minifier plugins:

With [`rollup-plugin-esbuild`](https://github.com/egoist/rollup-plugin-esbuild):

```js [rolldown.config.js]
import { defineConfig } from 'rolldown';
import { minify } from 'rollup-plugin-esbuild';

export default defineConfig({
  plugins: [minify()],
});
```

With [`rollup-plugin-swc3`](https://github.com/SukkaW/rollup-plugin-swc):

```js [rolldown.config.js]
import { defineConfig } from 'rolldown';
import { minify } from 'rollup-plugin-swc3';

export default defineConfig({
  plugins: [
    minify({
      module: true,
      // swc's minify option here
      mangle: {},
      compress: {},
    }),
  ],
});
```

---

---
url: /reference/plugin-api.md
---
# Plugin API

:::warning 🚧 Under Construction
We are working on creating a more detailed reference. For now, please refer to [Rollup's Plugin API](https://rollupjs.org/plugin-development/).
:::

---

---
url: /guide/plugin-development.md
---
# Plugin Development

Rolldown's plugin interface is almost fully compatible with Rollup's (detailed tacking [here](https://github.com/rolldown/rolldown/issues/819)), so if you have written a Rollup plugin before, you already know how to write a Rolldown plugin!

We are still working on creating a more detailed guide for users who are new to both Rollup and Rolldown. For now, please first refer to [Rollup's plugin development guide](https://rollupjs.org/plugin-development/).

## Plugin hook filters

One important thing to note for JavaScript plugins in Rolldown is that every plugin hook call incurs a small communication overhead between Rust and the JavaScript runtime (i.e. Node.js).

Consider the following plugin:

```js{5}
export default function myPlugin() {
  return {
    name: 'example',
    transform(code, id) {
      if (!id.endsWith('.data')) {
        // early return
        return
      }
      // perform actual transform
      return transformedCode
    },
  }
}
```

Line 5 is a very common pattern in Rollup plugins: check the file extension of a module inside the plugin hook to determine whether it needs to be processed.

However, this would be sub-optimal in a Rust bundler like Rolldown. Imagine this plugin is used in a large app with thousands of modules - Rolldown would have to invoke a Rust-to-JS call for every module, and in many cases just for the plugin to find out it doesn't actually need to do anything. Due to the single-threaded nature of JavaScript, unnecessary Rust-to-JS calls can also de-optimize parallelization.

Ideally, we want to be able to determine whether a plugin hook needs to be invoked at all without leaving Rust. This is why Rolldown augments Rollup plugin's object hook format with the additional `filter` property. The above plugin can be updated to:

```js{5}
export default function myPlugin() {
  return {
    name: 'example',
    transform: {
      filter: {
        id: /\.data$/
      },
      handler (code) {
        // perform actual transform
        return transformedCode
      },
    }
  }
}
```

Rolldown can now compile and execute the regular expression on the Rust side, and can avoid invoking JS if the filter does not match.

In addition to `id`, you can also filter based on `moduleType` and the module's source code. The `filter` property works similarly to [`createFilter` from `@rollup/pluginutils`](https://github.com/rollup/plugins/blob/master/packages/pluginutils/README.md#createfilter). Here are some important details:

* If multiple values are passed to `include`, the filter matches if **any** of them match.
* If a filter has both `include` and `exclude`, `exclude` takes precedence.
* If multiple filter properties are specified, the filter matches when all of the specified properties match. In other words, if even one property fails to match, it is excluded, regardless of the other properties. For example, the following filter matches a module only if its file names ends with `.js`, its source code contains `foo`, and does not contain `bar`:
  ```js
  {
    id: {
      include: /\.js$/,
      exclude: /\.ts$/
    },
    code: {
      include: 'foo',
      exclude: 'bar'
    }
  }
  ```

Full `HookFilter` interface for the `filter` property:

````ts
interface HookFilter {
  /**
   * This filter is used to do a pre-test to determine whether the hook should be called.
   *
   * @example
   * Include all `id`s that contain `node_modules` in the path.
   * ```js
   * { id: '**'+'/node_modules/**' }
   * ```
   * @example
   * Include all `id`s that contain `node_modules` or `src` in the path.
   * ```js
   * { id: ['**'+'/node_modules/**', '**'+'/src/**'] }
   * ```
   * @example
   * Include all `id`s that start with `http`
   * ```js
   * { id: /^http/ }
   * ```
   * @example
   * Exclude all `id`s that contain `node_modules` in the path.
   * ```js
   * { id: { exclude: '**'+'/node_modules/**' } }
   * ```
   * @example
   * Formal pattern to define includes and excludes.
   * ```
   * { id : {
   *   include: ['**'+'/foo/**', /bar/],
   *   exclude: ['**'+'/baz/**', /qux/]
   * }}
   * ```
   */
  id?: StringFilter;
  moduleType?: ModuleTypeFilter;
  code?: StringFilter;
}
````

The following properties are supported by each hook:

* `resolveId` hook: `id`
* `load` hook: `id`
* `transform` hook: `id`, `moduleType`, `code`

> \[!NOTE]
> `id` is treated as a glob pattern when you pass a `string`, and treated as a regular expression when you pass a `RegExp`.
> In the `resolve` hook, `id` must be a `RegExp`. `string`s are not allowed.
> This is because the `id` value in `resolveId` is the exact text written in the import statement and usually not an absolute path, while glob patterns are designed to match absolute paths.

---

---
url: /guide/in-depth/tla-in-rolldown.md
---
# Top Level Await(TLA) in Rolldown

Background knowledge:

* https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#top\_level\_await
* https://github.com/tc39/proposal-top-level-await

## How rolldown handles TLA

At this point, the principle of supporting TLA in rolldown is: we will make it work after bundling without preserving 100% semantic as the original code.

Current rules are:

* If your input contains TLA, it could only be bundled and emitted with `esm` format.
* `require` TLA module is forbidden.

## Concurrent to sequential

One downside of TLA in rolldown is that it will change the original code's behavior from concurrent to sequential. It still ensures the relative order but indeed slows down the execution.

A real-world example would looks like

```js
// main.js
import { bar } from './sync.js';
import { foo1 } from './tla1.js';
import { foo2 } from './tla2.js';
console.log(foo1, foo2, bar);

// tla1.js

export const foo1 = await Promise.resolve('foo1');

// tla2.js

export const foo2 = await Promise.resolve('foo2');

// sync.js

export const bar = 'bar';
```

After bundling, it will be

```js
// tla1.js
const foo1 = await Promise.resolve('foo1');

// tla2.js
const foo2 = await Promise.resolve('foo2');

// sync.js
const bar = 'bar';

// main.js
console.log(foo1, foo2, bar);
```

You can see that, in bundled code, promise `foo1` and `foo2` are resolved sequentially, but in the original code, they are resolved concurrently.

There's a very [good example](https://github.com/tc39/proposal-top-level-await?tab=readme-ov-file#semantics-as-desugaring) of TLA spec repo, which explains the mental model of how the TLA works

```js
import { a } from './a.mjs';
import { b } from './b.mjs';
import { c } from './c.mjs';

console.log(a, b, c);
```

could be considered as the following code after desugaring:

```js
import { a, promise as aPromise } from './a.mjs';
import { b, promise as bPromise } from './b.mjs';
import { c, promise as cPromise } from './c.mjs';

export const promise = Promise.all([aPromise, bPromise, cPromise]).then(() => {
  console.log(a, b, c);
});
```

However, in rolldown, it will looks like this after bundling:

```js
import { a, promise as aPromise } from './a.mjs';
import { b, promise as bPromise } from './b.mjs';
import { c, promise as cPromise } from './c.mjs';

await aPromise;
await bPromise;
await cPromise;

console.log(a, b, c);
```

---

---
url: /guide/troubleshooting.md
---
# Troubleshooting

## Performance

Performance is a primary goal for Rolldown. However, build performance isn't solely determined by Rolldown itself. It's also significantly affected by the environment it runs in and the plugins used.

While we continuously strive to improve Rolldown to minimize these external factors, there are inherent limitations and areas where optimizations are still ongoing. This guide provides insights into potential bottlenecks and how you can mitigate them.

### Environment

The operating system and its configuration can impact build times, particularly file system operations.

#### Windows

File system access on Windows is generally slower compared to other operating systems like macOS or Linux. Especially, antivirus software can make this much worse. But even without interference from antivirus programs, baseline file system performance tends to be slower. It is 3 times slower than macOS and 10 times slower than Linux. This becomes a bottleneck when most of the transforms are done without a plugin.

To improve performance on Windows, consider using alternative file system environments:

1. [**Dev Drive**](https://learn.microsoft.com/en-us/windows/dev-drive/): A newer Windows feature designed for developer workloads, using the Resilient File System (ReFS). Using a Dev Drive can lead to a **2x to 3x speedup** compared to the standard Windows NTFS file system for file system operations.
2. [**Windows Subsystem for Linux (WSL)**](https://learn.microsoft.com/en-us/windows/wsl/): WSL lets Linux environment to run on Windows easily, which offers significantly better file system performance. Placing your project files and running the build process within WSL can result in speedups of around **10x** compared to the standard Windows NTFS file system for file system operations.

:::details Benchmark Reference

The benchmark script used is described in this blog post ([How fast can you open 1000 files?](https://lemire.me/blog/2025/03/01/how-fast-can-you-open-1000-files/)).

The results were:

|    File System / Threads |     1 |     2 |     4 |     8 |    16 |
| -----------------------: | ----: | ----: | ----: | ----: | ----: |
|             Windows NTFS | 286ms | 153ms |  85ms | 106ms | 110ms |
| Windows Dev Drive (ReFS) | 124ms |  67ms |  35ms |  48ms |  55ms |
|               WSL (ext4) |  24ms |  13ms | 7.8ms | 9.0ms |  13ms |

The benchmark was ran on the following environment:

* OS: Windows 11 Pro 23H2 22631.5189
* CPU: AMD Ryzen 9 5900X
* Memory: DDR4-3600 32GB
* SSD: Western Digital Black SN850X 1TB

:::

### Plugins

Plugins extend Rolldown's functionality, but can also introduce performance overhead.

#### Plugin Hook Filters

Rolldown provides a feature called **Plugin Hook Filters**. This allows you to specify precisely which modules a plugin hook should process, reducing the communication overhead between JavaScript and Rust. For detailed information on how filters work internally, refer to the [Plugin Development Guide - Hook Filters](/guide/plugin-development#plugin-hook-filters).

If you are a plugin user and the plugin you use does not have hook filters specified, you can apply them by using the `withFilter` utility function exported by Rolldown.

```js
import yaml from '@rollup/plugin-yaml';
import { defineConfig, withFilter } from 'rolldown';

export default defineConfig({
  plugins: [
    // Run the transform hook of the `yaml` plugin only for modules which end in `.yaml`
    withFilter(
      yaml({
        /*...*/
      }),
      { transform: { id: /\.yaml$/ } },
    ),
  ],
});
```

#### Leverage Built-in Features

Rolldown includes several built-in features designed for efficiency. Where possible, prefer using these native capabilities over external Rollup plugins that perform similar tasks. Relying on built-in functionality often means the processing happens entirely within Rust, allowing to process in parallel.

Check the [Rolldown Features](/guide/features) page for capabilities that does not exist in Rollup.

For example, the following common Rollup plugins may be replaced with Rolldown's built-in features:

* `@rollup/plugin-alias`: [`resolve.alias`](/reference/config-options#resolve-alias) option
* `@rollup/plugin-commonjs`: supported out of the box
* `@rollup/plugin-inject`: [`inject`](/reference/config-options#inject) option
* `@rollup/plugin-node-resolve`: supported out of the box
* `@rollup/plugin-json`: supported out of the box
* `@rollup/plugin-swc`, `@rollup/plugin-babel`, `@rollup/plugin-sucrase`: supported out of the box via Oxc (complex configurations might still require the plugin)
* `@rollup/plugin-terser`: `output.minify` option

---

---
url: /guide/in-depth/why-bundlers.md
---
# Why do we still need bundlers?

## Skipping the build step is impractical

With the general availability of native ES modules and HTTP/2 in modern browsers, some developers are advocating for an unbundled approach for shipping web applications, even in production. While this approach works for smaller applications, in our opinion bundling is still very much necessary if you are shipping anything non-trivial and care about performance (which translates to better user experience).

Even in a polished unbundled deployment model, a build step is still often unavoidable. Take Rails 8's default import-map-based approach for example: all JavaScript assets still go through a build step in order to fingerprint the assets and generate the import map and modulepreload directives. It's just handled via `importmap-rails` and Propshaft instead of a JavaScript bundler.

Moreover, the unbundled approach will hit its limits if you have any of the following requirements:

* Require modern JavaScript features like ES6+, TypeScript, or JSX.
* Need to leverage bundler-specific optimizations like tree-shaking, code splitting, or minification.
* Utilize libraries or frameworks that depend on a build step.
* Utilize NPM dependencies that ship unbundled source code (results in too many requests).

Going with unbundled means locking yourself out of a big part of the JS ecosystem and giving up on many possible performance optimizations that could benefit your end users.

The main argument of avoiding JavaScript bundlers is added complexity and slowing down the dev feedback loop. However, modern JS tooling has improved a lot on this front over the past few years. Our goal with Vite / Rolldown is to improve these aspects further and make the build step feel invisible.

## The case for bundlers

Fundamentally, bundlers exist because of the unique constraints of web applications: they need to be delivered over the network on-demand. Bundlers can make web applications more performant in three ways:

1. Reduce the amount of network requests and waterfalls.
2. Reduce total bytes sent over the network.
3. Improve JavaScript execution performance.

## Reduce network requests and waterfalls

The first important thing we need to acknowledge is that **HTTP/2 does not mean you can stop caring about number of HTTP requests**.

Although HTTP/2 theoretically supports unlimited multiplexing, most browsers / servers have a default limit of around 100 on the maximum number of concurrent streams per connection. Every network request also comes with fixed overhead (header processing, TLS encryption, multiplexing, etc.) on both the server and the client. More requests means more server load, and the actual concurrency is limited by how fast your server can serve the module files. Applications that contain thousands of unbundled modules will still create serious network bottlenecks even under HTTP/2.

Deep import chains also results in network waterfalls - i.e. the browser needs to make multiple network roundtrips to fetch the entire module graph. This can be mitigated to some extent with `modulepreload` directives, but generating these requires tooling support, and bloating the HTML with thousands of `modulepreload` directives in `<head>` is also a performance issue in itself.

Bundling can drastically reduce such overhead by combining thousands of modules into an optimal number of chunks that both the server and the browser can handle with ease. Bundling also flattens the import chain depth to reduce waterfalls, and can provide the data needed to generate `modulepreload` directives. In its essence, bundling moves the work of combining the module graph to the build phase, instead of incurring it as a runtime cost for every visitor. This makes large applications load significantly faster on initial visit, especially in poor network conditions.

### Trade-offs in caching strategy

One argument supporting the unbundled approach is that it allows each module to be cached individually, reducing the amount of cache invalidation when the application is updated. However, this comes with the trade-off of a much slower initial load as explained above.

Sub-optimal bundling configurations can cause cascading chunk hash validations, causing users to have to re-download a large part of the app when the app is updated. But this is a solvable problem: bundlers can also leverage import maps and advanced chunking control to limit hash invalidation and improve cache hit rate. We do intend to provide an improved, more caching-friendly default chunking strategy in Vite / Rolldown in the future.

## Reduce total bytes sent over the network

Bundling can also greatly reduce overall size of JavaScript sent over the wire.

First, bundles can hoist multiple modules into the same scope, removing all the import / export statements between them.

Second, treeshaking / dead code elimination is an optimization that can only be performed by statically analyzing the source code at build time. Native ESM loads and evaluates everything eagerly, so even if you only use a single export from a big module, the entire module has to be downloaded and evaluated. With a smart bundler, exports that are not used can be completely removed from the final bundle, saving lots of bytes.

Finally, minification and gzip / brotli compression are considerably more efficient when performed on bundled code compared to individual modules.

With these factors combined, users download less code, and your servers use less outbound bandwidth.

## Improve JavaScript execution performance

JavaScript is an interpreted language, and modern JavaScript engines often employ advanced JIT compilation to make it run faster. However, there is also non-trivial cost involved in parsing and compiling JavaScript.

Sending less JavaScript code not only saves bandwidth - it also means less JavaScript needs to be compiled and evaluated in the browser, leading to faster application startup time.

Some bundlers / minifiers also can perform optimizations like constant folding / ahead-of-time evaluation to varying extent, making the bundled code more efficient than their hand-written source.

***

In conclusion, bundling is still a beneficial, and in many cases necessary step in web development, and will continue to be so in the foreseeable future.