Interface OutputOptions

interface OutputOptions {
    advancedChunks?: {
        groups?: CodeSplittingGroup[];
        includeDependenciesRecursively?: boolean;
        maxModuleSize?: number;
        maxSize?: number;
        minModuleSize?: number;
        minShareCount?: number;
        minSize?: number;
    };
    assetFileNames?: string
    | ((chunkInfo: PreRenderedAsset) => string);
    banner?: string | ((chunk: RenderedChunk) => string | Promise<string>);
    chunkFileNames?: string | ((chunkInfo: PreRenderedChunk) => string);
    cleanDir?: boolean;
    codeSplitting?: boolean | CodeSplittingOptions;
    dir?: string;
    dynamicImportInCjs?: boolean;
    entryFileNames?: string | ((chunkInfo: PreRenderedChunk) => string);
    esModule?: boolean | "if-default-prop";
    exports?: "auto" | "named" | "default" | "none";
    extend?: boolean;
    externalLiveBindings?: boolean;
    file?: string;
    footer?: string | ((chunk: RenderedChunk) => string | Promise<string>);
    format?: "es" | "cjs" | "esm" | "module" | "commonjs" | "iife" | "umd";
    generatedCode?: Partial<GeneratedCodeOptions>;
    globals?: Record<string, string> | ((name: string) => string);
    hashCharacters?: "base64" | "base36" | "hex";
    inlineDynamicImports?: boolean;
    intro?: string | ((chunk: RenderedChunk) => string | Promise<string>);
    keepNames?: boolean;
    legalComments?: "inline" | "none";
    manualChunks?: (
        moduleId: string,
        meta: { getModuleInfo: (moduleId: string) => ModuleInfo | null },
    ) => string | undefined | null | void;
    minify?: boolean | "dce-only" | MinifyOptions;
    minifyInternalExports?: boolean;
    name?: string;
    outro?: string | ((chunk: RenderedChunk) => string | Promise<string>);
    paths?: Record<string, string> | ((id: string) => string);
    plugins?: RolldownOutputPluginOption;
    polyfillRequire?: boolean;
    postBanner?: string | ((chunk: RenderedChunk) => string | Promise<string>);
    postFooter?: string | ((chunk: RenderedChunk) => string | Promise<string>);
    preserveModules?: boolean;
    preserveModulesRoot?: string;
    sanitizeFileName?: boolean | ((name: string) => string);
    sourcemap?: boolean | "inline" | "hidden";
    sourcemapBaseUrl?: string;
    sourcemapDebugIds?: boolean;
    sourcemapIgnoreList?:
        | boolean
        | ((relativeSourcePath: string, sourcemapPath: string) => boolean)
        | string | RegExp;
    sourcemapPathTransform?: (
        relativeSourcePath: string,
        sourcemapPath: string,
    ) => string;
    strictExecutionOrder?: boolean;
    topLevelVar?: boolean;
    virtualDirname?: string;
}

Properties

`Optional`advancedChunks

advancedChunks?: {
    groups?: CodeSplittingGroup[];
    includeDependenciesRecursively?: boolean;
    maxModuleSize?: number;
    maxSize?: number;
    minModuleSize?: number;
    minShareCount?: number;
    minSize?: number;
}

Deprecated

Please use output.codeSplitting instead.

Allows you to do manual chunking.

:::warning If advancedChunks and codeSplitting are both specified, advancedChunks option will be ignored. :::

`Optional`assetFileNames

assetFileNames?: string | ((chunkInfo: PreRenderedAsset) => string)

The pattern to use for naming custom emitted assets to include in the build output, or a function that is called per asset with PreRenderedAsset to return such a pattern.

Patterns support the following placeholders:

[extname]: The file extension of the asset including a leading dot, e.g. .css.
[ext]: The file extension without a leading dot, e.g. css.
[hash]: A hash based on the content of the asset. You can also set a specific hash length via e.g. [hash:10]. By default, it will create a base-64 hash. If you need a reduced character set, see output.hashCharacters.
[name]: The file name of the asset excluding any extension.

Forward slashes (/) can be used to place files in sub-directories.

Default

