### Run `just setup`

Source: https://rolldown.rs/development-guide/setup-the-project

Executes the main setup script for the Rolldown project. Run this after cloning the repository to install all necessary dependencies and prepare the build environment.

```sh
just setup
```

--------------------------------

### Install heaptrack for memory profiling

Source: https://rolldown.rs/development-guide/profiling

Install heaptrack and heaptrack-gui. Example provided for Ubuntu. Note that heaptrack is Linux-only but works on WSL.

```bash
sudo apt install heaptrack heaptrack-gui
```

--------------------------------

### Get Rolldown CLI Help

Source: https://rolldown.rs/guide/getting-started

Display available command-line options and examples for Rolldown.

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

--------------------------------

### Install `just` using pnpm

Source: https://rolldown.rs/development-guide/setup-the-project

Installs the `just` command-line tool globally using pnpm. This is an alternative method for installing `just`.

```sh
pnpm --global add just-install
```

--------------------------------

### Example: TLA in Rolldown (After Bundling)

Source: https://rolldown.rs/in-depth/tla-in-rolldown

This is the bundled output of the previous example, demonstrating how TLA modules are processed sequentially.

```javascript
// 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);

```

--------------------------------

### Install `just` using npm

Source: https://rolldown.rs/development-guide/setup-the-project

Installs the `just` command-line tool globally using npm. This is one of the methods to satisfy the `just` prerequisite.

```sh
npm install --global just-install
```

--------------------------------

### Rolldown Module Placing Order Example

Source: https://rolldown.rs/in-depth/automatic-code-splitting

Demonstrates Rolldown's attempt to place modules in their declared order by emulating execution flow, starting from entry points.

```javascript
// entry.js
import { foo } from './foo.js';
console.log(foo);

// foo.js
export var foo = 'foo';
```

```javascript
// foo.js
var foo = 'foo';

// entry.js
console.log(foo);
```

--------------------------------

### Setup Benchmarks in Project Root

Source: https://rolldown.rs/development-guide/benchmarking

Run this command in the project root to set up necessary fixtures before benchmarking.

```shell
just setup-bench
```

--------------------------------

### Example: Initial App Output

Source: https://rolldown.rs/in-depth/manual-code-splitting

Illustrates the initial output structure with application code and bundled libraries in separate files.

```javascript
import ... from './libs-hash0.js';
// App.js
function App() {
  return <Button onClick={() => alert("Button clicked!")} />;
}

// index.js

ReactDom.createRoot(document.getElementById("root")).render(<App />);
```

```javascript
// node_modules/react/index.js
"React library code";

// node_modules/ui-lib/index.js
"UI library code";

// node_modules/react-dom/index.js
"ReactDOM library code";

export { ... };
```

--------------------------------

### Install `just` using Yarn

Source: https://rolldown.rs/development-guide/setup-the-project

Installs the `just` command-line tool globally using Yarn. This is another option for installing `just`.

```sh
yarn global add just-install
```

--------------------------------

### Basic Barrel Module Example

Source: https://rolldown.rs/in-depth/lazy-barrel-optimization

Illustrates a simple barrel module setup where only the imported module is compiled when lazy barrel optimization is enabled.

```javascript
// barrel/index.js
export { a } from './a';
export { b } from './b';

// main.js
import { a } from './barrel';
console.log(a);
```

--------------------------------

### Example: TLA in Rolldown (Before Bundling)

Source: https://rolldown.rs/in-depth/tla-in-rolldown

This example shows how `main.js` imports modules with Top Level Await (`tla1.js`, `tla2.js`) and a synchronous module (`sync.js`).

```javascript
// 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';

```

--------------------------------

### Start Docs Dev Server

Source: https://rolldown.rs/development-guide/docs

Run this command in the project root to start the docs dev server. Changes to markdown files will be reflected instantly.

```sh
pnpm run docs
```

--------------------------------

### Example File Structure

Source: https://rolldown.rs/glossary/entry-chunk

Illustrates a typical file structure for an application that can be run separately or used as a library.

