Default behavior

Rslib builds on Rsbuild and Rspack, adapting some of their default behaviors for library builds.

These default behaviors typically depend on options such as format, bundle, and output.target, as well as specific fields in the package.json and tsconfig.json files. You can change these behaviors through configuration and plugins.

Environment variables

When building library code, Rslib uses format to determine whether to preserve process.env.NODE_ENV expressions from the source code in the output or replace them with a specified value at build time:

Output format	Default behavior
`esm` / `cjs`	Preserves the expression so the consuming application can replace it and optimize the code in a subsequent build, or the runtime can choose branches based on the actual environment variable.
`umd` / `iife`	Loaded directly, so library builds replace the expression with the build process's `NODE_ENV`, which defaults to `'production'`.
`mf`	Loaded directly. By default, replaced with `'development'` during mf-dev and `'production'` during build.

You can specify a replacement value with source.define, or configure Rspack's optimization.nodeEnv through tools.rspack to adjust or disable replacement.

For details on other predefined environment variables, .env file loading rules, and variable replacement, see Environment variables.

Format, entries, and dependencies

The defaults for each format are:

Format	output.target	output.autoExternal	Supports bundle: false
`esm`	`'node'`	`true`	Yes
`cjs`	`'node'`	`true`	Yes
`umd`	`'node'`	`false`	No
`iife`	`'node'`	`false`	No
`mf`	`'web'`	`false`	No

Note

Automatic externalization of JavaScript dependencies through output.autoExternal only applies in bundle mode.

format and output.target specify the module format and target runtime, respectively. For browser libraries, set output.target to 'web', and MF also requires the Module Federation plugin.

Based on the output format, target runtime, and bundle setting, Rslib applies the following defaults to entries, directory structure, and dependencies:

Feature	Default behavior	Related links
Entries	Bundle mode finds `src/index`; bundleless mode matches `src/**` and preserves the file structure.	source.entry, bundle
Directory structure	Bundleless mode preserves paths relative to the longest common directory of input files, excluding type declaration files.	outBase
Module references	Bundleless mode rewrites local JS, style, and asset references to relative output paths, adding or replacing extensions; package specifiers are preserved.	redirect.js, redirect.style, redirect.asset
Automatic externals	Bundled ESM/CJS marks `dependencies`, `optionalDependencies`, and `peerDependencies` as external, including subpaths, but not `devDependencies`.	output.autoExternal, output.externals
external type	ESM: `modern-module`; CJS: `commonjs-import`; UMD: `umd`; IIFE/MF: `global`.	output.externals, externalsType
Node.js built-ins	When `output.target` is `'node'`, sets `externalsPresets.node: false` and explicitly marks built-ins as external so they use the format's `externalsType` and match `import` / `require` semantics, regardless of `output.autoExternal`.	output.externals, externalsPresets.node, externalsType

Syntax and module compatibility

Feature	Default behavior	Related links
Syntax target	When `output.target` is `'node'`, uses the minimum version from `package.json#engines.node`. Uses `esnext` when no version can be inferred or `output.target` is `'web'`.	syntax
Syntax transformation	Derives Rsbuild's `output.overrideBrowserslist` from `syntax` or its default value to control JavaScript and CSS syntax transforms, and sets Rspack's `target` to control runtime code syntax (`esnext` maps to `es2025`). Does not read the project's `.browserslistrc` or `package.json#browserslist` by default.	syntax, output.overrideBrowserslist, target
Variable declarations	When `output.target` is `'web'`, removes Rsbuild's `output.environment.const: false` preset to avoid forcing `var`.	output.environment
Dependency compilation	Skips SWC compilation of JavaScript files in `node_modules` by default, but still compiles TypeScript and JSX files.	source.include, source.exclude
Path aliases	Reads aliases from both `compilerOptions.paths` in `tsconfig.json` and `resolve.alias`. By default, `compilerOptions.paths` has higher priority.	resolve.alias, resolve.aliasStrategy
TypeScript imports	JavaScript extensions can resolve to TypeScript files, such as `.js` resolving to `.ts` or `.tsx`.	resolve.extensionAlias
Extension resolution	When an import omits its extension, tries `.ts`, `.tsx`, `.mjs`, `.js`, `.jsx`, and `.json` in that order.	resolve.extensions
Decorators	Uses `legacy` when `tsconfig.json` enables `experimentalDecorators`; otherwise, `2023-11`.	source.decorators
JSX	Supports transforming JSX into JavaScript by default. Bundleless mode also supports preserving JSX syntax.	JSX transformation
Dynamic module paths	ESM/CJS preserves dynamic-path `import()` / `require()`, `require.resolve()`, and `require` as a value. Static-path `import()` can still produce chunks.	module.parser.javascript.importDynamic module.parser.javascript.requireDynamic module.parser.javascript.requireResolve module.parser.javascript.requireAsExpression
Module type detection	Preserves Rspack's default module type detection based on file extensions and `package.json#type`; for example, `.mjs` files are treated as `javascript/esm`. Rslib removes the `type: 'javascript/auto'` preset that Rsbuild applies to JavaScript, TypeScript, and JSX files matched by its SWC compilation rule.	module.rules
CommonJS exports	ESM/CJS sets `commonjs.exports: 'skipInEsm'` to preserve assignments to `module.exports` and `exports` in ESM source files.	module.parser.javascript.commonjs
CommonJS shims	CJS enables compatibility for `import.meta.url`, `import.meta.dirname`, and `import.meta.filename`.	shims.cjs
ESM shims	Shims for `__dirname`, `__filename`, and `require` are disabled.	shims.esm
SWC helpers	`externalHelpers: false` inlines required helpers by default. Rsbuild imports them from @swc/helpers during SWC compilation.	externalHelpers
Polyfills	`output.polyfill: 'off'` does not add runtime APIs automatically.	output.polyfill, Output compatibility

