Interface RolldownOptions

interface RolldownOptions {
    checks?: ChecksOptions;
    context?: string;
    cwd?: string;
    devtools?: { sessionId?: string };
    experimental?: {
        attachDebugInfo?: "none" | "simple" | "full";
        chunkImportMap?: boolean | { baseUrl?: string; fileName?: string };
        chunkModulesOrder?: "exec-order" | "module-id";
        chunkOptimization?: boolean;
        incrementalBuild?: boolean;
        lazyBarrel?: boolean;
        nativeMagicString?: boolean;
        resolveNewUrlToAsset?: boolean;
    };
    external?: string
    | RegExp
    | (string | RegExp)[]
    | ExternalOptionFunction;
    input?: string | Record<string, string> | string[];
    logLevel?: "silent" | "warn" | "info" | "debug";
    makeAbsoluteExternalsRelative?: false | true | "ifRelativeSource";
    moduleTypes?: ModuleTypes;
    onLog?: (
        level: "warn" | "info" | "debug",
        log: RolldownLog,
        defaultHandler: LogOrStringHandler,
    ) => void;
    onwarn?: (
        warning: RolldownLog,
        defaultHandler: (
            warning: string | RolldownLog | (() => string | RolldownLog),
        ) => void,
    ) => void;
    optimization?: OptimizationOptions;
    output?: OutputOptions | OutputOptions[];
    platform?: "node" | "browser" | "neutral";
    plugins?: RolldownPluginOption;
    preserveEntrySignatures?:
        | false
        | "strict"
        | "allow-extension"
        | "exports-only";
    resolve?: {
        alias?: Record<string, string | false | string[]>;
        aliasFields?: string[][];
        conditionNames?: string[];
        exportsFields?: string[][];
        extensionAlias?: Record<string, string[]>;
        extensions?: string[];
        mainFields?: string[];
        mainFiles?: string[];
        modules?: string[];
        symlinks?: boolean;
        tsconfigFilename?: string;
    };
    shimMissingExports?: boolean;
    transform?: TransformOptions;
    treeshake?: boolean
    | TreeshakingOptions;
    tsconfig?: string | boolean;
    watch?: false | WatcherOptions;
}

Hierarchy (View Summary)

InputOptions
- RolldownOptions

Properties

`Optional`checks

checks?: ChecksOptions

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

`Optional`context

context?: string

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

`Optional`cwd

cwd?: string

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

Default

process.cwd()

`Optional` `Experimental`devtools

devtools?: { sessionId?: string }

Devtools integration options.

`Optional` `Experimental`experimental

experimental?: {
    attachDebugInfo?: "none" | "simple" | "full";
    chunkImportMap?: boolean | { baseUrl?: string; fileName?: string };
    chunkModulesOrder?: "exec-order" | "module-id";
    chunkOptimization?: boolean;
    incrementalBuild?: boolean;
    lazyBarrel?: boolean;
    nativeMagicString?: boolean;
    resolveNewUrlToAsset?: boolean;
}

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

Type Declaration

OptionalattachDebugInfo?: "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'
```

`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

OptionalchunkModulesOrder?: "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'
```
OptionalchunkOptimization?: 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
```
OptionalincrementalBuild?: boolean
Enable incremental build support. Required to be used with watch mode.
Default
```
false
```
OptionallazyBarrel?: boolean
Control whether to enable lazy barrel optimization.

Lazy barrel optimization avoids compiling unused re-export modules in side-effect-free barrel modules, significantly improving build performance for large codebases with many barrel modules.
See
Lazy Barrel Documentation
Default
```
false
```
OptionalnativeMagicString?: 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
```
OptionalresolveNewUrlToAsset?: 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
```

`Optional`external

external?: string | RegExp | (string | RegExp)[] | ExternalOptionFunction

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

`Optional`input

input?: string | Record<string, string> | string[]

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

`Optional`logLevel

logLevel?: "silent" | "warn" | "info" | "debug"

Controls the verbosity of console logging during the build.

Default

'info'

`Optional`makeAbsoluteExternalsRelative

makeAbsoluteExternalsRelative?: false | true | "ifRelativeSource"

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.

`Optional`moduleTypes

moduleTypes?: ModuleTypes

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 each file extensions should be handled.

See the In-Depth Guide for more details.

Example

import { defineConfig } from 'rolldown'

export default defineConfig({
  moduleTypes: {
    '.frag': 'text',
  }
})

`Optional`onLog

onLog?: (
    level: "warn" | "info" | "debug",
    log: RolldownLog,
    defaultHandler: LogOrStringHandler,
) => void

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

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

`Optional`onwarn

onwarn?: (
    warning: RolldownLog,
    defaultHandler: (
        warning: string | RolldownLog | (() => string | RolldownLog),
    ) => void,
) => void

A function that will intercept warning messages.

Deprecated

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

`Optional`optimization

optimization?: OptimizationOptions

Configure optimization features for the bundler.

`Optional`output

output?: OutputOptions | OutputOptions[]

`Optional`platform

platform?: "node" | "browser" | "neutral"

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

`Optional`plugins

plugins?: RolldownPluginOption

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.

See Plugin API document for more details about creating plugins.

Example

import { defineConfig } from 'rolldown'

