Command Line Interface

Rolldown can be used from the command line. You can provide an optional Rolldown configuration file to simplify command line usage and enable advanced Rolldown functionality.

Configuration Files

Rolldown configuration files are optional, but they are powerful and convenient and thus recommended. A config file is an ES module that exports a default object with the desired options. Typically, it is called rolldown.config.js and sits in the root directory of your project. You can also use CJS syntax in CJS files, which uses module.exports instead of export default. Rolldown also natively supports TypeScript configuration files.

Consult the reference for a comprehensive list of options you can include in your config file.

rolldown.config.js

export default {
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
    format: 'cjs',
  },
};

To use a config file with Rolldown, pass the -c (or --config) flag:

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

If you don't pass a file name, Rolldown will try to load rolldown.config.{js,mjs,cjs,ts,mts,cts} in the working directory. If no config file is found, Rolldown will show an error.

You can also export a function from your config file. The function will be called with command line arguments so you can dynamically adapt your configuration:

rolldown.config.js

import { defineConfig } from 'rolldown';

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

Config Intellisense

Since Rolldown ships with TypeScript typings, you can leverage your IDE's intellisense with JSDoc type hints:

rolldown.config.js

/** @type {import('rolldown').RolldownOptions} */
export default {
  // ...
};

Alternatively you can use the defineConfig helper, which provides intellisense without the need for JSDoc annotations:

rolldown.config.js

import { defineConfig } from 'rolldown';

export default defineConfig({
  // ...
});

Configuration Arrays

To build different bundles from different inputs, you can supply an array of configuration objects:

rolldown.config.js

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' },
  },
]);

Different outputs with same inputs

You can also supply an array for the output option to generate multiple outputs from the same input:

rolldown.config.js

import { defineConfig } from 'rolldown';

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

Command Line Flags

Flags can be passed as --foo, --foo <value>, or --foo=<value>. Boolean flags like --minify don't need a value, while key-value options like --define use comma-separated syntax: --define key=value,key2=value2. Many flags have short aliases (e.g., -m for --minify, -f for --format).

Integration into other tools

Note that your shell interprets arguments before Rolldown sees them—quotes and wildcards may behave unexpectedly. For advanced build processes or integration into other tools, consider using the JavaScript API instead. Key differences when switching from config files to the API:

• Configuration must be an object (not a Promise or function)
• Run rolldown.rolldown separately for each set of inputOptions (no config arrays)
• Use bundle.generate(outputOptions) or bundle.write(outputOptions) instead of the output option

Many options have command line flag equivalents. See the reference for details of those flags. In those cases, any arguments passed here will override the config file, if you're using one. This is a list of all supported flags:

