Interface BuildOptions

Attach debug information to the output bundle.

• Type: 'none' | 'simple' | 'full'

• Default: 'simple'

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

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 configuration snippet:

{
  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'];
        }
      }
    }
  ]
}
Copy

Control which order should use when rendering modules in chunk

• Type: `'exec-order' | 'module-id'

• Default: 'exec-order'

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

Required to be used with watch mode.

Use native Rust implementation of MagicString for source map generation.

• Type: boolean
• Default: false

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

Lets modules be executed in the order they are declared.

• Type: boolean
• Default: false

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.

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'] }.