> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
# 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](/config/lib/format.md), [bundle](/config/lib/bundle.md), and [output.target](/config/rsbuild/output.md#outputtarget), as well as specific fields in the `package.json` and `tsconfig.json` files. You can change these behaviors through configuration and plugins.
## Environment variables \{#environment-variables}
When building library code, Rslib uses [format](/config/lib/format.md) 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](/guide/basic/cli.md#rslib-mf-dev) and `'production'` during [build](/guide/basic/cli.md#rslib). |
You can specify a replacement value with [source.define](/config/rsbuild/source.md#sourcedefine), or configure Rspack's [optimization.nodeEnv](https://rspack.rs/config/optimization#optimizationnodeenv) through [tools.rspack](/config/rsbuild/tools.md#toolsrspack) to adjust or disable replacement.
For details on other predefined environment variables, `.env` file loading rules, and variable replacement, see [Environment variables](/guide/advanced/env-vars.md).
## Format, entries, and dependencies
The defaults for each [format](/config/lib/format.md) are:
| Format | [output.target](/config/rsbuild/output.md#outputtarget) | [output.autoExternal](/config/rsbuild/output.md#outputautoexternal) | Supports [bundle: false](/config/lib/bundle.md#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](/config/lib/format.md) and [output.target](/config/rsbuild/output.md#outputtarget) specify the module format and target runtime, respectively. For browser libraries, set `output.target` to `'web'`, and MF also requires the [Module Federation plugin](/guide/advanced/module-federation.md#quick-start).
Based on the output format, target runtime, and [bundle](/config/lib/bundle.md) 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](/config/rsbuild/source.md#sourceentry), [bundle](/config/lib/bundle.md) |
| Directory structure | Bundleless mode preserves paths relative to the longest common directory of input files, excluding type declaration files. | [outBase](/config/lib/out-base.md) |
| 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](/config/lib/redirect.md#redirectjs), [redirect.style](/config/lib/redirect.md#redirectstyle), [redirect.asset](/config/lib/redirect.md#redirectasset) |
| Automatic externals | Bundled ESM/CJS marks `dependencies`, `optionalDependencies`, and `peerDependencies` as external, including subpaths, but not `devDependencies`. | [output.autoExternal](/config/rsbuild/output.md#outputautoexternal), [output.externals](/config/rsbuild/output.md#outputexternals) |
| external type | ESM: `modern-module`; CJS: `commonjs-import`; UMD: `umd`; IIFE/MF: `global`. | [output.externals](/config/rsbuild/output.md#outputexternals), [externalsType](https://rspack.rs/config/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](/config/rsbuild/output.md#outputexternals), [externalsPresets.node](https://rspack.rs/config/externals#externalspresets), [externalsType](https://rspack.rs/config/externals#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](/config/lib/syntax.md) |
| 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](/config/lib/syntax.md), [output.overrideBrowserslist](/config/rsbuild/output.md#outputoverridebrowserslist), [target](https://rspack.rs/config/target) |
| Variable declarations | When `output.target` is `'web'`, removes Rsbuild's `output.environment.const: false` preset to avoid forcing `var`. | [output.environment](https://rspack.rs/config/output#outputenvironment) |
| Dependency compilation | Skips SWC compilation of JavaScript files in `node_modules` by default, but still compiles TypeScript and JSX files. | [source.include](/config/rsbuild/source.md#sourceinclude), [source.exclude](/config/rsbuild/source.md#sourceexclude) |
| Path aliases | Reads aliases from both `compilerOptions.paths` in `tsconfig.json` and `resolve.alias`. By default, `compilerOptions.paths` has higher priority. | [resolve.alias](/config/rsbuild/resolve.md#resolvealias), [resolve.aliasStrategy](/config/rsbuild/resolve.md#resolvealiasstrategy) |
| TypeScript imports | JavaScript extensions can resolve to TypeScript files, such as `.js` resolving to `.ts` or `.tsx`. | [resolve.extensionAlias](https://rspack.rs/config/resolve#resolveextensionalias) |
| Extension resolution | When an import omits its extension, tries `.ts`, `.tsx`, `.mjs`, `.js`, `.jsx`, and `.json` in that order. | [resolve.extensions](/config/rsbuild/resolve.md#resolveextensions) |
| Decorators | Uses `legacy` when `tsconfig.json` enables `experimentalDecorators`; otherwise, `2023-11`. | [source.decorators](/config/rsbuild/source.md#sourcedecorators) |
| JSX | Supports transforming JSX into JavaScript by default. Bundleless mode also supports preserving JSX syntax. | [JSX transformation](/guide/solution/react.md#jsx-transform) |
| 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](https://rspack.rs/config/module-parser#javascriptimportdynamic)
[module.parser.javascript.requireDynamic](https://rspack.rs/config/module-parser#javascriptrequiredynamic)
[module.parser.javascript.requireResolve](https://rspack.rs/config/module-parser#javascriptrequireresolve)
[module.parser.javascript.requireAsExpression](https://rspack.rs/config/module-parser#javascriptrequireasexpression) |
| 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](https://rspack.rs/config/module-rules#rulestype) |
| CommonJS exports | ESM/CJS sets `commonjs.exports: 'skipInEsm'` to preserve assignments to `module.exports` and `exports` in ESM source files. | [module.parser.javascript.commonjs](https://rspack.rs/config/module-parser#javascriptcommonjs) |
| CommonJS shims | CJS enables compatibility for `import.meta.url`, `import.meta.dirname`, and `import.meta.filename`. | [shims.cjs](/config/lib/shims.md#shimscjs) |
| ESM shims | Shims for `__dirname`, `__filename`, and `require` are disabled. | [shims.esm](/config/lib/shims.md#shimsesm) |
| SWC helpers | `externalHelpers: false` inlines required helpers by default. Rsbuild imports them from [@swc/helpers](https://www.npmjs.com/package/@swc/helpers) during SWC compilation. | [externalHelpers](/config/lib/external-helpers.md) |
| Polyfills | `output.polyfill: 'off'` does not add runtime APIs automatically. | [output.polyfill](/config/rsbuild/output.md#outputpolyfill), [Output compatibility](/guide/advanced/output-compatibility.md) |
## Optimization and chunks
Rslib uses Rsbuild's [mode](https://rsbuild.rs/config/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](/config/rsbuild/output.md#outputminify) |
| Chunk splitting | `splitChunks.preset: 'none'`; ESM/CJS extracts common code only from async chunks; UMD/IIFE disables splitting and async chunks. | [splitChunks](https://rsbuild.rs/config/split-chunks), [optimization.splitChunks](https://rspack.rs/config/optimization#optimizationsplitchunks), [output.asyncChunks](https://rspack.rs/config/output#outputasyncchunks) |
| Module IDs | Non-MF formats use `'named'` when `output.target` is `'node'` and inherit Rsbuild's default `'compact-hashed'` when it is `'web'`.
MF format inherits Rsbuild's default: `'compact-hashed'` for regular builds and `'named'` for `mf-dev`. | [optimization.moduleIds](https://rspack.rs/config/optimization#optimizationmoduleids) |
| Chunk IDs | Inherits Rsbuild's default: `'compact-hashed'` for regular builds and `'named'` for `mf-dev`. | [optimization.chunkIds](https://rspack.rs/config/optimization#optimizationchunkids) |
| ESM output optimization | Sets `concatenateModules: false`, `sideEffects: true`, and `avoidEntryIife: true`, alongside `modern-module` output for downstream tree shaking. | [optimization.concatenateModules](https://rspack.rs/config/optimization#optimizationconcatenatemodules), [optimization.sideEffects](https://rspack.rs/config/optimization#optimizationsideeffects), [optimization.avoidEntryIife](https://rspack.rs/config/optimization#optimizationavoidentryiife) |
| Shared runtime | ESM sets `runtimeChunk: { name: 'rslib-runtime' }` for bundleless builds or multiple explicit entries to share runtime code. | [optimization.runtimeChunk](https://rspack.rs/config/optimization#optimizationruntimechunk) |
:::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](/config/rsbuild/output.md#outputdistpath) |
| JavaScript extensions | `autoExtension: true` selects `.js`, `.mjs`, or `.cjs` based on the format and `package.json#type`. | [autoExtension](/config/lib/auto-extension.md), [output.filename](/config/rsbuild/output.md#outputfilename) |
| 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](/config/rsbuild/output.md#outputfilenamehash) |
| JavaScript filenames | Non-MF formats use `[name]` plus the automatic extension, such as `[name].mjs`; `filenameHash: true` adds `[contenthash:10]`. | [output.filename](/config/rsbuild/output.md#outputfilename), [output.filenameHash](/config/rsbuild/output.md#outputfilenamehash) |
| 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](/config/rsbuild/output.md#outputfilename), [Rspack output.filename](https://rspack.rs/config/output#outputfilename), [output.chunkFilename](https://rspack.rs/config/output#outputchunkfilename) |
| 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](https://rspack.rs/config/output#outputlibrarytype), [output.iife](https://rspack.rs/config/output#outputiife), [output.module](https://rspack.rs/config/output#outputmodule) |
| 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](/config/lib/umd-name.md), [output.library.name](https://rspack.rs/config/output#outputlibraryname) |
| Chunk format and loading | ESM uses `chunkFormat: false` and `chunkLoading: 'import'`. CJS uses `chunkFormat: 'commonjs'`, `chunkLoading: 'require'`, and `iife: false`. | [output.chunkFormat](https://rspack.rs/config/output#outputchunkformat), [output.chunkLoading](https://rspack.rs/config/output#outputchunkloading), [output.iife](https://rspack.rs/config/output#outputiife) |
| IIFE global object | Uses `output.globalObject: 'globalThis'` to access global external dependencies. | [output.globalObject](https://rspack.rs/config/output#outputglobalobject) |
| Cleaning output | `output.cleanDistPath: 'auto'` cleans output directories only when they are subdirectories of the project root. | [output.cleanDistPath](/config/rsbuild/output.md#outputcleandistpath) |
| Source maps | Production builds omit JS/CSS source maps; MF development mode generates JS source maps. | [output.sourceMap](/config/rsbuild/output.md#outputsourcemap) |
| HTML | `tools.htmlPlugin: false` skips HTML generation. | [tools.htmlPlugin](https://rsbuild.rs/config/tools/html-plugin) |
| MF output | `output.uniqueName` comes from `package.json#name`; `mf-dev` writes output to disk. | [output.uniqueName](https://rspack.rs/config/output#outputuniquename), [dev.writeToDisk](https://rsbuild.rs/config/dev/write-to-disk) |
## 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](/config/rsbuild/output.md#outputassetprefix) |
| Asset inlining | ESM/CJS disables inlining with a threshold of `0`; other formats inherit Rsbuild's 4 KiB threshold. | [output.dataUriLimit](/config/rsbuild/output.md#outputdataurilimit) |
| `new URL()` | ESM processes static `new URL(..., import.meta.url)` references, emitting original assets with relative output paths. | [new URL imports](/guide/advanced/static-assets.md#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](/guide/advanced/web-workers.md), [module.parser.javascript.worker](https://rspack.rs/config/module-parser#javascriptworker), [output.workerChunkLoading](https://rspack.rs/config/output#outputworkerchunkloading) |
| Wasm | ESM bundle mode uses `compile` to generate loading code; bundleless uses `preserve` to keep imports and copy files. | [wasm.mode](/config/lib/wasm.md#wasmmode) |
## 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](/config/rsbuild/output.md#outputemitcss), [output.injectStyles](/config/rsbuild/output.md#outputinjectstyles) |
| Style references | CSS extraction combines styles and removes JS style imports in bundle mode; bundleless emits per source file and preserves imports. | [bundle](/config/lib/bundle.md), [CSS](/guide/advanced/css.md) |
| CSS Modules | Matches `.module.*`; bundleless emits a JS module with class mappings and a CSS import. | [output.cssModules](/config/rsbuild/output.md#outputcssmodules) |
| 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](/config/lib/redirect.md#redirectstyle), [Assets in CSS](/guide/advanced/static-assets.md#import-assets-in-css-file), [tools.cssLoader](/config/rsbuild/tools.md#toolscssloader) |
| CSS minification | Disabled, leaving final optimization to consumers. | [output.minify](/config/rsbuild/output.md#outputminify) |
## 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](/config/lib/dts.md#dtstypescriptpath), [dts.isolated](/config/lib/dts.md#dtsisolated), [dts.tsgo](/config/lib/dts.md#dtstsgo) |
| Input scope | By default, declaration inputs follow `tsconfig.json`; `rootDir` determines the directory structure. | [source.tsconfigPath](/config/rsbuild/source.md#sourcetsconfigpath) |
| Output directory | Priority: `dts.distPath` → `tsconfig.json#declarationDir` → JS output root. | [dts.distPath](/config/lib/dts.md#dtsdistpath) |
| Bundling | `dts.bundle: false`; when enabled, [API Extractor](https://api-extractor.com/) bundles declarations per entry. | [dts.bundle](/config/lib/dts.md#dtsbundle) |
| 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](https://www.npmjs.com/package/@types/react) by default. | [dts.bundle.bundledPackages](/config/lib/dts.md#dtsbundlebundledpackages), [output.autoExternal](/config/rsbuild/output.md#outputautoexternal), [output.externals](/config/rsbuild/output.md#outputexternals) |
| 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](/config/lib/dts.md#dtsautoextension) |
| 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](/config/lib/redirect.md#redirectdtspath), [redirect.dts.extension](/config/lib/redirect.md#redirectdtsextension) |
| Path aliases | Reads `compilerOptions.paths` from `tsconfig.json` by default. When `dts.alias` is configured, it takes priority for matching aliases. | [dts.alias](/config/lib/dts.md#dtsalias) |
| Type errors | `dts.abortOnError: true` fails the build on declaration generation errors. | [dts.abortOnError](/config/lib/dts.md#dtsabortonerror) |
| Project references | `dts.build: false` skips automatic builds of TypeScript project references. | [dts.build](/config/lib/dts.md#dtsbuild) |
## Build performance and output size
| Feature | Default behavior | Related links |
| ---------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Persistent cache | Enabled by default; disabled by default in Rsbuild. | [performance.buildCache](/config/rsbuild/performance.md#performancebuildcache) |
| File size logs | Bundleless mode prints only the file count and total size. | [performance.printFileSize](/config/rsbuild/performance.md#performanceprintfilesize) |
## 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](/guide/basic/cli.md).
Objects are usually merged recursively and arrays appended, while options such as `resolve.extensions` are replaced. See [Configuration merge rules](https://rsbuild.rs/api/javascript-api/core#merge-rules). When combining configurations with [mergeRslibConfig](/api/javascript-api/core.md#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](https://rsbuild.rs/config/tools/rspack) and check its documentation for usage, while other Rslib and Rsbuild options are listed in the [Configuration overview](/config/index.md).
You can enable [debug mode](/guide/basic/configure-rslib.md#debug-mode) or run [rslib inspect](/guide/basic/cli.md#rslib-inspect) to view the final generated configuration.