```javascript
// component.js
export function component() {
  return 'Hello World';
}

// render.js
export function render(component) {
  console.log(component());
}

// app.js
import { component } from './component.js';
import { render } from './render.js';

render(component);

// lib.js
export { component } from './component.js';
```

--------------------------------

### Example: Parallel Library Loading Output

Source: https://rolldown.rs/in-depth/manual-code-splitting

Demonstrates the output structure when libraries are split into individual chunks for parallel download.

```javascript
import ... from './react-hash0.js';
import ... from './react-dom-hash0.js';
import ... from './ui-lib-hash0.js';

// App.js
function App() {
  return <Button onClick={() => alert("Button clicked!")} />;
}
// index.js
ReactDom.createRoot(document.getElementById("root")).render(<App />);
```

```javascript
"React library code";
export { ... };
```

```javascript
"ReactDOM library code";
export { ... };
```

```javascript
"UI library code";
export { ... };
```

--------------------------------

### Build and Preview Docs Site

Source: https://rolldown.rs/development-guide/docs

Use these commands to build the documentation site and then preview it. This step is optional if you are not modifying the docs build setup.

```sh
pnpm docs:build
pnpm docs:preview
```

--------------------------------

### Install `just` using Homebrew

Source: https://rolldown.rs/development-guide/setup-the-project

Installs the `just` command-line tool using the Homebrew package manager. This is a common method for macOS and Linux users.

```sh
brew install just
```

--------------------------------

### Install `just` using Cargo

Source: https://rolldown.rs/development-guide/setup-the-project

Installs the `just` command-line tool using Cargo, Rust's package manager. This is suitable if you have Rust and Cargo installed.

```sh
cargo install just
```

--------------------------------

### Example Plugin: Virtual Module

Source: https://rolldown.rs/apis/plugin-api

This example demonstrates how to create a Rolldown plugin that intercepts import requests for a virtual module and provides custom content for it.

```APIDOC
## Plugin Interface

The [`Plugin`](/reference/Interface.Plugin) interface has a required `name` property and multiple optional properties and hooks.

Hooks are methods defined on the plugin that can be used to interact with the build process. They are called at various stages of the build. Hooks can affect how a build is run, provide information about a build, or modify a build once complete. There are different kinds of hooks:

* `async`: The hook may also return a Promise resolving to the same type of value; otherwise, the hook is marked as `sync`.
* `first`: If several plugins implement this hook, the hooks are run sequentially until a hook returns a value other than `null` or `undefined`.
* `sequential`: If several plugins implement this hook, all of them will be run in the specified plugin order. If a hook is `async`, subsequent hooks of this kind will wait until the current hook is resolved.
* `parallel`: If several plugins implement this hook, all of them will be run in the specified plugin order. If a hook is `async`, subsequent hooks of this kind will be run in parallel and not wait for the current hook.

Instead of a method, hooks can also be objects with a `handler` property. In this case, the `handler` property is the actual hook method. This allows you to provide additional optional properties to control the behavior of the hook. See the [`ObjectHook`](/reference/TypeAlias.ObjectHook) type for more information.

There are two types of hooks: [build hooks](#build-hooks) and [output generation hooks](#output-generation-hooks).
```

--------------------------------

### Manual Chunking Example

Source: https://rolldown.rs/reference/outputoptions.manualchunks

This example demonstrates how to use the manualChunks option to group all modules from node_modules into a 'vendor' chunk. Other modules will not be manually chunked.

```javascript
{
  manualChunks: (moduleId, meta) => {
    if (moduleId.includes('node_modules')) {
      return 'vendor';
    }
    return null;
  }
}
```

--------------------------------

### Check Rolldown Installation via CLI

Source: https://rolldown.rs/guide/getting-started

Verify that Rolldown has been installed correctly by checking its version using the CLI.

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

--------------------------------

### Install samply

Source: https://rolldown.rs/development-guide/profiling

Install the samply profiler using cargo binstall. Note that samply has known issues on macOS.

```bash
cargo binstall samply
```

--------------------------------

### TLA Desugaring Example (Rolldown)

Source: https://rolldown.rs/in-depth/tla-in-rolldown