Optimization and chunks

Rslib uses Rsbuild's mode configuration to select build and optimization behavior:

rslib and rslib --watch use 'production', with watch mode only adding file watching and rebuilds.
rslib mf-dev uses 'development' for the MF development server.

mode is configured independently of the build process's NODE_ENV. For example, NODE_ENV=development rslib still builds with mode: 'production'.

Rslib adjusts the following optimization defaults:

Feature	Default behavior	Related links
Minification	Removes dead and unused code in production mode, preserving variable names and Pure annotations. ESM/CJS/UMD/IIFE preserves formatting. MF removes unnecessary whitespace and line breaks and disables top-level unused code elimination to preserve remote entry globals.	output.minify
Chunk splitting	`splitChunks.preset: 'none'`; ESM/CJS extracts common code only from async chunks; UMD/IIFE disables splitting and async chunks.	splitChunks, optimization.splitChunks, output.asyncChunks
Module IDs	Non-MF formats use `'named'` for readable IDs when `output.target` is `'node'`, and `'deterministic'` for stable IDs when `output.target` is `'web'`. MF uses `'deterministic'` when `mode` is `'production'`, and `'named'` when it is `'development'`.	optimization.moduleIds
Chunk IDs	Inherits Rspack: `'deterministic'` in production mode and `'named'` in development mode.	optimization.chunkIds
ESM output optimization	Sets `concatenateModules: false`, `sideEffects: true`, and `avoidEntryIife: true`, alongside `modern-module` output for downstream tree shaking.	optimization.concatenateModules, optimization.sideEffects, optimization.avoidEntryIife
Shared runtime	ESM sets `runtimeChunk: { name: 'rslib-runtime' }` for bundleless builds or multiple explicit entries to share runtime code.	optimization.runtimeChunk

Note

Setting output.minify replaces Rslib's entire minimizer preset, even when you pass a partial object. output.minify: false disables only the minimizer. Rspack still analyzes used exports and side effects, but unused declarations may remain in the output.
splitChunks.preset: 'none' does not guarantee a single output file: dynamic imports, multiple entries, Workers, and runtime code can produce additional files.

Output files

Feature	Default behavior	Related links
Output directory	Uses `dist` as the root, with JS/CSS directly inside it and other assets grouped by type.	output.distPath
JavaScript extensions	`autoExtension: true` selects `.js`, `.mjs`, or `.cjs` based on the format and `package.json#type`.	autoExtension, output.filename
Filename hashes	Non-MF formats omit hashes for stable filenames. MF adds hashes to JS/CSS filenames by default in production mode and omits them in development mode.	output.filenameHash
JavaScript filenames	Non-MF formats use `[name]` plus the automatic extension, such as `[name].mjs`; `filenameHash: true` adds `[contenthash:10]`.	output.filename, output.filenameHash
Chunk filenames	By default, filenames for both entry files and async chunks are configured through Rsbuild's `output.filename.js`. With multiple `lib` items, non-MF helper and async chunks get suffixes based on each object's position in the `lib` array: `~0` for the first, `~1` for the second, and so on to avoid collisions; entry names stay unchanged. Custom filename functions receive no suffix and also name async chunks.	Rsbuild output.filename, Rspack output.filename, output.chunkFilename
Library export type	`output.library.type` is `'modern-module'` with `output.module: true` for ESM, `'commonjs-static'` for CJS, `'umd'` for UMD, and `'module'` with `output.iife: true` for IIFE.	output.library.type, output.iife, output.module
UMD export name	When `format` is `'umd'`, sets `output.library.type: 'umd'` and uses `umdName` as Rspack's `output.library.name`. The name is unset by default.	umdName, output.library.name
Chunk format and loading	ESM uses `chunkFormat: false` and `chunkLoading: 'import'`. CJS uses `chunkFormat: 'commonjs'`, `chunkLoading: 'require'`, and `iife: false`.	output.chunkFormat, output.chunkLoading, output.iife
IIFE global object	Uses `output.globalObject: 'globalThis'` to access global external dependencies.	output.globalObject
Cleaning output	`output.cleanDistPath: 'auto'` cleans output directories only when they are subdirectories of the project root.	output.cleanDistPath
Source maps	Production builds omit JS/CSS source maps; MF development mode generates JS source maps.	output.sourceMap
HTML	`tools.htmlPlugin: false` skips HTML generation.	tools.htmlPlugin
MF output	`output.uniqueName` comes from `package.json#name`; `mf-dev` writes output to disk.	output.uniqueName, dev.writeToDisk