'assets/[name]-[hash][extname]'

`Optional`banner

banner?: string | ((chunk: RenderedChunk) => string | Promise<string>)

A string to prepend to the bundle before renderChunk hook.

See output.intro, output.postBanner as well.

`Optional`chunkFileNames

chunkFileNames?: string | ((chunkInfo: PreRenderedChunk) => string)

The pattern to use for naming shared chunks created when code-splitting, or a function that is called per chunk with PreRenderedChunk to return such a pattern.

Patterns support the following placeholders:

[format]: The rendering format defined in the output options. The value is any of InternalModuleFormat.
[hash]: A hash based only on the content of the final generated chunk, including transformations in renderChunk and any referenced file hashes. You can also set a specific hash length via e.g. [hash:10]. By default, it will create a base-64 hash. If you need a reduced character set, see output.hashCharacters.
[name]: The name of the chunk. This can be explicitly set via the output.codeSplitting option or when the chunk is created by a plugin via this.emitFile. Otherwise, it will be derived from the chunk contents.

Forward slashes (/) can be used to place files in sub-directories.

Default

'[name]-[hash].js'

`Optional`cleanDir

cleanDir?: boolean

Clean output directory (output.dir) before emitting output.

Default

false

`Optional`codeSplitting

codeSplitting?: boolean | CodeSplittingOptions

Controls how code splitting is performed.

true: Default behavior, automatic code splitting. (default)
false: Inline all dynamic imports into a single bundle (equivalent to deprecated inlineDynamicImports: true).
object: Advanced manual code splitting configuration.

For deeper understanding, please refer to the in-depth documentation.

Example

Basic vendor chunk

export default defineConfig({
  output: {
    codeSplitting: {
      minSize: 20000,
      groups: [
        {
          name: 'vendor',
          test: /node_modules/,
        },
      ],
    },
  },
});

Default

true

`Optional`dir

dir?: string

The directory in which all generated chunks are placed.

The output.file option can be used instead if only a single chunk is generated.

Default

'dist'

`Optional`dynamicImportInCjs

dynamicImportInCjs?: boolean

Whether to keep external dynamic imports as import(...) expressions in CommonJS output.

If set to false, external dynamic imports will be rewritten to use require(...) calls. This may be necessary to support environments that do not support dynamic import() in CommonJS modules like old Node.js versions.

Default

true

`Optional`entryFileNames

entryFileNames?: string | ((chunkInfo: PreRenderedChunk) => string)

The pattern to use for chunks created from entry points, or a function that is called per entry chunk with PreRenderedChunk to return such a pattern.

Patterns support the following placeholders:

[format]: The rendering format defined in the output options. The value is any of InternalModuleFormat.
[hash]: A hash based only on the content of the final generated chunk, including transformations in renderChunk and any referenced file hashes. You can also set a specific hash length via e.g. [hash:10]. By default, it will create a base-64 hash. If you need a reduced character set, see output.hashCharacters.
[name]: The file name (without extension) of the entry point, unless the object form of input was used to define a different name.

Forward slashes (/) can be used to place files in sub-directories. This pattern will also be used for every file when setting the output.preserveModules option.

Default

'[name].js'

`Optional`esModule

esModule?: boolean | "if-default-prop"

Whether to add a __esModule: true property when generating exports for non-ES formats.

This property signifies that the exported value is the namespace of an ES module and that the default export of this module corresponds to the .default property of the exported object.

true: Always add the property when using named exports mode, which is similar to what other tools do.
"if-default-prop": Only add the property when using named exports mode and there also is a default export. The subtle difference is that if there is no default export, consumers of the CommonJS version of your library will get all named exports as default export instead of an error or undefined.
false: Never add the property even if the default export would become a property .default.

Default

'if-default-prop'

`Optional`exports

exports?: "auto" | "named" | "default" | "none"

Which exports mode to use.

Default

'auto'

`Optional`extend

extend?: boolean

Whether to extend the global variable defined by the name option in umd or iife formats.

When true, the global variable will be defined as global.name = global.name || {}. When false, the global defined by name will be overwritten like global.name = {}.

Default

false

`Optional`externalLiveBindings