This example illustrates how Rolldown bundles code with Top Level Await, resulting in sequential `await` calls for module promises.

```javascript
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);

```

--------------------------------

### Install Rolldown with Package Managers

Source: https://rolldown.rs/guide/getting-started

Install Rolldown as a development dependency using your preferred package manager.

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

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

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

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

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

--------------------------------

### Component Implementation

Source: https://rolldown.rs/in-depth/dead-code-elimination

An example of a component file that imports its associated CSS. This CSS will be included if the component is used and marked as a side effect.

```javascript
import './Button.css';
export function Button(props) {
  /* ... */
}
```

--------------------------------

### Basic React App Structure

Source: https://rolldown.rs/in-depth/manual-code-splitting

This example shows a typical React application structure with imports for React DOM and a main App component. It's used to illustrate the input for code splitting.

```jsx
// index.jsx
import * as ReactDom from 'react-dom';
import App from './App.jsx';

ReactDom.createRoot(document.getElementById('root')).render(<App />);

// App.jsx
import * as React from 'react';
import { Button } from 'ui-lib';

export default function App() {
  return <Button onClick={() => alert('Button clicked!')} />;
}
```

--------------------------------

### Dynamic Rolldown Configuration

Source: https://rolldown.rs/apis/cli

An example of exporting a function from a Rolldown config file. This allows dynamic configuration based on command-line arguments.

```javascript
import { defineConfig } from 'rolldown';

export default defineConfig((commandLineArgs) => {
  if (commandLineArgs.watch) {
    // watch-specific config
  }
  return {
    input: 'src/main.js',
  };
});
```

--------------------------------

### Example: App Code Change Output

Source: https://rolldown.rs/in-depth/manual-code-splitting

Shows the output after an application code change, where only the application chunk is updated, leveraging the cached library chunk.

```javascript
import ... from './libs-hash0.js';
// App.js
function App() {
  return <Button onClick={() => alert("Button clicked!!!")} />;
}

// index.js

ReactDom.createRoot(document.getElementById("root")).render(<App />);
```

```javascript
// node_modules/react/index.js
"React library code";

// node_modules/ui-lib/index.js
"UI library code";

// node_modules/react-dom/index.js
"ReactDOM library code";

export { ... };
```

--------------------------------

### Example of Recursive Dependency Inclusion

Source: https://rolldown.rs/in-depth/manual-code-splitting

Demonstrates how Rolldown includes dependencies recursively when grouping modules. This can lead to changes in entry chunk export signatures.

```javascript
// entry.js
import { value } from './a.js';

console.log(value);

export const foo = 'foo';

// a.js
import { valueB } from './b.js';
export const value = 'a' + valueB;

// b.js
export const value = 'b';

```

```javascript
// entry.js
import { value } from './a.js';

// b.js
const value = 'b';

// entry.js
const foo = 'foo';
console.log(value);

export { foo, value };

```

```javascript
// a.js
import { value } from './entry.js';

// a.js
export const value = 'a' + value;

```

--------------------------------

### Input and Transformed Output Example

Source: https://rolldown.rs/builtin-plugins/esm-external-require

Illustrates how the plugin transforms a CommonJS require() call for an external dependency into a reference to a virtual module, which then handles the ESM import.

```javascript
// Input code
const react = require('react');

// Transformed output
const react = require('builtin:esm-external-require-react');

// Virtual module: builtin:esm-external-require-react
import * as m from 'react';
module.exports = m;
```

--------------------------------

### Rolldown Plugin Example: Virtual Module

Source: https://rolldown.rs/apis/plugin-api

This plugin intercepts import requests for 'example-virtual-module' and provides custom content. It demonstrates the `resolveId` and `load` hooks for creating virtual modules. Use this pattern to inject helper functions or generated code.

```javascript
const id = 'example-virtual-module';
const resolvedId = '\0' + id;

export default function examplePlugin() {
  return {
    name: 'example-plugin', // this name will show up in logs and errors
    resolveId(source) {
      if (source === id) {
        // this signals to Rolldown that this import should resolve to a module named `\0example-virtual-module`
        return resolvedId;
      }
      return null; // other ids should be handled as usual
    },
    load(id) {
      if (id === resolvedId) {
        // the source code for `\0example-virtual-module`
        return `export default 'Hello from ${id}';`;
      }
      return null; // other ids should be handled as usual
    },
  };
}
```

