Interface: RolldownOptions

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2552

Extends

• InputOptions

Properties

checks?

optional checks: ChecksOptions;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2498

Controls which warnings are emitted during the build process. Each option can be set to true (emit warning) or false (suppress warning).

Inherited from

InputOptions.checks

---

context?

optional context: string;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2542

The value of this at the top level of each module. Normally, you don't need to set this option.

Default

undefined

Example

Set custom context

export default {
  context: 'globalThis',
  output: {
    format: 'iife',
  },
}

./docs/context.md

Inherited from

InputOptions.context

---

cwd?

optional cwd: string;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2198

The working directory to use when resolving relative paths in the configuration.

Default

process.cwd()

Inherited from

InputOptions.cwd

---

devtools?

optional devtools: object;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2511

Experimental

Devtools integration options.

sessionId?

optional sessionId: string;

Inherited from

InputOptions.devtools

---

experimental?

optional experimental: object;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2279

Experimental

Experimental features that may change in future releases and can introduce behavior change without a major version bump.

attachDebugInfo?

optional attachDebugInfo: "none" | "simple" | "full";

Attach debug information to the output bundle.

Available modes:

• none: No debug information is attached.
• simple: Attach comments indicating which files the bundled code comes from. These comments could be removed by the minifier.
• full: Attach detailed debug information to the output bundle. These comments are using legal comment syntax, so they won't be removed by the minifier.

Default

'simple'

chunkImportMap?

optional chunkImportMap:
  | boolean
  | {
  baseUrl?: string;
  fileName?: string;
};

Enables automatic generation of a chunk import map asset during build.

This map only includes chunks with hashed filenames, where keys are derived from the facade module name or primary chunk name. It produces stable and unique hash-based filenames, effectively preventing cascading cache invalidation caused by content hashes and maximizing browser cache reuse.

The output defaults to importmap.json unless overridden via fileName. A base URL prefix (default "/") can be applied to all paths. The resulting JSON is a valid import map and can be directly injected into HTML via <script type="importmap">.

Example

{
  experimental: {
    chunkImportMap: {
      baseUrl: '/',
      fileName: 'importmap.json'
    }
  },
  plugins: [
    {
      name: 'inject-import-map',
      generateBundle(_, bundle) {
        const chunkImportMap = bundle['importmap.json'];
        if (chunkImportMap?.type === 'asset') {
          const htmlPath = path.resolve('index.html');
          let html = fs.readFileSync(htmlPath, 'utf-8');

          html = html.replace(
            /<script\s+type="importmap"[^>]*>[\s\S]*?</script>/i,
            `<script type="importmap">${chunkImportMap.source}</script>`
          );

          fs.writeFileSync(htmlPath, html);
          delete bundle['importmap.json'];
        }
      }
    }
  ]
}

TIP

If you want to learn more, you can check out the example here: examples/chunk-import-map

Default

false

chunkModulesOrder?

optional chunkModulesOrder: "exec-order" | "module-id";

Control which order should be used when rendering modules in a chunk.

Available options:

• exec-order: Almost equivalent to the topological order of the module graph, but specially handling when module graph has cycle.
• module-id: This is more friendly for gzip compression, especially for some javascript static asset lib (e.g. icon library)

NOTE

Try to sort the modules by their module id if possible (Since rolldown scope hoist all modules in the chunk, we only try to sort those modules by module id if we could ensure runtime behavior is correct after sorting).

Default

'exec-order'

chunkOptimization?

optional chunkOptimization: boolean;

Control whether to optimize chunks by allowing entry chunks to have different exports than the underlying entry module. This optimization can reduce the number of generated chunks.

When enabled, rolldown will try to insert common modules directly into existing chunks rather than creating separate chunks for them, which can result in fewer output files and better performance.

This optimization is automatically disabled when any module uses top-level await (TLA) or contains TLA dependencies, as it could affect execution order guarantees.

Default

true

incrementalBuild?

optional incrementalBuild: boolean;

Enable incremental build support. Required to be used with watch mode.

Default

false

nativeMagicString?

optional nativeMagicString: boolean;

Use native Rust implementation of MagicString for source map generation.

MagicString is a JavaScript library commonly used by bundlers for string manipulation and source map generation. When enabled, rolldown will use a native Rust implementation of MagicString instead of the JavaScript version, providing significantly better performance during source map generation and code transformation.

Benefits

• Improved Performance: The native Rust implementation is typically faster than the JavaScript version, especially for large codebases with extensive source maps.
• Background Processing: Source map generation is performed asynchronously in a background thread, allowing the main bundling process to continue without blocking. This parallel processing can significantly reduce overall build times when working with JavaScript transform hooks.
• Better Integration: Seamless integration with rolldown's native Rust architecture.

Example

export default {
  experimental: {
    nativeMagicString: true,
  },
  output: {
    sourcemap: true,
  },
}

NOTE

