--- url: /reference/Interface.OutputOptions.md --- # Interface: OutputOptions ## Properties ### ~~advancedChunks?~~ * **Type**: object with the properties below * **Optional** #### ~~groups?~~ * **Type**: [`CodeSplittingGroup`](TypeAlias.CodeSplittingGroup.md)\[] * **Optional** #### ~~includeDependenciesRecursively?~~ * **Type**: `boolean` * **Optional** #### ~~maxModuleSize?~~ * **Type**: `number` * **Optional** #### ~~maxSize?~~ * **Type**: `number` * **Optional** #### ~~minModuleSize?~~ * **Type**: `number` * **Optional** #### ~~minShareCount?~~ * **Type**: `number` * **Optional** #### ~~minSize?~~ * **Type**: `number` * **Optional** #### Deprecated Please use [`output.codeSplitting`](#codesplitting) instead. Allows you to do manual chunking. :::warning If `advancedChunks` and `codeSplitting` are both specified, `advancedChunks` option will be ignored. ::: *** ### assetFileNames? * **Type**: `string` | ((`chunkInfo`) => `string`) * **Optional** 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`](Interface.PreRenderedAsset.md) 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`](#hashcharacters). * `[name]`: The file name of the asset excluding any extension. Forward slashes (`/`) can be used to place files in sub-directories. See also [`output.chunkFileNames`](#chunkfilenames), [`output.entryFileNames`](#entryfilenames). #### Default ```ts 'assets/[name]-[hash][extname]' ``` *** ### banner? * **Type**: `string` | ((`chunk`) => `string` | `Promise`<`string`>) * **Optional** A string to prepend to the bundle before [`renderChunk`](Interface.Plugin.md#renderchunk) hook. See [`output.intro`](#intro), [`output.postBanner`](#postbanner) as well. :::warning When using `output.banner` with minification enabled, the banner content may be stripped out unless it is formatted as a legal comment. To ensure your banner persists through minification, do either: * Use [`output.postBanner`](/reference/OutputOptions.postBanner) instead, which are added after minification, or * Use one of these comment formats: * Comments starting with `/*!` (e.g., `/*! My banner */`) * Comments containing `@license` (e.g., `/* @license My banner */`) * Comments containing `@preserve` (e.g., `/* @preserve My banner */`) * Comments starting with `//!` (for single-line comments) The latter way's behavior is controlled by the [`output.legalComments`](/reference/OutputOptions.legalComments) option, which defaults to `'inline'` and preserves these special comment formats. ::: #### Examples ##### Adding shebang for CLI tools ```js export default { output: { banner: (chunk) => { // Add shebang only to the CLI entry point if (chunk.name === 'cli') { return '#!/usr/bin/env node'; } return ''; }, }, }; ``` ##### Adding "use strict" directive ```js export default { output: { format: 'cjs', banner: '"use strict";', }, }; ``` *** ### chunkFileNames? * **Type**: `string` | ((`chunkInfo`) => `string`) * **Optional** The pattern to use for naming shared chunks created when code-splitting, or a function that is called per chunk with [`PreRenderedChunk`](Interface.PreRenderedChunk.md) 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`](TypeAlias.InternalModuleFormat.md). * `[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`](#hashcharacters). * `[name]`: The name of the chunk. This can be explicitly set via the [`output.codeSplitting`](#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. See also [`output.assetFileNames`](#assetfilenames), [`output.entryFileNames`](#entryfilenames). #### Default ```ts '[name]-[hash].js' ``` *** ### cleanDir? * **Type**: `boolean` * **Optional** Clean output directory ([`output.dir`](#dir)) before emitting output. #### Default false #### Examples ##### Basic usage ```js export default { output: { cleanDir: true, }, }; ``` ##### Multiple outputs in one config When multiple outputs share the same directory, only set `cleanDir: true` for the first output: ```js export default { output: [ { dir: 'dist', format: 'es', cleanDir: true, // Clean on first output }, { dir: 'dist', format: 'cjs', // cleanDir defaults to false, so files from first output are preserved }, ], }; ``` ##### Multiple configurations When multiple configurations share the same directory, only set `cleanDir: true` for the first configuration: ```js export default [ { input: 'src/index.js', output: { dir: 'dist', cleanDir: true, // Clean on first configuration }, }, { input: 'src/other.js', output: { dir: 'dist', // cleanDir defaults to false, so files from first config are preserved }, }, ]; ``` ##### Different directories in multiple outputs When multiple outputs use different directories, you can safely use `cleanDir: true` for each: ```js export default { output: [ { dir: 'dist/es', format: 'es', cleanDir: true, // Safe - different directory }, { dir: 'dist/cjs', format: 'cjs', cleanDir: true, // Safe - different directory }, ], }; ``` #### In-depth ##### Execution timing The timing of the directory cleanup is important for plugin compatibility: * The cleanup occurs **before** the `generateBundle` hook is called * Files created by plugins during `generateBundle` or `writeBundle` hooks are **not** deleted * This ensures that plugin-generated files are preserved even when `cleanDir` is enabled For advanced use cases involving multiple outputs with the same `output.dir`, consider using a separate cleanup script for more control over the cleanup process. ##### ⚠️ Multiple configurations behavior When using multiple configurations or outputs, the `cleanDir` option will be executed **separately for each configuration/output** following the order they are defined. **The two patterns:** * **Multiple configurations**: `export default defineConfig([{ output: { cleanDir: true, ... } }, { output: {...} }])` * **Multiple outputs in one config**: `defineConfig({ output: [{ cleanDir: true, ... }, { ... }] })` **The problem:** If multiple outputs share the same `output.dir` and have `cleanDir: true`, later outputs may clean files generated by earlier outputs. This happens because each output executes its cleanup independently. **Best practice:** To avoid this issue, only set `cleanDir: true` for the first output, or use different output directories. This ensures that all generated files are preserved. *** ### codeSplitting? * **Type**: `boolean` | [`CodeSplittingOptions`](TypeAlias.CodeSplittingOptions.md) * **Optional** 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](/in-depth/manual-code-splitting). :::warning Be aware that manual code splitting can change the behavior of the application if side effects are triggered before the corresponding modules are actually used. You can change the chunking configuration to keep order-sensitive modules together, or you can use the [`output.strictExecutionOrder`](/reference/OutputOptions.strictExecutionOrder) option to preserve source execution order. The option wraps modules so their bodies run in source order, at a bundle-size cost; `experimental.onDemandWrapping` replaces wrap-all with a conservative plan derived from predicted chunk execution hazards. ::: #### Example **Basic vendor chunk** ```js export default defineConfig({ output: { codeSplitting: { minSize: 20000, groups: [ { name: 'vendor', test: /node_modules/, }, ], }, }, }); ``` **Multiple chunk groups with priorities** ```js export default defineConfig({ output: { codeSplitting: { groups: [ { name: 'react-vendor', test: /node_modules[\\/]react/, priority: 20, }, { name: 'ui-vendor', test: /node_modules[\\/]antd/, priority: 15, }, { name: 'vendor', test: /node_modules/, priority: 10, }, { name: 'common', minShareCount: 2, minSize: 10000, priority: 5, }, ], }, }, }); ``` **Size-based splitting** ```js export default defineConfig({ output: { codeSplitting: { groups: [ { name: 'large-libs', test: /node_modules/, minSize: 100000, // 100KB maxSize: 250000, // 250KB priority: 10, }, ], }, }, }); ``` #### Default ```ts true ``` *** ### comments? * **Type**: `boolean` | [`CommentsOptions`](Interface.CommentsOptions.md) * **Optional** Control which comments are preserved in the output. * `true`: Preserve legal, annotation, and JSDoc comments (default) * `false`: Strip all comments * Object: Granular control over comment categories Note: Regular line and block comments without these markers are always removed regardless of this option. When both `legalComments` and `comments.legal` are set, `comments.legal` takes priority. #### Default ```ts true ``` *** ### dir? * **Type**: `string` * **Optional** The directory in which all generated chunks are placed. The [`output.file`](#file) option can be used instead if only a single chunk is generated. The output directory will be generated if it does not already exist, but it will not be cleared if it already contains some files. Any generated files will silently overwrite existing files with the same name. If you want the output directory to only contain files from the current run, you can use [`output.cleanDir`](/reference/OutputOptions.cleanDir) option. #### Default ```ts 'dist' ``` *** ### dynamicImportInCjs? * **Type**: `boolean` * **Optional** 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 ```ts true ``` *** ### entryFileNames? * **Type**: `string` | ((`chunkInfo`) => `string`) * **Optional** The pattern to use for chunks created from entry points, or a function that is called per entry chunk with [`PreRenderedChunk`](Interface.PreRenderedChunk.md) 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`](TypeAlias.InternalModuleFormat.md). * `[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`](#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`](#preservemodules) option. See also [`output.assetFileNames`](#assetfilenames), [`output.chunkFileNames`](#chunkfilenames). #### Default ```ts '[name].js' ``` *** ### esModule? * **Type**: `boolean` | `"if-default-prop"` * **Optional** Whether to add a `__esModule: true` property when generating exports for non-ES [formats](#format). 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](#exports), which is similar to what other tools do. * `"if-default-prop"`: Only add the property when using [named exports mode](#exports) 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' #### Interaction with Consuming Tools Different tools handle the `__esModule` marker differently when importing your bundle: * **Rolldown**: Use heuristics based on Node.js's behavior. See the [Bundling CJS](/in-depth/bundling-cjs#ambiguous-default-import-from-cjs-modules) guide for more details. * **esbuild**: Use heuristics based on Node.js's behavior. * **Node.js**: Does not respect `__esModule`. The default export is the `module.exports` value. * **Babel**: Respects `__esModule`. *** ### exports? * **Type**: `"auto"` | `"named"` | `"default"` | `"none"` * **Optional** Which exports mode to use. When `'auto'` is used, Rolldown will automatically determine the export mode based on the exports of the `input` modules. If the `input` modules have a single default export, then `'default'` mode is used. If the `input` modules have named exports, then `'named'` mode is used. If there are no exports, then `'none'` mode is used. `'default'` can only be used when the `input` modules have a single default export. `'none'` can only be used when the `input` modules have no exports. Otherwise, Rolldown will throw an error. The difference between `'default'` and `'named'` affects how other people can consume your bundle. If you use `'default'`, a CommonJS user could do this, for example: ```js // your-lib package entry export default 'Hello world'; // a CommonJS consumer /* require( "your-lib" ) returns "Hello world" */ const hello = require('your-lib'); ``` With `'named'`, a user would do this instead: ```js // your-lib package entry export const hello = 'Hello world'; // a CommonJS consumer /* require( "your-lib" ) returns {hello: "Hello world"} */ const hello = require('your-lib').hello; /* or using destructuring */ const { hello } = require('your-lib'); ``` The wrinkle is that if you use `'named'` exports but also have a default export, a user would have to do something like this to use the default export: ```js // your-lib package entry export default 'foo'; export const bar = 'bar'; // a CommonJS consumer /* require( "your-lib" ) returns {default: "foo", bar: "bar"} */ const foo = require('your-lib').default; const bar = require('your-lib').bar; /* or using destructuring */ const { default: foo, bar } = require('your-lib'); ``` ::: tip There are many tools that are capable of resolving a CommonJS `require(...)` call with an ES module. If you are generating CommonJS output that is meant to be interchangeable with ESM output for those tools, you should always use `'named'` export mode. The reason is that most of those tools will by default return the namespace of an ES module on `require` where the default export is the `.default` property. In other words for those tools, you cannot create a package interface where `const lib = require("your-lib")` yields the same as `import lib from "your-lib"`. With `'named'` export mode however, `const {lib} = require("your-lib")` will be equivalent to `import {lib} from "your-lib"`. ::: #### Default ```ts 'auto' ``` *** ### extend? * **Type**: `boolean` * **Optional** Whether to extend the global variable defined by the [`name`](#name) option in `umd` or `iife` [formats](#format). 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 ```ts false ``` *** ### externalLiveBindings? * **Type**: `boolean` * **Optional** Whether to generate code to support live bindings for [external](Interface.InputOptions.md#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 #### Example ```js // input export { x } from 'external'; ``` ```js // CJS output with externalLiveBindings: true var external = require('external'); Object.defineProperty(exports, 'x', { enumerable: true, get: function () { return external.x; }, }); ``` ```js // CJS output with externalLiveBindings: false var external = require('external'); exports.x = external.x; ``` *** ### file? * **Type**: `string` * **Optional** The file path for the single generated chunk. The [`output.dir`](#dir) option should be used instead if multiple chunks are generated. *** ### footer? * **Type**: `string` | ((`chunk`) => `string` | `Promise`<`string`>) * **Optional** A string to append to the bundle before [`renderChunk`](Interface.Plugin.md#renderchunk) hook. See [`output.outro`](#outro), [`output.postFooter`](#postfooter) as well. :::warning When using `output.footer` with minification enabled, the footer content may be stripped out unless it is formatted as a legal comment. To ensure your footer persists through minification, do either: * Use [`output.postFooter`](/reference/OutputOptions.postFooter) instead, which is added after minification, or * Use one of these comment formats: * Comments starting with `/*!` (e.g., `/*! My footer */`) * Comments containing `@license` (e.g., `/* @license My footer */`) * Comments containing `@preserve` (e.g., `/* @preserve My footer */`) * Comments starting with `//!` (for single-line comments) The latter way's behavior is controlled by the [`output.legalComments`](/reference/OutputOptions.legalComments) option, which defaults to `'inline'` and preserves these special comment formats. ::: #### Examples ##### Expose the default export as `module.exports` for CJS output with all named exports as properties ```js export default { output: { format: 'cjs', exports: 'named', footer: (chunk) => { if (chunk.isEntry) { return ` module.exports = exports.default; module.exports.default = module.exports; module.exports.foo = module.exports.default.foo;`; } return ''; }, }, }; ``` *** ### format? * **Type**: `"es"` | `"cjs"` | `"iife"` | `"umd"` | `"module"` | `"esm"` | `"commonjs"` * **Optional** 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](https://developer.mozilla.org/en-US/docs/Glossary/IIFE). * `'umd'` stands for [Universal Module Definition](https://github.com/umdjs/umd). #### Default 'es' #### In-depth ##### ES Module [ES modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) (ESM) are the official JavaScript module standard. When `output.format: 'es'` is used, the bundle will use `export` syntax like this: ```js function exportedFunction() { /* ... */ } let exportedValue = '/* ... */'; export { exportedFunction, exportedValue }; ``` To load ES modules, use `