Static assets

Feature	Default behavior	Related links
Assets imported in JavaScript	ESM/CJS uses `assetPrefix: 'auto'`, emits assets, and preserves `import`/`require`; other formats use `'/'`.	output.assetPrefix
Asset inlining	ESM/CJS disables inlining with a threshold of `0`; other formats inherit Rsbuild's 4 KiB threshold.	output.dataUriLimit
`new URL()`	ESM processes static `new URL(..., import.meta.url)` references, emitting original assets with relative output paths.	new URL imports
Workers	ESM builds `new Worker(new URL(...))` references as ES module Workers with `type: 'module'`. `workerChunkLoading` is `'import'` for ESM and `'async-node'` for CJS.	Web Workers, module.parser.javascript.worker, output.workerChunkLoading
Wasm	ESM bundle mode uses `compile` to generate loading code; bundleless uses `preserve` to keep imports and copy files.	wasm.mode

CSS

Feature	Default behavior	Related links
CSS output	Emits CSS when `output.target` is `'web'`, and omits it when `output.target` is `'node'`. `output.injectStyles: false` emits separate CSS files.	output.emitCss, output.injectStyles
Style references	CSS extraction combines styles and removes JS style imports in bundle mode; bundleless emits per source file and preserves imports.	bundle, CSS
CSS Modules	Matches `.module.*`; bundleless emits a JS module with class mappings and a CSS import.	output.cssModules
Assets and references in CSS	ESM/CJS resolves CSS `url()` to relative asset paths; bundleless sets `tools.cssLoader.import: false` to preserve CSS `@import`.	redirect.style, Assets in CSS, tools.cssLoader
CSS minification	Disabled, leaving final optimization to consumers.	output.minify

Type declarations

Rslib does not generate type declarations by default. dts: true emits unbundled declarations independently of JavaScript's bundle setting. Multiple JavaScript outputs can share declarations, so enabling dts in one lib item is usually enough.

Feature	Default behavior	Related links
Generation method	Selects the generation method based on the project's installed TypeScript version: 5/6 uses the Compiler API, while 7+ uses the native TypeScript CLI.	dts.typescriptPath, dts.isolated, dts.tsgo
Input scope	By default, declaration inputs follow `tsconfig.json`; `rootDir` determines the directory structure.	source.tsconfigPath
Output directory	Priority: `dts.distPath` → `tsconfig.json#declarationDir` → JS output root.	dts.distPath
Bundling	`dts.bundle: false`; when enabled, API Extractor bundles declarations per entry.	dts.bundle
Dependency handling	When bundling type declarations, uses `output.autoExternal` and `output.externals` to determine externals and bundles declarations from the remaining direct dependencies, excluding @types/react by default.	dts.bundle.bundledPackages, output.autoExternal, output.externals
File extensions	`dts.autoExtension: false` defaults to `.d.ts`; in unbundled output, `.mts` and `.cts` source files produce `.d.mts` and `.d.cts`, respectively.	dts.autoExtension
Import paths	`redirect.dts.path` and `redirect.dts.extension` both default to `true`, converting path aliases to relative paths and adding or replacing JavaScript extensions in references.	redirect.dts.path, redirect.dts.extension
Path aliases	Reads `compilerOptions.paths` from `tsconfig.json` by default. When `dts.alias` is configured, it takes priority for matching aliases.	dts.alias
Type errors	`dts.abortOnError: true` fails the build on declaration generation errors.	dts.abortOnError
Project references	`dts.build: false` skips automatic builds of TypeScript project references.	dts.build

Build performance and output size

Feature	Default behavior	Related links
Persistent cache	Enabled by default; disabled by default in Rsbuild.	performance.buildCache
File size logs	Bundleless mode prints only the file count and total size.	performance.printFileSize

Change and inspect defaults

Put shared settings at the top level and settings for one output in its lib item. Per-lib settings take priority over shared settings and determine the corresponding default behavior. Explicit CLI build options override the corresponding file configuration; see CLI.

Objects are usually merged recursively and arrays appended, while options such as resolve.extensions are replaced. See Configuration merge rules. When combining configurations with mergeRslibConfig, lib items with the same id are merged and items without an id are appended.

You can adjust the Rspack options in the tables through tools.rspack and check its documentation for usage, while other Rslib and Rsbuild options are listed in the Configuration overview.

You can enable debug mode or run rslib inspect to view the final generated configuration.

#Default behavior

#Environment variables

#Format, entries, and dependencies

#Syntax and module compatibility

#Optimization and chunks

#Output files

#Static assets

#CSS

#Type declarations

#Build performance and output size

#Change and inspect defaults