externalLiveBindings?: boolean

Whether to generate code to support live bindings for external imports.

With the default value of true, Rolldown will generate code to support live bindings for external imports.

When set to false, Rolldown will assume that exports from external modules do not change. This will allow Rolldown to generate smaller code. Note that this can cause issues when there are circular dependencies involving an external dependency.

Default

true

`Optional`file

file?: string

The file path for the single generated chunk.

The output.dir option should be used instead if multiple chunks are generated.

`Optional`footer

footer?: string | ((chunk: RenderedChunk) => string | Promise<string>)

A string to append to the bundle before renderChunk hook.

See output.outro, output.postFooter as well.

`Optional`format

format?: "es" | "cjs" | "esm" | "module" | "commonjs" | "iife" | "umd"

Expected format of generated code.

'es', 'esm' and 'module' are the same format, all stand for ES module.
'cjs' and 'commonjs' are the same format, all stand for CommonJS module.
'iife' stands for Immediately Invoked Function Expression.
'umd' stands for Universal Module Definition.

Default

'esm'

`Optional`generatedCode

generatedCode?: Partial<GeneratedCodeOptions>

Which language features Rolldown can safely use in generated code.

This will not transpile any user code but only change the code Rolldown uses in wrappers and helpers.

`Optional`globals

globals?: Record<string, string> | ((name: string) => string)

Specifies id: variableName pairs necessary for external imports in umd / iife formats.

Example

export default defineConfig({
  external: ['jquery'],
  output: {
    format: 'iife',
    name: 'MyBundle',
    globals: {
      jquery: '$',
    }
  }
});

// input
import $ from 'jquery';

// output
var MyBundle = (function ($) {
  // ...
})($);

`Optional`hashCharacters

hashCharacters?: "base64" | "base36" | "hex"

Specify the character set that Rolldown is allowed to use in file hashes.

'base64': Uses url-safe base64 characters (0-9, a-z, A-Z, -, _). This will produce the shortest hashes.
'base36': Uses alphanumeric characters (0-9, a-z)
'hex': Uses hexadecimal characters (0-9, a-f)

Default

'base64'

`Optional`inlineDynamicImports

inlineDynamicImports?: boolean

Deprecated

Please use codeSplitting: false instead.

Whether to inline dynamic imports instead of creating new chunks to create a single bundle.

This option can be used only when a single input is provided.

Default

false

`Optional`intro

intro?: string | ((chunk: RenderedChunk) => string | Promise<string>)

A string to prepend inside any format-specific wrapper.

See output.banner, output.postBanner as well.

`Optional`keepNames

keepNames?: boolean

Keep name property of functions and classes after bundling.

When enabled, the bundler will preserve the original name property value of functions and classes in the output. This is useful for debugging and some frameworks that rely on it for registration and binding purposes.

Default

false

`Optional`legalComments

legalComments?: "inline" | "none"

Control comments in the output.

none: no comments
inline: preserve comments that contain @license, @preserve or starts with //! /*!

`Optional`manualChunks

manualChunks?: (
moduleId: string,
meta: { getModuleInfo: (moduleId: string) => ModuleInfo | null },
) => string | undefined | null | void

Allows you to do manual chunking. Provided for Rollup compatibility.

You could use this option for migration purpose. Under the hood,

{
  manualChunks: (moduleId, meta) => {
    if (moduleId.includes('node_modules')) {
      return 'vendor';
    }
    return null;
  }
}

will be transformed to

{
  codeSplitting: {
    groups: [
      {
        name(moduleId) {
          if (moduleId.includes('node_modules')) {
            return 'vendor';
          }
          return null;
        },
      },
    ],
  }
}

Note that unlike Rollup, object form is not supported.

Deprecated

Please use output.codeSplitting instead.

:::warning If manualChunks and codeSplitting are both specified, manualChunks option will be ignored. :::

`Optional`minify

minify?: boolean | "dce-only" | MinifyOptions

Control code minification

Rolldown uses Oxc Minifier under the hood. See Oxc's minification documentation for more details.