```javascript
import { defineConfig } from 'rolldown';
import examplePlugin from './rolldown-plugin-example.js';

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

--------------------------------

### Automatic Code Splitting Example

Source: https://rolldown.rs/in-depth/automatic-code-splitting

Demonstrates how static and dynamic imports lead to the creation of separate chunks. 'entry.js' and 'foo.js' form one chunk due to static import, while 'dyn-entry.js' and 'bar.js' form another due to dynamic import.

```javascript
// entry.js (included in `input` option)
import foo from './foo.js';
import('./dyn-entry.js');

// dyn-entry.js
require('./bar.js');

// foo.js
export default 'foo';

// bar.js
module.exports = 'bar';
```

--------------------------------

### Plugin with Filter and Fallback for Older Versions

Source: https://rolldown.rs/apis/plugin-api/hook-filters

This example demonstrates how to create a plugin that uses filters for newer versions of Rollup/Vite and Rolldown, while providing a fallback mechanism for older versions. The internal check within the handler ensures compatibility.

```javascript
const idFilter = /\.data$/;

export default function myPlugin() {
  return {
    name: 'my-plugin',
    transform: {
      // Filter is used by Rolldown and newer Rollup/Vite versions
      filter: { id: idFilter },
      // Handler is called when filter matches
      handler(code, id) {
        // Double-check in handler for compatibility with older versions
        // This is only necessary if you're supporting older versions
        if (!idFilter.test(id)) {
          return null;
        }
        // perform actual transform
        return transformedCode;
      },
    },
  };
}
```

--------------------------------

### Mixed Exports Example

Source: https://rolldown.rs/in-depth/lazy-barrel-optimization

Demonstrates a barrel module with a mix of export types, showcasing how lazy barrel optimization prioritizes named exports before considering star exports.

```javascript
export { a } from './a';
export * as ns from './b';
export * from './others';
export * from './more';
```

--------------------------------

### Configuring Custom `require` Injection

Source: https://rolldown.rs/in-depth/bundling-cjs

Shows how to inject a custom `require` function for specific modules when bundling for environments that may not fully support `module.createRequire`. This example restricts requiring 'node:fs' and throws an error for others.

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

```javascript
import fs from 'node:fs';

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

--------------------------------

### Replacement Order Example

Source: https://rolldown.rs/builtin-plugins/replace

The plugin sorts keys by length descending to prevent partial replacements, ensuring longer, more specific replacements are processed first. This is crucial for overlapping keys like `API_URL` and `API_URL_V2`.

```js
// Input code:
const apiV2 = API_URL_V2;
const api = API_URL;

replacePlugin({
  API_URL: '"https://api.example.com"',
  API_URL_V2: '"https://api.example.com/v2"',
});

// Without length sorting (❌ wrong):
// const apiV2 = "https://api.example.com"_V2;  // Incorrect!
// const api = "https://api.example.com";

// With length sorting (✅ correct):
// const apiV2 = "https://api.example.com/v2";  // API_URL_V2 matched first
// const api = "https://api.example.com";       // Then API_URL matched
```

--------------------------------

### Rolldown Bundling with Dynamic Imports

Source: https://rolldown.rs/in-depth/automatic-code-splitting

Illustrates a scenario where Rolldown prioritizes singleton module guarantees over original declaration order, potentially leading to unexpected runtime behavior. This example shows how shared modules are grouped.

```javascript
// entry.js (included in `input` option)
import './setup.js';
import './execution.js';

import('./dyn-entry.js');

// setup.js
globalThis.value = 'hello, world';

// execution.js
console.log(globalThis.value);

// dyn-entry.js
import './execution.js';
```

```javascript
// entry.js [entry.js]
import './common-execution.js';

// setup.js
globalThis.value = 'hello, world';
```