This is an experimental feature. While it aims to provide identical behavior to the JavaScript implementation, there may be edge cases. Please report any discrepancies you encounter. For a complete working example, see examples/native-magic-string

Default

false

resolveNewUrlToAsset?

optional resolveNewUrlToAsset: boolean;

When enabled, new URL() calls will be transformed to a stable asset URL which includes the updated name and content hash. It is necessary to pass import.meta.url as the second argument to the new URL constructor, otherwise no transform will be applied.

WARNING

JavaScript and TypeScript files referenced via new URL('./file.js', import.meta.url) or new URL('./file.ts', import.meta.url) will not be transformed or bundled. The file will be copied as-is, meaning TypeScript files remain untransformed and dependencies are not resolved.

The expected behavior for JS/TS files is still being discussed and may change in future releases. See #7258 for more context.

Example

// main.js
const url = new URL('./styles.css', import.meta.url)
console.log(url)

// Example output after bundling WITHOUT the option (default)
const url = new URL('./styles.css', import.meta.url)
console.log(url)

// Example output after bundling WITH `experimental.resolveNewUrlToAsset` set to `true`
const url = new URL('assets/styles-CjdrdY7X.css', import.meta.url)
console.log(url)

Default

false

strictExecutionOrder?

optional strictExecutionOrder: boolean;

Lets modules be executed in the order they are declared.

This is done by injecting runtime helpers to ensure that modules are executed in the order they are imported. External modules won't be affected.

WARNING

Enabling this option may negatively increase bundle size. It is recommended to use this option only when absolutely necessary.

Default

false

transformHiresSourcemap?

optional transformHiresSourcemap: boolean | "boundary";

Enable high-resolution source maps for transform operations.

Default

false

Inherited from

InputOptions.experimental

---

external?

optional external:
  | string
  | RegExp
  | StringOrRegExp[]
  | ExternalOptionFunction;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2094

Specifies which modules should be treated as external and not bundled. External modules will be left as import statements in the output. ./docs/external.md

Inherited from

InputOptions.external

---

input?

optional input: string | string[] | Record<string, string>;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2083

Defines entries and location(s) of entry modules for the bundle. Relative paths are resolved based on the cwd option. ./docs/input.md

Inherited from

InputOptions.input

---

logLevel?

optional logLevel: "warn" | "info" | "silent" | "debug";

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2235

Controls the verbosity of console logging during the build.

./docs/log-level.md

Default

'info'

Inherited from

InputOptions.logLevel

---

makeAbsoluteExternalsRelative?

optional makeAbsoluteExternalsRelative: false | true | "ifRelativeSource";

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2506

Determines if absolute external paths should be converted to relative paths in the output.

This does not only apply to paths that are absolute in the source but also to paths that are resolved to an absolute path by either a plugin or Rolldown core.

./docs/make-absolute-externals-relative.md

Inherited from

InputOptions.makeAbsoluteExternalsRelative

---

moduleTypes?

optional moduleTypes: ModuleTypes;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2274

Maps file patterns to module types, controlling how files are processed.

This is conceptually similar to esbuild's loader option, allowing you to specify how different file extensions should be handled.

Inherited from

InputOptions.moduleTypes

---

onLog()?

optional onLog: (level, log, defaultHandler) => void;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2257

A function that intercepts log messages. If not supplied, logs are printed to the console.

./docs/on-log.md

Parameters

level

"warn" | "info" | "debug"

log

RollupLog

defaultHandler

LogOrStringHandler

Returns

void

Example

export default defineConfig({
  onLog(level, log, defaultHandler) {
    if (log.code === 'CIRCULAR_DEPENDENCY') {
      return // Ignore circular dependency warnings
    }
    if (level === 'warn') {
      defaultHandler('error', log) // turn other warnings into errors
    } else {
      defaultHandler(level, log) // otherwise, just print the log
    }
  },
})

Inherited from

InputOptions.onLog

---

onwarn()?

optional onwarn: (warning, defaultHandler) => void;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2268

A function that will intercept warning messages.

./docs/on-warn.md

Parameters

warning

RollupLog

defaultHandler

(warning) => void

Returns

void

Deprecated

This is a legacy API. Consider using onLog instead for better control over all log types.

./docs/on-warn-deprecation.md

Inherited from

InputOptions.onwarn

---

optimization?

optional optimization: OptimizationOptions;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2526

Configure optimization features for the bundler.

Inherited from

InputOptions.optimization

---

output?

optional output:
  | OutputOptions
  | OutputOptions[];

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2553

---

platform?

optional platform: "browser" | "node" | "neutral";

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2212

Expected platform where the code run.

When the platform is set to neutral:

• When bundling is enabled the default output format is set to esm, which uses the export syntax introduced with ECMAScript 2015 (i.e. ES6). You can change the output format if this default is not appropriate.
• The main fields setting is empty by default. If you want to use npm-style packages, you will likely have to configure this to be something else such as main for the standard main field used by node.
• The conditions setting does not automatically include any platform-specific values.