true: Enable full minification including code compression and dead code elimination
false: Disable minification (default)
'dce-only': Only perform dead code elimination without code compression
MinifyOptions: Fine-grained control over minification settings

Default

false

`Optional`minifyInternalExports

minifyInternalExports?: boolean

Whether to minify internal exports as single letter variables to allow for better minification.

Default

true for format es or if output.minify is true or object, false otherwise

`Optional`name

name?: string

Specifies the global variable name that contains the exports of umd / iife formats.

Example

export default defineConfig({
  output: {
    format: 'iife',
    name: 'MyBundle',
  }
});

// output
var MyBundle = (function () {
  // ...
})();

`Optional`outro

outro?: string | ((chunk: RenderedChunk) => string | Promise<string>)

A string to append inside any format-specific wrapper.

See output.footer, output.postFooter as well.

`Optional`paths

paths?: Record<string, string> | ((id: string) => string)

Maps external module IDs to paths.

Allows customizing the path used when importing external dependencies. This is particularly useful for loading dependencies from CDNs or custom locations.

Object form: Maps module IDs to their replacement paths
Function form: Takes a module ID and returns its replacement path

Example

{
  paths: {
    'd3': 'https://cdn.jsdelivr.net/npm/d3@7'
  }
}

Example

{
  paths: (id) => {
    if (id.startsWith('lodash')) {
      return `https://cdn.jsdelivr.net/npm/${id}`
    }
    return id
  }
}

`Optional`plugins

plugins?: RolldownOutputPluginOption

The list of plugins to use only for this output.

See

plugins

`Optional`polyfillRequire

polyfillRequire?: boolean

Whether to add a polyfill for require() function in non-CommonJS formats.

This option is useful when you want to inject your own require implementation.

Default

true

`Optional`postBanner

postBanner?: string | ((chunk: RenderedChunk) => string | Promise<string>)

A string to prepend to the bundle after renderChunk hook and minification.

See output.banner, output.intro as well.

`Optional`postFooter

postFooter?: string | ((chunk: RenderedChunk) => string | Promise<string>)

A string to append to the bundle after renderChunk hook and minification.

See output.footer, output.outro as well.

`Optional`preserveModules

preserveModules?: boolean

Whether to use preserve modules mode.

Default

false

`Optional`preserveModulesRoot

preserveModulesRoot?: string

A directory path to input modules that should be stripped away from output.dir when using preserve modules mode.

`Optional`sanitizeFileName

sanitizeFileName?: boolean | ((name: string) => string)

Whether to enable chunk name sanitization (removal of non-URL-safe characters like \0, ? and *).

Set false to disable the sanitization. You can also provide a custom sanitization function.

Default

true

`Optional`sourcemap

sourcemap?: boolean | "inline" | "hidden"

Whether to generate sourcemaps.