```javascript
// dyn-entry.js [dyn-entry.js]
import './common-execution.js';
```

```javascript
// common-execution.js [common-execution.js]
console.log(globalThis.value);
```

--------------------------------

### Dynamic Import Entry Point

Source: https://rolldown.rs/in-depth/lazy-barrel-optimization

When a barrel module is dynamically imported, it becomes an entry point, and all its exports must be available. This example shows how importing './index.js' makes the barrel an entry point.

```javascript
// barrel/a.js
export const a = 'a';
import('./index.js'); // makes barrel an entry point

// barrel/index.js
export { a } from './a';
export { b } from './b'; // b.js will be loaded
```

--------------------------------

### Filter by Multiple Properties

Source: https://rolldown.rs/apis/plugin-api/hook-filters

This example shows how to specify multiple filter properties (`id`, `code`) to create a more specific filter. The filter matches only if all specified properties match.

```javascript
{
  id: {
    include: /\.js$/,
    exclude: /\.ts$/
  },
  code: {
    include: 'foo',
    exclude: 'bar'
  }
}
```

--------------------------------

### Constructor

Source: https://rolldown.rs/reference/Class.Visitor

Initializes a new instance of the Visitor class.

```APIDOC
## Constructor

### Description
Initializes a new instance of the Visitor class.

### Parameters
#### visitor
- **visitor** (VisitorObject) - Description of the visitor object.
```

--------------------------------

### Using the Concise Build API

Source: https://rolldown.rs/guide/getting-started

Employ the `build` API for a more streamlined approach, accepting the same options as the config file export and writing to disk by default.

```javascript
import { build } from 'rolldown';

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

--------------------------------

### TLA Desugaring Example (Spec)

Source: https://rolldown.rs/in-depth/tla-in-rolldown

This example shows the desugared mental model of Top Level Await from the TC39 proposal, where promises are collected and awaited.

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

console.log(a, b, c);

```

--------------------------------

### Create Source Files for Bundling

Source: https://rolldown.rs/guide/getting-started

Define two JavaScript files, `main.js` and `hello.js`, to be bundled by Rolldown.

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

hello();
```

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

--------------------------------

### build()

Source: https://rolldown.rs/apis/bundler-api

`build()` is the simplest option for most use cases, similar to esbuild's `build` function. It bundles and writes in a single call with automatic cleanup.

```APIDOC
## build()

### Description
`build()` is the simplest option for most use cases, similar to esbuild's `build` function. It bundles and writes in a single call with automatic cleanup.

::: warning Experimental

This API is experimental and may change in patch releases.

:::

### Usage
```js
import { build } from 'rolldown';

const result = await build({
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
  },
});
console.log(result);
```

### See Also
- [build reference](/reference/Function.build)
```

--------------------------------

### Run Rust Benchmarks

Source: https://rolldown.rs/development-guide/benchmarking

Execute this command in the project root to build and run the Rust benchmarks. The build process is handled automatically.

```shell
just bench-rust
```

--------------------------------

### ESM Importer and CJS Importee Example

Source: https://rolldown.rs/in-depth/bundling-cjs

Demonstrates a typical scenario where an ESM module imports from a CJS module. This example highlights the ambiguity in how default imports are resolved.

```js
import foo from './importee.cjs';
console.log(foo);
```

```js
Object.defineProperty(module.exports, '__esModule', {
  value: true,
});
module.exports.default = 'foo';
```

--------------------------------

### Consolidated Common Chunk Example

Source: https://rolldown.rs/in-depth/automatic-code-splitting

This example shows a consolidated common chunk that combines shared code from multiple entries. Executing each entry after this chunk results in a predictable output.

```javascript
globalThis.value = globalThis.value || [];
globalThis.value.push('ab');
globalThis.value = globalThis.value || [];
globalThis.value.push('bc');
globalThis.value = globalThis.value || [];
globalThis.value.push('abc');
```

--------------------------------

### Build Code with build()

Source: https://rolldown.rs/apis/bundler-api

Utilize the experimental `build()` function for a simplified bundling process, similar to esbuild's `build`. It bundles and writes in one step with automatic cleanup.

```javascript
import { build } from 'rolldown';

