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 Loaders

By default Rolldown loads a config file by bundling it with Rolldown first (configLoader: 'bundle'). This works on any supported runtime, including for TypeScript configs.

If your runtime can import the config directly (Node.js 22.18+ (native TypeScript type stripping), Bun, Deno, or a loader registered via --import (e.g. tsx, jiti)), you can skip the bundling step with the native loader:

rolldown -c rolldown.config.ts --configLoader native

The native loader is more simple and is planned to be the default in the future.

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 --transform.define use comma-separated syntax: --transform.define key:value,key2:value2. Many flags have short aliases (e.g., -m for --minify, -f for --format).

Disabling boolean flags

To turn a boolean flag off, prefix it with --no-, e.g. --no-minify or --no-codeSplitting. Passing false as a value—--minify false or --codeSplitting=false—is not supported and will error, because the value is read as the string "false" rather than a boolean. This matches Rollup's CLI behavior (--no-treeshake, etc.).

Some flags accept either a boolean or an object (e.g. codeSplitting). For those you can:

• enable with defaults: --codeSplitting
• disable: --no-codeSplitting
• set nested fields with dot-notation: --codeSplitting.minSize 30000

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.1.4)

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 `-s` for `.map` file).
  --version -v,               Show version number.
  --watch -w,                 Watch files in bundle and rebuild on changes.
  --advancedChunks.minShareCount <advancedChunks.minShareCount>Minimum share count of the chunk.
  --advancedChunks.minSize <advancedChunks.minSize>Minimum size of the chunk.
  --assetFileNames <name>     Name pattern for asset files.
  --banner <banner>           Code to insert the top of the bundled file (outside the wrapper function).
  --checks.cannotCallNamespace Whether to emit warnings when a namespace is called as a function.
  --checks.circularDependency Whether to emit warnings when detecting circular dependency.
  --checks.commonJsVariableInEsm Whether to emit warnings when a CommonJS variable is used in an ES module.
  --checks.configurationFieldConflict Whether to emit warnings when a config value is overridden by another config value with a higher priority.
  --checks.couldNotCleanDirectory Whether to emit warnings when Rolldown could not clean the output directory.
  --checks.duplicateShebang   Whether to emit warnings when both the code and postBanner contain shebang.
  --checks.emptyImportMeta    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.filenameConflict   Whether to emit warnings when files generated have the same name with different contents.
  --checks.importIsUndefined  Whether to emit warnings when an imported variable is not exported.
  --checks.ineffectiveDynamicImport Whether to emit warnings when a module is dynamically imported but also statically imported, making the dynamic import ineffective for code splitting.
  --checks.invalidAnnotation  Whether to emit warnings when a `#__PURE__` / `@__PURE__` annotation has no effect due to its position.
  --checks.largeBarrelModules Whether to emit info logs when a barrel module has a very large number of re-exports (more than 5000).
  --checks.missingGlobalName  Whether to emit warnings when the `output.globals` option is missing when needed.
  --checks.missingNameOptionForIifeExport Whether to emit warnings when the `output.name` option is missing when needed.
  --checks.mixedExports       Whether to emit warnings when the way to export values is ambiguous.
  --checks.pluginTimings      Whether to emit warnings when plugins take significant time during the build process.
  --checks.preferBuiltinFeature Whether to emit warnings when a plugin that is covered by a built-in feature is used.
  --checks.sourcemapBroken    Whether to emit warnings when a plugin transforms code without generating a sourcemap.
  --checks.toleratedTransform Whether to emit warnings when detecting tolerated transform.
  --checks.unresolvedEntry    Whether to emit warnings when an entrypoint cannot be resolved.
  --checks.unresolvedImport   Whether to emit warnings when an import cannot be resolved.
  --checks.unsupportedTsconfigOption Whether to emit warnings when a tsconfig option or combination of options is not supported.
  --chunkFileNames <name>     Name pattern for emitted secondary chunks.
  --cleanDir                  Clean output directory before emitting output.
  --codeSplitting <codeSplitting>Code splitting options. Enabled by default; use `--no-codeSplitting` to disable, or `--codeSplitting.minSize` / `--codeSplitting.minShareCount` to configure.
  --comments <comments>       Control comments in the output.
  --configLoader <loader>     How to load the config file (bundle, native).
  --context <context>         The entity top-level `this` represents.
  --cwd <cwd>                 Current working directory.
  --devtools.sessionId <devtools.sessionId>Used to name the build.
  --dynamicImportInCjs        Dynamic import in CJS output.
  --entryFileNames <name>     Name pattern for emitted entry chunks.
  --environment <environment> Pass additional settings to the config file via process.ENV.
  --esModule                  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).
  --generatedCode.preset <generatedCode.preset>.
  --generatedCode.profilerNames Whether to add readable names to internal variables for profiling purposes.
  --generatedCode.symbols     Whether to use Symbol.toStringTag for namespace objects.
  --hashCharacters <hashCharacters>Use the specified character set for file hashes.
  --inlineDynamicImports      Inline dynamic imports.
  --input <input>             Entry file.
  --intro <intro>             Code to insert the top of the bundled file (inside the wrapper function).
  --keepNames                 Keep function and class names after bundling.
  --legalComments <legalComments>Control legal comments in the output.
  --logLevel <logLevel>       Log level (silent, info, debug, warn).
  --makeAbsoluteExternalsRelative Prevent normalization of external imports.
  --minifyInternalExports     Minify internal exports.
  --moduleTypes <types>       Module types for customized extensions.
  --no-externalLiveBindings   Disable external live bindings.
  --no-preserveEntrySignatures Avoid facade chunks for entry points.
  --no-treeshake              Disable treeshaking.
  --optimization.inlineConst <optimization.inlineConst>Enable crossmodule constant inlining.
  --optimization.pifeForModuleWrappers 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.
  --polyfillRequire           Disable require polyfill injection.
  --postBanner <postBanner>   A string to prepend to the top of each chunk. Applied after the `renderChunk` hook and minification.
  --postFooter <postFooter>   A string to append to the bottom of each chunk. Applied after the `renderChunk` hook and minification.
  --preserveModules           Preserve module structure.
  --preserveModulesRoot <preserveModulesRoot>Put preserved modules under this path at root level.
  --sanitizeFileName          Sanitize file name.
  --shimMissingExports        Create shim variables for missing exports.
  --sourcemapBaseUrl <sourcemapBaseUrl>Base URL used to prefix sourcemap paths.
  --sourcemapDebugIds         Inject sourcemap debug IDs.
  --sourcemapExcludeSources   Exclude source content from sourcemaps.
  --sourcemapFileNames <sourcemapFileNames>Name pattern for emitted sourcemaps.
  --strict <strict>           Whether to always output `"use strict"` directive in non-ES module outputs.
  --strictExecutionOrder      Lets modules be executed in the order they are declared.
  --topLevelVar               Rewrite top-level declarations to use `var`.
  --transform.assumptions.ignoreFunctionLength .
  --transform.assumptions.noDocumentAll .
  --transform.assumptions.objectRestNoSymbols .
  --transform.assumptions.pureGetters .
  --transform.assumptions.setPublicClassFields .
  --transform.decorator.emitDecoratorMetadata .
  --transform.decorator.legacy .
  --transform.decorator.strictNullChecks .
  --transform.define <transform.define>Define global variables (syntax: key:value,key2:value2).
  --transform.dropLabels <transform.dropLabels>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.styledComponents <transform.plugins.styledComponents>.
  --transform.plugins.taggedTemplateEscape .
  --transform.target <transform.target>The JavaScript target environment.
  --transform.typescript.allowDeclareFields .
  --transform.typescript.allowNamespaces .
  --transform.typescript.declaration.sourcemap .
  --transform.typescript.declaration.stripInternal .
  --transform.typescript.jsxPragma <transform.typescript.jsxPragma>.
  --transform.typescript.jsxPragmaFrag <transform.typescript.jsxPragmaFrag>.
  --transform.typescript.onlyRemoveTypeImports .
  --transform.typescript.optimizeConstEnums .
  --transform.typescript.optimizeEnums .
  --transform.typescript.removeClassFieldsWithoutInitializer .
  --transform.typescript.rewriteImportExtensions <transform.typescript.rewriteImportExtensions>.
  --tsconfig <tsconfig>       Path to the tsconfig.json file.
  --virtualDirname <virtualDirname>.

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

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

--configLoader <loader>

How to load the config file. One of:

• bundle (default): bundle the config with Rolldown before importing it.
• native: import the config directly, relying on the runtime for TypeScript and loader support. See Config Loaders.

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