export default defineConfig({
  plugins: [
    examplePlugin1(),
    // Conditional plugins
    process.env.ENV1 && examplePlugin2(),
    // Nested plugins arrays are flattened
    [examplePlugin3(), examplePlugin4()],
  ]
})

`Optional`preserveEntrySignatures

preserveEntrySignatures?: false | "strict" | "allow-extension" | "exports-only"

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'

`Optional`resolve

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

Options for built-in module resolution feature.

Type Declaration

Optionalalias?: 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
OptionalaliasFields?: 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
OptionalconditionNames?: 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
OptionalexportsFields?: string[][]
Fields in package.json to check for exports.

Default
[['exports']]
OptionalextensionAlias?: 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'] }.
Optionalextensions?: string[]
Extensions to try when resolving files. These are tried in order from first to last.

Default
['.tsx', '.ts', '.jsx', '.js', '.json']
OptionalmainFields?: 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: []
OptionalmainFiles?: string[]
Filenames to try when resolving directories.
Default
```
['index']
```
Optionalmodules?: string[]
Directories to search for modules.
Default
```
['node_modules']
```
Optionalsymlinks?: boolean
Whether to follow symlinks when resolving modules.
Default
```
true
```
OptionaltsconfigFilename?: string
Deprecated
Use the top-level tsconfig option instead.

`Optional`shimMissingExports

shimMissingExports?: boolean

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

Default

false

`Optional`transform

transform?: TransformOptions

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.

`Optional`treeshake

treeshake?: boolean | TreeshakingOptions

Controls tree-shaking (dead code elimination).

See the In-depth Dead Code Elimination Guide for more details.

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

Default

true

`Optional`tsconfig

tsconfig?: string | boolean

Configures TypeScript configuration file resolution and usage.

Default

true

`Optional` `Experimental`watch

watch?: false | WatcherOptions

Watch mode related options.

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

Interface RolldownOptions

Hierarchy (View Summary)

Index

Properties

Properties

Optionalchecks

Optionalcontext

Default

Example

Optionalcwd

Default

Optional Experimentaldevtools

Optional Experimentalexperimental

Type Declaration

OptionalattachDebugInfo?: "none" | "simple" | "full"

Default

OptionalchunkImportMap?: boolean | { baseUrl?: string; fileName?: string }

Example

Default

OptionalchunkModulesOrder?: "exec-order" | "module-id"

Default

OptionalchunkOptimization?: boolean

Default

OptionalincrementalBuild?: boolean

Default

OptionallazyBarrel?: boolean

See

Default

OptionalnativeMagicString?: boolean

Example

Default

OptionalresolveNewUrlToAsset?: boolean

Example

Default

Optionalexternal

Optionalinput

OptionallogLevel

Default

OptionalmakeAbsoluteExternalsRelative

OptionalmoduleTypes

Example

OptionalonLog

Example

Optionalonwarn

Deprecated

Optionaloptimization

Optionaloutput

Optionalplatform

Default

Optionalplugins

Example

OptionalpreserveEntrySignatures

Default

Optionalresolve

Type Declaration

Optionalalias?: Record<string, string | false | string[]>

Example

OptionalaliasFields?: string[][]

Default

OptionalconditionNames?: string[]

Default

OptionalexportsFields?: string[][]

Default

OptionalextensionAlias?: Record<string, string[]>

Optionalextensions?: string[]

Default

OptionalmainFields?: string[]

Default

OptionalmainFiles?: string[]

Default

Optionalmodules?: string[]

Default

Optionalsymlinks?: boolean

Default

OptionaltsconfigFilename?: string

Deprecated

OptionalshimMissingExports

Default

Optionaltransform

Example

`Optional`checks

`Optional`context

`Optional`cwd

`Optional` `Experimental`devtools

`Optional` `Experimental`experimental

`Optional`attachDebugInfo?: "none" | "simple" | "full"

`Optional`chunkImportMap?: boolean | { baseUrl?: string; fileName?: string }

`Optional`chunkModulesOrder?: "exec-order" | "module-id"

`Optional`chunkOptimization?: boolean

`Optional`incrementalBuild?: boolean

`Optional`lazyBarrel?: boolean

`Optional`nativeMagicString?: boolean

`Optional`resolveNewUrlToAsset?: boolean

`Optional`external

`Optional`input

`Optional`logLevel

`Optional`makeAbsoluteExternalsRelative

`Optional`moduleTypes

`Optional`onLog

`Optional`onwarn

`Optional`optimization

`Optional`output

`Optional`platform

`Optional`plugins

`Optional`preserveEntrySignatures

`Optional`resolve

`Optional`alias?: Record<string, string | false | string[]>

`Optional`aliasFields?: string[][]

`Optional`conditionNames?: string[]

`Optional`exportsFields?: string[][]

`Optional`extensionAlias?: Record<string, string[]>

`Optional`extensions?: string[]

`Optional`mainFields?: string[]

`Optional`mainFiles?: string[]

`Optional`modules?: string[]

`Optional`symlinks?: boolean

`Optional`tsconfigFilename?: string

`Optional`shimMissingExports

`Optional`transform

`Optional`treeshake

`Optional`tsconfig

`Optional` `Experimental`watch