const result = await build({
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
  },
});
console.log(result);
```

--------------------------------

### Rolldown CLI Version

Source: https://rolldown.rs/apis/cli

Displaying the installed version number of Rolldown.

```shell
-v / --version
```

--------------------------------

### List Available `just` Commands

Source: https://rolldown.rs/development-guide/building-and-running

Run `just` without any arguments to see a list of all available commands for building, testing, and linting the project.

```bash
just
```

--------------------------------

### Instantiate and Use Visitor

Source: https://rolldown.rs/reference/Class.Visitor

Import the Visitor and parseSync utilities. Instantiate a Visitor with callbacks for specific AST node types and their exit events. Then, use the visitor to traverse the parsed program's AST.

```typescript
import { Visitor } from 'rolldown/utils';
import { parseSync } from 'rolldown/utils';

const result = parseSync(...);
const visitor = new Visitor({
  VariableDeclaration(path) {
    // Do something with the variable declaration
  },
  "VariableDeclaration:exit"(path) {
    // Do something after visiting the variable declaration
  }
});
visitor.visit(result.program);
```

--------------------------------

### Run Node.js Benchmarks

Source: https://rolldown.rs/development-guide/benchmarking

After building the Node.js bindings, use this command in the project root to execute the Node.js benchmarks.

```sh
just bench-node
```

--------------------------------

### Side Effect Preservation Example

Source: https://rolldown.rs/in-depth/dead-code-elimination

Illustrates how side effects are preserved when a module's exports are used, even if the module is marked as side-effect-free.

```javascript
// math.js
window.myGlobal = 'hello'; // side effect: modifies global

export function add(a, b) {
  return a + b;
}

// main.js
import './math.js';
console.log('main');
```

```javascript
// math.js (marked as side-effect-free)
window.myGlobal = 'hello'; // side effect: modifies global

export function add(a, b) {
  return a + b;
}

// main.js
import { add } from './math.js';
console.log('main', add(2, 3));
```

```javascript
// math.js (marked as side-effect-free)
window.myGlobal = 'hello'; // side effect: modifies global

export function add(a, b) {
  return a + b;
}

// main.js
import { add } from './math.js';
console.log('main', add(2, 3));
```

--------------------------------

### Data-driven Test Configuration

Source: https://rolldown.rs/development-guide/testing

Example of a `_config.json` file used for data-driven testing in Rust. This file configures the bundler for a specific test case.

```json
{
  "options": {
    "input": {
      "index": "./input.js"
    }
  },
  "files": {
    "./input.js": "export const message = \"Hello\";"
  },
  "expect": {
    "output": {
      "index": {
        "code": "var message = \"Hello\";\n"
      }
    }
  }
}
```

--------------------------------

### Execute Bundled JavaScript File

Source: https://rolldown.rs/guide/getting-started

Run the generated `bundle.js` file using Node.js to verify the output.

```sh
node bundle.js
```

--------------------------------

### Basic Plugin Hook Without Filter

Source: https://rolldown.rs/apis/plugin-api/hook-filters

This example shows a typical plugin hook where condition checks are performed within the JavaScript handler.

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

--------------------------------

### Configure Rolldown with a JS File

Source: https://rolldown.rs/guide/getting-started

Use a JavaScript configuration file for more complex build options. Recommended to use `defineConfig` for intellisense and auto-completion.

```javascript
import { defineConfig } from 'rolldown';

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

--------------------------------

### Using Rolldown Config File

Source: https://rolldown.rs/apis/cli

Commands to invoke Rolldown using a configuration file. It shows how to use a default config file or a custom one.

```shell
rolldown -c                 # use rolldown.config.{js,mjs,cjs,ts,mts,cts}
rolldown --config           # same as above
rolldown -c my.config.js    # use a custom config file
```

--------------------------------

### CJS On-demand Execution Example

Source: https://rolldown.rs/in-depth/bundling-cjs

Demonstrates how Rolldown preserves the on-demand execution semantics of CommonJS modules. The `foo.js` module is only executed when `getFooExports()` is called.

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

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

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