false: No sourcemap will be generated.
true: A separate sourcemap file will be generated.
'inline': The sourcemap will be appended to the output file as a data URL.
'hidden': A separate sourcemap file will be generated, but the link to the sourcemap (//# sourceMappingURL comment) will not be included in the output file.

Default

false

`Optional`sourcemapBaseUrl

sourcemapBaseUrl?: string

The base URL for the links to the sourcemap file in the output file.

By default, relative URLs are generated. If this option is set, an absolute URL with that base URL will be generated. This is useful when deploying source maps to a different location than your code, such as a CDN or separate debugging server.

`Optional`sourcemapDebugIds

sourcemapDebugIds?: boolean

Whether to include debug IDs in the sourcemap.

When true, a unique debug ID will be emitted in source and sourcemaps which streamlines identifying sourcemaps across different builds.

Default

false

`Optional`sourcemapIgnoreList

sourcemapIgnoreList?:
    | boolean
    | ((relativeSourcePath: string, sourcemapPath: string) => boolean)
    | string | RegExp

Control which source files are included in the sourcemap ignore list.

Files in the ignore list are excluded from debugger stepping and error stack traces.

false: Include no source files in the ignore list
true: Include all source files in the ignore list
string: Files containing this string in their path will be included in the ignore list
RegExp: Files matching this regular expression will be included in the ignore list
function: Custom function to determine if a source should be ignored

:::tip Performance Using static values (boolean, string, or RegExp) is significantly more performant than functions. Calling JavaScript functions from Rust has extremely high overhead, so prefer static patterns when possible. :::

Example

// ✅ Preferred: Use RegExp for better performance
sourcemapIgnoreList: /node_modules/

// ✅ Preferred: Use string pattern for better performance
sourcemapIgnoreList: "vendor"

// ! Use sparingly: Function calls have high overhead
sourcemapIgnoreList: (source, sourcemapPath) => {
  return source.includes('node_modules') || source.includes('.min.');
}

Default

/node_modules/

`Optional`sourcemapPathTransform

sourcemapPathTransform?: (
relativeSourcePath: string,
sourcemapPath: string,
) => string

A transformation to apply to each path in a sourcemap.

Example

export default defineConfig({
  output: {
    sourcemap: true,
    sourcemapPathTransform: (source, sourcemapPath) => {
      // Remove 'src/' prefix from all source paths
      return source.replace(/^src//, '');
    },
  },
});

`Optional`strictExecutionOrder

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

`Optional`topLevelVar

topLevelVar?: boolean

Whether to use var declarations at the top level scope instead of function / class / let / const expressions.

Enabling this option can improve runtime performance of the generated code in certain environments.

Default

false

`Optional`virtualDirname

virtualDirname?: string

Specifies the directory name for "virtual" files that might be emitted by plugins when using preserve modules mode.

Default

'_virtual'

Interface OutputOptions

Index

Properties

Properties

OptionaladvancedChunks

Deprecated

OptionalassetFileNames

Default

Optionalbanner

OptionalchunkFileNames

Default

OptionalcleanDir

Default

OptionalcodeSplitting

Example

Default

Optionaldir

Default

OptionaldynamicImportInCjs

Default

OptionalentryFileNames

Default

OptionalesModule

Default

Optionalexports

Default

Optionalextend

Default

OptionalexternalLiveBindings

Default

Optionalfile

Optionalfooter

Optionalformat

Default

OptionalgeneratedCode

Optionalglobals

Example

OptionalhashCharacters

Default

OptionalinlineDynamicImports

Deprecated

Default

Optionalintro

OptionalkeepNames

Default

OptionallegalComments

OptionalmanualChunks

Deprecated

Optionalminify

Default

OptionalminifyInternalExports

Default

Optionalname

Example

Optionaloutro

Optionalpaths

Example

Example

Optionalplugins

See

OptionalpolyfillRequire

Default

OptionalpostBanner

OptionalpostFooter

OptionalpreserveModules

Default

OptionalpreserveModulesRoot

OptionalsanitizeFileName

Default

Optionalsourcemap

Default

OptionalsourcemapBaseUrl

OptionalsourcemapDebugIds

Default

OptionalsourcemapIgnoreList

Example

Default

OptionalsourcemapPathTransform

Example

OptionalstrictExecutionOrder

`Optional`advancedChunks

`Optional`assetFileNames

`Optional`banner

`Optional`chunkFileNames

`Optional`cleanDir

`Optional`codeSplitting

`Optional`dir

`Optional`dynamicImportInCjs

`Optional`entryFileNames

`Optional`esModule

`Optional`exports

`Optional`extend

`Optional`externalLiveBindings

`Optional`file

`Optional`footer

`Optional`format

`Optional`generatedCode

`Optional`globals

`Optional`hashCharacters

`Optional`inlineDynamicImports

`Optional`intro

`Optional`keepNames

`Optional`legalComments

`Optional`manualChunks

`Optional`minify

`Optional`minifyInternalExports

`Optional`name

`Optional`outro

`Optional`paths

`Optional`plugins

`Optional`polyfillRequire

`Optional`postBanner

`Optional`postFooter

`Optional`preserveModules

`Optional`preserveModulesRoot

`Optional`sanitizeFileName

`Optional`sourcemap

`Optional`sourcemapBaseUrl

`Optional`sourcemapDebugIds

`Optional`sourcemapIgnoreList

`Optional`sourcemapPathTransform

`Optional`strictExecutionOrder

`Optional`topLevelVar

`Optional`virtualDirname