Config Options
🚧 Under Construction
We are working on generating a more detailed reference. For now, please refer to Rollup's Config Options Reference and documentation on additional notable features.
InputOptions
input
plugins
external
resolve
resolve.alias
WARNING
resolve.alias
will not call resolveId
hooks of other plugin.
If you want to call resolveId
hooks of other plugin, use aliasPlugin
from rolldown/experimental
instead.
You could find more discussion in this issue
resolve.aliasFields
resolve.conditionNames
resolve.extensionAlias
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'] }
.
resolve.exportsFields
resolve.extensions
resolve.mainFields
resolve.mainFiles
resolve.modules
resolve.symlinks
resolve.tsconfigFilename
cwd
platform
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.
shimMissingExports
treeshake
logLevel
onLog
onwarn
moduleTypes
experimental
experimental.strictExecutionOrder
experimental.disableLiveBindings
experimental.viteMode
experimental.resolveNewUrlToAsset
experimental.hmr
experimental.chunkModulesOrder
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)
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).
experimental.attachDebugInfo
experimental.chunkImportMap
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'];
}
}
}
]
}
NOTE
If you want to learn more, you can check out the example here: examples/chunk-import-map
experimental.onDemandWrapping
experimental.incrementalBuild
Required to be used with watch
mode.
experimental.transformHiresSourcemap
define
Replace global variables or property accessors with the provided values.
Examples
- Replace the global variable
IS_PROD
withtrue
export default defineConfig({ define: { IS_PROD: 'true' // or JSON.stringify(true) } })
Result:
// Input
if (IS_PROD) {
console.log('Production mode')
}
// After bundling
if (true) {
console.log('Production mode')
}
- Replace the property accessor
process.env.NODE_ENV
with'production'
export default defineConfig({ define: { 'process.env.NODE_ENV': "'production'" } })
Result:
// Input
if (process.env.NODE_ENV === 'production') {
console.log('Production mode')
}
// After bundling
if ('production' === 'production') {
console.log('Production mode')
}
inject
Inject import statements on demand.
Supported patterns
{
// import { Promise } from 'es6-promise'
Promise: ['es6-promise', 'Promise'],
// import { Promise as P } from 'es6-promise'
P: ['es6-promise', 'Promise'],
// import $ from 'jquery'
$: 'jquery',
// import * as fs from 'node:fs'
fs: ['node:fs', '*'],
// Inject shims for property access pattern
'Object.assign': path.resolve( 'src/helpers/object-assign.js' ),
}
profilerNames
jsx
transform
Configure how the code is transformed. This process happens after the transform
hook.
To transpile legacy decorators, you could use
export default defineConfig({
transform: {
decorator: {
legacy: true,
},
},
})
For latest decorators proposal, rolldown is able to bundle them but doesn't support transpiling them yet.
watch
dropLabels
keepNames
checks
makeAbsoluteExternalsRelative
debug
debug.sessionId
preserveEntrySignatures
optimization
optimization.inlineConst
Inline imported constant values during bundling instead of preserving variable references.
When enabled, constant values from imported modules will be inlined at their usage sites, potentially reducing bundle size and improving runtime performance by eliminating variable lookups. options:
true
: equivalent to{ mode: 'all', pass: 1 }
, enabling constant inlining for all eligible constants with a single pass.false
: Disable constant inlining{ mode: 'smart' | 'all', pass?: number }
:mode: 'smart'
: Only inline constants in specific scenarios where it is likely to reduce bundle size and improve performance. Smart mode inlines constants in these specific scenarios:if (test) {} else {}
- condition expressions in if statementstest ? a : b
- condition expressions in ternary operatorstest1 || test2
- logical OR expressionstest1 && test2
- logical AND expressionstest1 ?? test2
- nullish coalescing expressions
mode: 'all'
: Inline all imported constants wherever they are used.pass
: Number of passes to perform for inlining constants.
example
// Input files:
// constants.js
export const API_URL = 'https://api.example.com';
// main.js
import { API_URL } from './constants.js';
console.log(API_URL);
// With inlineConst: true, the bundled output becomes:
console.log('https://api.example.com');
// Instead of:
const API_URL = 'https://api.example.com';
console.log(API_URL);
context
tsconfig
Allows you to specify where to find the TypeScript configuration file.
You may provide:
- a relative path to the configuration file. It will be resolved relative to cwd.
- an absolute path to the configuration file.
When a tsconfig path is specified, the module resolver will respect compilerOptions.paths
from the specified tsconfig.json
,
and the tsconfig options will be merged with the top-level transform
options, with the transform
options taking precedence.
OutputOptions
dir
file
exports
hashCharacters
format
sourcemap
sourcemapBaseUrl
sourcemapDebugIds
sourcemapIgnoreList
sourcemapPathTransform
banner
footer
intro
outro
extend
esModule
assetFileNames
entryFileNames
chunkFileNames
cssEntryFileNames
cssChunkFileNames
sanitizeFileName
minify
Control code minification.
true
: Enable full minification including code compression and dead code eliminationfalse
: Disable minification (default)'dce-only'
: Only perform dead code elimination without code compressionMinifyOptions
: Fine-grained control over minification settings
name
globals
externalLiveBindings
inlineDynamicImports
manualChunks
- Type:
((moduleId: string, meta: { getModuleInfo: (moduleId: string) => ModuleInfo | null }) => string | NullValue)
- Object form is not supported.
WARNING
- This option is deprecated. Please use
advancedChunks
instead. - If
manualChunks
andadvancedChunks
are both specified,manualChunks
option will be ignored.
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
{
advancedChunks: {
groups: [
{
name(moduleId) {
if (moduleId.includes('node_modules')) {
return 'vendor';
}
return null;
},
},
],
}
}
advancedChunks
Allows you to do manual chunking. For deeper understanding, please refer to the in-depth documentation.
advancedChunks.includeDependenciesRecursively
- Type:
boolean
- Default:
true
By default, each group will also include captured modules' dependencies. This reduces the chance of generating circular chunks.
If you want to disable this behavior, it's recommended to both set
preserveEntrySignatures: false
strictExecutionOrder: true
to avoid generating invalid chunks.
advancedChunks.minSize
- Type:
number
Global fallback of {group}.minSize
, if it's not specified in the group.
advancedChunks.maxSize
- Type:
number
Global fallback of {group}.maxSize
, if it's not specified in the group.
advancedChunks.maxModuleSize
- Type:
number
Global fallback of {group}.maxModuleSize
, if it's not specified in the group.
advancedChunks.minModuleSize
- Type:
number
Global fallback of {group}.minModuleSize
, if it's not specified in the group.
advancedChunks.minShareCount
- Type:
number
Global fallback of {group}.minShareCount
, if it's not specified in the group.
advancedChunks.groups
Groups to be used for advanced chunking.
advancedChunks.groups.name
- Type:
string | ((moduleId: string, ctx: { getModuleInfo: (moduleId: string) => ModuleInfo | null }) => string | NullValue)
Name of the group. It will be also used as the name of the chunk and replaced the [name]
placeholder in the chunkFileNames
option.
For example,
import { defineConfig } from 'rolldown';
export default defineConfig({
advancedChunks: {
groups: [
{
name: 'libs',
test: /node_modules/,
},
],
},
});
will create a chunk named libs-[hash].js
in the end.
It's ok to have the same name for different groups. Rolldown will deduplicate the chunk names if necessary.
Dynamic name()
If name
is a function, it will be called with the module id as the argument. The function should return a string or null
. If it returns null
, the module will be ignored by this group.
Notice, each returned new name will be treated as a separate group.
For example,
import { defineConfig } from 'rolldown';
export default defineConfig({
advancedChunks: {
groups: [
{
name: (moduleId) => moduleId.includes('node_modules') ? 'libs' : 'app',
minSize: 100 * 1024,
},
],
},
});
WARNING
Constraints like minSize
, maxSize
, etc. are applied separately for different names returned by the function.
advancedChunks.groups.test
- Type:
string | RegExp | ((id: string) => boolean | undefined | void);
Controls which modules are captured in this group.
- If
test
is a string, the module whose id contains the string will be captured. - If
test
is a regular expression, the module whose id matches the regular expression will be captured. - If
test
is a function, modules for whichtest(id)
returnstrue
will be captured. - If
test
is empty, any module will be considered as matched.
WARNING
When using regular expression, it's recommended to use [\\/]
to match the path separator instead of /
to avoid potential issues on Windows.
- ✅ Recommended:
/node_modules[\\/]react/
- ❌ Not recommended:
/node_modules/react/
advancedChunks.groups.priority
- Type:
number
- Default:
0
Priority of the group. Group with higher priority will be chosen first to match modules and create chunks. When converting the group to a chunk, modules of that group will be removed from other groups.
If two groups have the same priority, the group whose index is smaller will be chosen.
For example,
import { defineConfig } from 'rolldown';
export default defineConfig({
advancedChunks: {
groups: [
{
name: 'react',
test: /node_modules[\\/]react/,
priority: 1,
},
{
name: 'other-libs',
test: /node_modules/,
priority: 2,
},
],
});
This is a clearly incorrect example. Though react
group is defined before other-libs
, it has a lower priority, so the modules in react
group will be captured in other-libs
group.
advancedChunks.groups.minSize
- Type:
number
- Default:
0
Minimum size in bytes of the desired chunk. If the accumulated size of the captured modules by this group is smaller than this value, it will be ignored. Modules in this group will fall back to the automatic chunking
if they are not captured by any other group.
advancedChunks.groups.minShareCount
- Type:
number
- Default:
1
Controls if a module should be captured based on how many entry chunks reference it.
advancedChunks.groups.maxSize
- Type:
number
- Default:
Infinity
If the accumulated size in bytes of the captured modules by this group is larger than this value, this group will be split into multiple groups that each has size close to this value.
advancedChunks.groups.maxModuleSize
- Type:
number
- Default:
Infinity
Controls a module could only be captured if its size in bytes is smaller or equal than this value.
advancedChunks.groups.minModuleSize
- Type:
number
- Default:
0
Controls a module could only be captured if its size in bytes is larger or equal than this value.
legalComments
Control comments in the output.
none
: no commentsinline
: preserve comments that contain@license
,@preserve
or starts with//!
/*!
plugins
polyfillRequire
hoistTransitiveImports
preserveModules
virtualDirname
preserveModulesRoot
topLevelVar
minifyInternalExports
- Type:
boolean
- Default:
false
Whether to minify internal exports.