```javascript
// #region \0rolldown/runtime.js
// ...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
```

--------------------------------

### Identifying Side Effects in Imports

Source: https://rolldown.rs/in-depth/dead-code-elimination

Shows common examples of code that have side effects, such as importing CSS, modifying global variables, or extending built-in prototypes.

```javascript
// side effect: applies styles
import './styles.css';
// side effect: modifies global
window.API_URL = '/api';
// side effect: modifies prototype
Array.prototype.first = function () {
  return this[0];
};

```

--------------------------------

### Basic Dead Code Elimination Example

Source: https://rolldown.rs/in-depth/dead-code-elimination

Demonstrates how unused functions with no side effects are removed. The `multiply` function is eliminated because it's not imported or used in `main.js`.

```javascript
// math.js
export function add(a, b) {
  return a + b;
}

export function multiply(a, b) {
  return a * b;
}

// main.js
import { add } from './math.js';
console.log(add(2, 3));

```

--------------------------------

### Import and Use Bundle Analyzer Plugin

Source: https://rolldown.rs/builtin-plugins/bundle-analyzer

Import the plugin from `rolldown/experimental` and include it in your Rolldown configuration. The analysis file is emitted alongside your bundled output.

```javascript
import { defineConfig } from 'rolldown';
import { bundleAnalyzerPlugin } from 'rolldown/experimental';

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

--------------------------------

### Composable Filters with Pluginutils

Source: https://rolldown.rs/apis/plugin-api/hook-filters

This example utilizes `@rolldown/pluginutils` to create composable filter expressions using logical operators like `and`. This is useful for more complex filtering logic.

```javascript
import { and, id, include, moduleType } from '@rolldown/pluginutils';

export default function myPlugin() {
  return {
    name: 'my-plugin',
    transform: {
      filter: [include(and(id(/\.ts$/), moduleType('ts')))],
      handler(code, id) {
        // Only called for .ts files with moduleType 'ts'
        return transformedCode;
      },
    },
  };
}
```

--------------------------------

### Configure package.json Build Script

Source: https://rolldown.rs/guide/getting-started

Add a `build` script to your `package.json` to simplify running the Rolldown bundling command.

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

--------------------------------

### Run Rolldown CLI with Node

Source: https://rolldown.rs/development-guide/building-and-running

Execute the `rolldown` CLI using Node.js. Ensure the `rolldown` package is built first using `just build`.

```bash
just run
```

--------------------------------

### Importing from HTTP URL

Source: https://rolldown.rs/in-depth/external-modules

Specifiers starting with http://, https://, or // are always treated as external. These IDs are emitted as-is and are not affected by `makeAbsoluteExternalsRelative`.

```javascript
import lib from 'https://cdn.example.com/lib.js';
// Always external, emitted as-is
```

--------------------------------

### Import Rewriting with @rolldown/plugin-transform-imports

Source: https://rolldown.rs/in-depth/lazy-barrel-optimization

This example shows how `@rolldown/plugin-transform-imports` rewrites import statements to directly reference module exports, bypassing the need to resolve large barrel files.

```javascript
// Before
import { Home, Search } from '@mui/icons-material';

// After (rewritten by the plugin)
import Home from '@mui/icons-material/esm/Home';
import Search from '@mui/icons-material/esm/Search';
```

--------------------------------

### Rolldown CLI Help

Source: https://rolldown.rs/apis/cli

Displaying the help message for the Rolldown CLI. This shows all available commands and options.

```shell
{{ data.help }}
```

--------------------------------

### Unused Import Specifiers

Source: https://rolldown.rs/in-depth/lazy-barrel-optimization

By default, modules are loaded even if their imported specifiers are not used. This example demonstrates that './a.js' is loaded when './barrel/index.js' is imported with `{ a }`, even if `a` is never used.

```javascript
// barrel/index.js
export { a } from './a';
export { b } from './b';