Fast JavaScript/TypeScript bundler in Rust with Rollup-compatible API. (rolldown v1.0.0-rc.1)

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.cannot-call-namespace Whether to emit warnings when a namespace is called as a function.
  --checks.circular-dependency Whether to emit warnings when detecting circular dependency.
  --checks.common-js-variable-in-esm Whether to emit warnings when a CommonJS variable is used in an ES module.
  --checks.configuration-field-conflict Whether to emit warnings when a config value is overridden by another config value with a higher priority.
  --checks.could-not-clean-directory Whether to emit warnings when Rolldown could not clean the output directory.
  --checks.duplicate-shebang  Whether to emit warnings when both the code and postBanner contain shebang.
  --checks.empty-import-meta  Whether to emit warnings when `import.meta` is not supported with the output format and is replaced with an empty object (`{}`).
  --checks.eval               Whether to emit warnings when detecting uses of direct `eval`s.
  --checks.filename-conflict  Whether to emit warnings when files generated have the same name with different contents.
  --checks.import-is-undefined Whether to emit warnings when an imported variable is not exported.
  --checks.missing-global-name Whether to emit warnings when the `output.globals` option is missing when needed.
  --checks.missing-name-option-for-iife-export Whether to emit warnings when the `output.name` option is missing when needed.
  --checks.mixed-exports      Whether to emit warnings when the way to export values is ambiguous.
  --checks.plugin-timings     Whether to emit warnings when plugins take significant time during the build process.
  --checks.prefer-builtin-feature Whether to emit warnings when a plugin that is covered by a built-in feature is used.
  --checks.tolerated-transform Whether to emit warnings when detecting tolerated transform.
  --checks.unresolved-entry   Whether to emit warnings when an entrypoint cannot be resolved.
  --checks.unresolved-import  Whether to emit warnings when an import cannot be resolved.
  --chunk-file-names <name>   Name pattern for emitted secondary chunks.
  --clean-dir                 Clean output directory before emitting output.
  --code-splitting <code-splitting>Code splitting options (true, false, or object).
  --context <context>         The entity top-level `this` represents.
  --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.
  --devtools.session-id <devtools.session-id>Used to name the build.
  --dynamic-import-in-cjs     Dynamic import in CJS output.
  --entry-file-names <name>   Name pattern for emitted entry chunks.
  --environment <environment> Pass additional settings to the config file via process.ENV.
  --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).
  --generated-code.preset <generated-code.preset>.
  --generated-code.profiler-names Whether to add readable names to internal variables for profiling purposes.
  --generated-code.symbols    Whether to use Symbol.toStringTag for namespace objects.
  --hash-characters <hash-characters>Use the specified character set for file hashes.
  --inline-dynamic-imports    Inline dynamic imports.
  --input <input>             Entry file.
  --intro <intro>             Code to insert the top of the bundled file (inside the wrapper function).
  --keep-names                Keep function and class names after bundling.
  --legal-comments <legal-comments>Control comments in the output.
  --log-level <log-level>     Log level (silent, info, debug, warn).
  --make-absolute-externals-relative Prevent normalization of external imports.
  --minify-internal-exports   Minify internal exports.
  --module-types <types>      Module types for customized extensions.
  --no-external-live-bindings Disable external live bindings.
  --no-preserve-entry-signatures Avoid facade chunks for entry points.
  --no-treeshake              Disable treeshaking.
  --optimization.inline-const <optimization.inline-const>Enable crossmodule constant inlining.
  --optimization.pife-for-module-wrappers Use PIFE pattern for module wrappers.
  --outro <outro>             Code to insert the bottom of the bundled file (inside the wrapper function).
  --paths <paths>             Maps external module IDs to paths.
  --polyfill-require          Disable require polyfill injection.
  --post-banner <post-banner> A string to prepend to the top of each chunk. Applied after the `renderChunk` hook and minification.
  --post-footer <post-footer> A string to append to the bottom of each chunk. Applied after the `renderChunk` hook and minification.
  --preserve-modules          Preserve module structure.
  --preserve-modules-root <preserve-modules-root>Put preserved modules under this path at root level.
  --sanitize-file-name        Sanitize file name.
  --shim-missing-exports      Create shim variables for missing exports.
  --sourcemap-base-url <sourcemap-base-url>Base URL used to prefix sourcemap paths.
  --sourcemap-debug-ids       Inject sourcemap debug IDs.
  --strict-execution-order    Lets modules be executed in the order they are declared.
  --top-level-var             Rewrite top-level declarations to use `var`.
  --transform.assumptions.ignore-function-length .
  --transform.assumptions.no-document-all .
  --transform.assumptions.object-rest-no-symbols .
  --transform.assumptions.pure-getters .
  --transform.assumptions.set-public-class-fields .
  --transform.decorator.emit-decorator-metadata .
  --transform.decorator.legacy .
  --transform.define <transform.define>Define global variables (syntax: key=value,key2=value2).
  --transform.drop-labels <transform.drop-labels>Remove labeled statements with these label names.
  --transform.helpers.mode <transform.helpers.mode>.
  --transform.inject <transform.inject>Inject import statements on demand.
  --transform.jsx <transform.jsx>.
  --transform.plugins.styled-components <transform.plugins.styled-components>.
  --transform.plugins.tagged-template-escape .
  --transform.target <transform.target>The JavaScript target environment.
  --transform.typescript.allow-declare-fields .
  --transform.typescript.allow-namespaces .
  --transform.typescript.declaration.sourcemap .
  --transform.typescript.declaration.strip-internal .
  --transform.typescript.jsx-pragma <transform.typescript.jsx-pragma>.
  --transform.typescript.jsx-pragma-frag <transform.typescript.jsx-pragma-frag>.
  --transform.typescript.only-remove-type-imports .
  --transform.typescript.remove-class-fields-without-initializer .
  --transform.typescript.rewrite-import-extensions <transform.typescript.rewrite-import-extensions>.
  --tsconfig <tsconfig>       Path to the tsconfig.json file.
  --virtual-dirname <virtual-dirname>.

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/.

The flags listed below are only available via the command line interface.

-c, --config <filename>

Use the specified config file. If the argument is used but no filename is specified, Rolldown will look for a default config file. See Configuration Files for more details.

-h / --help

Show the help message.

-v / --version

Show the installed version number.

-w / --watch

Rebuild the bundle when source files change on disk.

ROLLDOWN_WATCH env

While in watch mode, the ROLLDOWN_WATCH and ROLLUP_WATCH environment variable will be set to true by Rolldown's command line interface and can be checked by other processes. Plugins should instead check this.meta.watchMode, which is independent of the command line interface.

--environment <values>

Pass additional settings to the config file via process.env. Values are comma-separated key-value pairs, where a value of true can be omitted.

For example:

rolldown -c --environment INCLUDE_DEPS,BUILD:production

This will set process.env.INCLUDE_DEPS = 'true' and process.env.BUILD = 'production'.

You can invoke this option multiple times. In that case, subsequently set variables will overwrite previous definitions.

Overwriting the values

If you have package.json scripts:

{
  "scripts": {
    "build": "rolldown -c --environment BUILD:production"
  }
}

you can call this script with npm run build -- --environment BUILD:development to set process.env.BUILD="development".