Default

• 'node' if the format is 'cjs'
• 'browser' for other formats ./docs/platform.md

Inherited from

InputOptions.platform

---

plugins?

optional plugins: RolldownPluginOption;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2089

The list of plugins to use.

Falsy plugins will be ignored, which can be used to easily activate or deactivate plugins. Nested plugins will be flattened. Async plugins will be awaited and resolved.

Inherited from

InputOptions.plugins

---

preserveEntrySignatures?

optional preserveEntrySignatures: false | "strict" | "allow-extension" | "exports-only";

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2522

Controls how entry chunk exports are preserved.

This determines whether Rolldown needs to create facade chunks (additional wrapper chunks) to maintain the exact export signatures of entry modules, or whether it can combine entry modules with other chunks for optimization.

Default

'exports-only' ./docs/preserve-entry-signatures.md

Inherited from

InputOptions.preserveEntrySignatures

---

resolve?

optional resolve: object;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2098

Options for built-in module resolution feature.

alias?

optional alias: Record<string, string | false | string[]>;

Substitute one package for another.

One use case for this feature is replacing a node-only package with a browser-friendly package in third-party code that you don't control.

Example

resolve: {
  alias: {
    '@': '/src',
    'utils': './src/utils',
  }
}

WARNING

resolve.alias will not call resolveId hooks of other plugin. If you want to call resolveId hooks of other plugin, use viteAliasPlugin from rolldown/experimental instead. You could find more discussion in this issue

aliasFields?

optional aliasFields: string[][];

Fields in package.json to check for aliased paths.

This option is expected to be used for browser field support.

Default

• [['browser']] for browser platform
• [] for other platforms

conditionNames?

optional conditionNames: string[];

Condition names to use when resolving exports in package.json.

Default

Defaults based on platform and import kind:

• browser platform
  • ["import", "browser", "default"] for import statements
  • ["require", "browser", "default"] for require() calls
• node platform
  • ["import", "node", "default"] for import statements
  • ["require", "node", "default"] for require() calls
• neutral platform
  • ["import", "default"] for import statements
  • ["require", "default"] for require() calls

exportsFields?

optional exportsFields: string[][];

Fields in package.json to check for exports.

Default

[['exports']]

extensionAlias?

optional extensionAlias: Record<string, string[]>;

Map of extensions to alternative extensions.

With writing import './foo.js' in a file, you want to resolve it to foo.ts instead of foo.js. You can achieve this by setting: extensionAlias: { '.js': ['.ts', '.js'] }.

extensions?

optional extensions: string[];

Extensions to try when resolving files. These are tried in order from first to last.

Default

['.tsx', '.ts', '.jsx', '.js', '.json']

mainFields?

optional mainFields: string[];

Fields in package.json to check for entry points.

Default

Defaults based on platform:

• node platform: ['main', 'module']
• browser platform: ['browser', 'module', 'main']
• neutral platform: []

mainFiles?

optional mainFiles: string[];

Filenames to try when resolving directories.

Default

;['index']

modules?

optional modules: string[];

Directories to search for modules.

Default

;['node_modules']

symlinks?

optional symlinks: boolean;

Whether to follow symlinks when resolving modules.

Default

true

tsconfigFilename?

optional tsconfigFilename: string;

Deprecated

Use the top-level tsconfig option instead.

Inherited from

InputOptions.resolve

---

shimMissingExports?

optional shimMissingExports: boolean;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2218

When true, creates shim variables for missing exports instead of throwing an error.

Default

false ./docs/shim-missing-exports.md

Inherited from

InputOptions.shimMissingExports

---

transform?

optional transform: TransformOptions;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2488

Configure how the code is transformed. This process happens after the transform hook.

Example

Enable legacy decorators

export default defineConfig({
  transform: {
    decorator: {
      legacy: true,
    },
  },
})

Note that if you have correct tsconfig.json file, Rolldown will automatically detect and enable legacy decorators support.

./docs/transform.md

Inherited from

InputOptions.transform

---

treeshake?

optional treeshake: boolean | TreeshakingOptions;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2227

Controls tree-shaking (dead code elimination).

When false, tree-shaking will be disabled. When true, it is equivalent to setting each options to the default value.

Default

true

Inherited from

InputOptions.treeshake

---

tsconfig?

optional tsconfig: string | boolean;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2548

Configures TypeScript configuration file resolution and usage. ./docs/tsconfig.md

Default

true

Inherited from

InputOptions.tsconfig

---

watch?

optional watch: false | WatcherOptions;

Defined in: node_modules/.pnpm/rolldown@1.0.0-beta.60/node_modules/rolldown/dist/shared/define-config-BgCyRzGF.d.mts:2494

Watch mode related options.

These options only take effect when running with the --watch flag, or using rolldown.watch() API.

Inherited from

InputOptions.watch