// main.js
import { a } from './barrel'; // a.js is loaded even if `a` is never used
```

--------------------------------

### Run Rolldown Build Script with Package Managers

Source: https://rolldown.rs/guide/getting-started

Execute the configured `build` script using various package managers.

```sh
$ vp run build
```

```sh
$ npm run build
```

```sh
$ pnpm run build
```

```sh
$ yarn build
```

```sh
$ bun run build
```

--------------------------------

### HMR Edit File Example

Source: https://rolldown.rs/development-guide/testing

Illustrates an HMR edit file used in testing. The `hmr-1` suffix indicates this is the first step in a Hot Module Replacement sequence.

```javascript
main.hmr-1.js
```

--------------------------------

### visit()

Source: https://rolldown.rs/reference/Class.Visitor

Visits the AST program.

```APIDOC
## visit()

### Description
Visits the AST program.

### Parameters
#### program
- **program** (Program) - The AST program to visit.

### Returns
- `void`
```

--------------------------------

### Word Boundaries Example

Source: https://rolldown.rs/builtin-plugins/replace

By default, replacements occur only at word boundaries to avoid unintended substring replacements. This preserves words like 'environment' and property accesses like 'process.env'.

```js
// Input code:
const currentEnv = env;
const environment = getEnvironment();
const config = process.env.NODE_ENV;

replacePlugin({ env: '"production"' });

// Output:
// const currentEnv = "production";           ✅ 'env' as standalone word
// const environment = getEnvironment();      ✅ 'env' is part of 'environment'
// const config = process.env.NODE_ENV;       ✅ 'env' after '.' (property access)
```

--------------------------------

### Mark Barrel as Side-Effect-Free (Rolldown Treeshake Function)

Source: https://rolldown.rs/in-depth/lazy-barrel-optimization

For more complex logic in marking side-effect-free modules, use a function with the `treeshake.moduleSideEffects` option. This example marks all files ending with '/index.js' as side-effect-free.

```javascript
// rolldown.config.js
export default {
  treeshake: {
    moduleSideEffects: (id) => {
      // Mark all index.js files as side-effect-free
      if (id.endsWith('/index.js')) return false;
      return true;
    },
  },
};
```

--------------------------------

### ESM Importing from CJS Example

Source: https://rolldown.rs/in-depth/bundling-cjs

Illustrates seamless interoperability where an ES module imports values from a CommonJS module. The `__toESM` helper ensures proper conversion of CJS exports to ESM.

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

console.log(value);

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

```javascript
// #region \0rolldown/runtime.js
// ...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
```

--------------------------------

### Build Node.js Bindings for Release

Source: https://rolldown.rs/development-guide/benchmarking

Before running Node.js benchmarks, ensure the Node.js bindings are built in release mode using this command.

```shell
just build-rolldown-release
```

--------------------------------

### Apply Plugin Hook Filters with `withFilter`

Source: https://rolldown.rs/guide/troubleshooting

Use the `withFilter` utility to specify which modules a plugin hook should process, reducing overhead. This example applies a filter to the `@rollup/plugin-yaml` transform hook.

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

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

--------------------------------

### Bundle JavaScript Files with Rolldown CLI

Source: https://rolldown.rs/guide/getting-started

Use the Rolldown CLI to bundle `src/main.js` into `bundle.js`.

```sh
./node_modules/.bin/rolldown src/main.js --file bundle.js
```

--------------------------------

### Configure Bundle Analyzer Format

Source: https://rolldown.rs/builtin-plugins/bundle-analyzer

Select the output format for the analysis report using the `format` option. Choose 'json' for programmatic analysis or 'md' for LLM consumption.

```javascript
bundleAnalyzerPlugin({
  format: 'md',
});
```

--------------------------------

### Multiple Bundles from Different Inputs

Source: https://rolldown.rs/apis/cli

Configuring Rolldown to build multiple bundles from different input files by providing an array of configuration objects.

```javascript
import { defineConfig } from 'rolldown';

export default defineConfig([
  {
    input: 'src/main.js',
    output: { format: 'esm', entryFileNames: 'bundle.esm.js' },
  },
  {
    input: 'src/main.js',
    output: { format: 'cjs', entryFileNames: 'bundle.cjs.js' },
  },
]);
```