---
url: /guide/advanced/css.md
---

# CSS

Rslib provides out-of-the-box support for CSS, including CSS Modules, CSS preprocessors, PostCSS, CSS inlining, Lightning CSS, and CSS compression.

Rslib also provides several configurations to customize CSS file processing.

## Import CSS

You can import CSS files directly in JavaScript files.

```js title="src/index.js"
import './index.css';
```

You should note that the default value of Rslib's [output.target](/config/rsbuild/output.md#outputtarget) is `'node'`. If you need to handle CSS styles, you need to set it to `'web'`.

```ts title="rslib.config.ts"
export default {
  output: {
    target: 'web',
  },
};
```

When [format](/config/lib/format.md) is `'cjs'` or `'esm'`, Rslib will apply different processing methods to CSS based on the [bundle](/config/lib/bundle.md) configuration.

### Bundle mode

In `bundle` mode (default behavior), Rslib will bundle the CSS into a separate file and will not preserve the `import` statement referencing the CSS in the output JavaScript file.

This is a common practice for community library development, which is friendlier to Server-Side Rendering (SSR) and avoids parsing errors caused by loading CSS files in the Node.js environment. Furthermore, for upstream applications using the library, on-demand style importing can be achieved through relevant plugins or configurations, such as Rsbuild's [source.transformImport](https://rsbuild.rs/config/source/transform-import).

If you want to preserve the `import` statement referencing the CSS, you can use the following methods:

1. **Use banner**: Configure [banner.js](/config/lib/banner.md#bannerjs) to add `import './index.css';` to the top of the output JavaScript file.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      banner: {
        js: "import './index.css';",
      },
    },
  ],
};
```

For more complex scenarios, such as when code splitting generates multiple chunk files, you can use Rspack's [BannerPlugin](https://rspack.rs/plugins/webpack/banner-plugin) to precisely control which modules need to add a banner, avoiding adding it to all chunks.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      tools: {
        rspack: {
          plugins: [
            new rspack.BannerPlugin({
              banner: "import './index.css';",
              raw: true,
              test: /^index\.js$/,
            }),
          ],
        },
      },
    },
  ],
};
```

2. **Inline styles**: Enable [output.injectStyles](/config/rsbuild/output.md#outputinjectstyles) to inject CSS directly into the JavaScript runtime.

3. **Use bundleless mode**: Set [bundle](/config/lib/bundle.md) to `false` to preserve the source code file structure and reference relationships.

### Bundleless mode

In `bundleless` mode ([bundle](/config/lib/bundle.md) set to `false`), Rslib will preserve the source code file structure and reference relationships. This means that the `import` statement referencing the CSS will be preserved in the output JavaScript file. This method is friendlier to build tools and facilitates Tree Shaking and on-demand importing of styles.

Here is an example usage, assuming the source code is as follows:


**src/index.ts**

```ts
import './index.css';
export const component = () => {};
```


**src/index.css**

```css
.title {
  color: red;
}
```


Based on the [output structure](/guide/basic/output-structure.md) configuration in the config file, the output will be as follows:


**bundle**


**dist/index.mjs**

```js
const component = () => {};
export { component };
```


**dist/index.css**

```css
.title {
  color: red;
}
```



**bundleless**


**dist/index.mjs**

```js
import './index.css';
const component = () => {};
export { component };
```


**dist/index.css**

```css
.title {
  color: red;
}
```



## CSS Modules

Rslib supports CSS Modules by default without additional configuration. Our convention is to use the `[name].module.css` filename to enable CSS Modules.

The following style files are considered CSS Modules:

- `*.module.css`
- `*.module.less`
- `*.module.sass`
- `*.module.scss`
- `*.module.styl`
- `*.module.stylus`

Read the [CSS Modules](https://rsbuild.rs/guide/styling/css-modules) chapter to understand the complete usage of CSS Modules.

Assuming the source code is as follows:


**src/index.ts**

```tsx
import styles from './index.module.css';

console.log(styles.title);
```


**src/index.module.css**

```css
.title {
  color: red;
}
```


The output will be as follows:


**bundle**


**dist/index.mjs**

```js
const index_module = {
  title: 'title-aQjbKQ',
};
console.log(index_module.title);
```


**dist/index.css**

```css
.title-aQjbKQ {
  color: red;
}
```



**bundleless**


**dist/index.mjs**

```js
import index_module from './index.module.mjs';
console.log(index_module.title);
```


**dist/index.module.mjs**

```js
import './index_module.css';
const index_module = {
  title: 'title-aQjbKQ',
};
export { index_module as default };
```


**dist/index_module.css**

```css
.title-aQjbKQ {
  color: red;
}
```



## CSS preprocessors

Rslib supports popular CSS preprocessors through plugins, including Sass, Less, and Stylus. See how to use them:

- [Sass Plugin](https://rsbuild.rs/plugins/list/plugin-sass)
- [Less Plugin](https://rsbuild.rs/plugins/list/plugin-less)
- [Stylus Plugin](https://rsbuild.rs/plugins/list/plugin-stylus)

Taking the Sass plugin as an example, you can install the plugin via the following command:


```sh [npm]
npm add @rsbuild/plugin-sass -D
```

```sh [yarn]
yarn add @rsbuild/plugin-sass -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-sass -D
```

```sh [bun]
bun add @rsbuild/plugin-sass -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-sass -D
```

Then register the plugin in the `rslib.config.ts` file:

```ts title="rslib.config.ts"
import { pluginSass } from '@rsbuild/plugin-sass';

export default {
  plugins: [pluginSass()],
};
```

After registering the plugin, you can import `*.scss`, `*.sass`, `*.module.scss`, or `*.module.sass` files in your code without adding other configurations.

## PostCSS

Rslib supports transforming CSS code through [PostCSS](https://postcss.org/). You can configure PostCSS in the following ways:

### Configuration file

Rslib uses [postcss-load-config](https://github.com/postcss/postcss-load-config) to load the PostCSS configuration file in the root directory of the current project, such as postcss.config.cjs:

```js title="postcss.config.cjs"
module.exports = {
  plugins: {
    'postcss-px-to-viewport': {
      viewportWidth: 375,
    },
  },
};
```

`postcss-load-config` supports multiple file formats, including but not limited to the following file names:

- postcss.config.js
- postcss.config.mjs
- postcss.config.cjs
- postcss.config.ts
- ...

### tools.postcss

You can also configure the postcss-loader through [tools.postcss](/config/rsbuild/tools.md#toolspostcss) option, which supports modifying the built-in configuration through a function, for example:

```ts title="rslib.config.ts"
export default {
  tools: {
    postcss: (opts) => {
      const viewportPlugin = require('postcss-px-to-viewport')({
        viewportWidth: 375,
      });
      opts.postcssOptions.plugins.push(viewportPlugin);
    },
  },
};
```

### Configuration priority

- When you configure both the `postcss.config.js` file and the `tools.postcss` option, both will take effect, and the `tools.postcss` option will take precedence.
- If there is no `postcss.config.js` file in the project and the `tools.postcss` option is not configured, Rslib will not register `postcss-loader`.

## Tailwind CSS

### Tailwind CSS v4

Rslib has built-in support for PostCSS, and you can integrate [Tailwind CSS v4](https://tailwindcss.com/) in Rslib via PostCSS plugins. Here are the steps to integrate Tailwind CSS v4:

1. Install `tailwindcss` and `@tailwindcss/postcss` packages:


```sh [npm]
npm add tailwindcss @tailwindcss/postcss -D
```

```sh [yarn]
yarn add tailwindcss @tailwindcss/postcss -D
```

```sh [pnpm]
pnpm add tailwindcss @tailwindcss/postcss -D
```

```sh [bun]
bun add tailwindcss @tailwindcss/postcss -D
```

```sh [deno]
deno add npm:tailwindcss npm:@tailwindcss/postcss -D
```

2. Register the Tailwind CSS PostCSS plugin via [postcss.config.mjs](https://npmjs.com/package/postcss-loader#config) or [tools.postcss](/config/rsbuild/tools.md#toolspostcss).

```js title="postcss.config.mjs"
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};
```

3. Add an `@import` to your CSS entry file that imports Tailwind CSS.

```css title="src/index.css"
@import 'tailwindcss';
```

:::tip

Tailwind CSS v4 cannot be used with CSS preprocessors like Sass, Less, or Stylus. You need to place the `@import 'tailwindcss';` statement at the beginning of your `.css` file, see [Tailwind CSS - Compatibility](https://tailwindcss.com/docs/compatibility#sass-less-and-stylus) for more details.

:::

4. Use Tailwind's utility classes in any component or HTML, for example:

```html
<h1 class="text-3xl font-bold underline">Hello world!</h1>
```

For more usage, please refer to the [Tailwind CSS Documentation](https://tailwindcss.com/).

### Tailwind CSS v3

Refer to [Use Tailwind CSS v3](https://rsbuild.rs/guide/styling/tailwindcss-v3).

## Inline CSS files

By default (when [bundle](/config/lib/bundle.md) is `true`), Rslib will extract CSS into a separate `.css` file and output it to the dist directory.

To inline styles into your JS file, set [output.injectStyles](/config/rsbuild/output.md#outputinjectstyles) to `true` to disable CSS extraction logic. When the JS file is requested by the browser, JS dynamically inserts the `<style>` tag into the HTML to load the CSS styles.

```ts title="rslib.config.ts"
export default {
  output: {
    injectStyles: true,
  },
};
```

This will increase the size of your JS Bundle, so it is usually not recommended to disable the CSS extraction.

## Import from node\_modules

Rslib supports importing CSS files from `node_modules`.

- Import in a JS file:

```ts title="src/index.js"
/* Import normalize.css */
/* https://github.com/necolas/normalize.css */
import 'normalize.css';
```

- Import in a CSS file:

```css title="src/index.css"
@import 'normalize.css';

body {
  /* */
}
```

- In Sass and Less files, it is also allowed to add the `~` prefix to resolve style files in `node_modules`. However, this is a **deprecated feature** and it is recommended to remove the `~` prefix from the code.

```scss title="src/index.scss"
@import '~normalize.css';
```

## Query parameters

::: info

Query parameters only take effect when [bundle](/config/lib/bundle.md) is set to `true`.

:::

### inline

Rslib supports importing compiled CSS files as strings in JavaScript by using the `?inline` query parameter.

```js
import inlineCss from './style.css?inline';

console.log(inlineCss); // Compiled CSS content
```

Using `import "*.css?inline"` has the following behaviors:

- Get the compiled text content of the CSS file, processed by Lightning CSS, PostCSS and CSS preprocessors
- The content will be inlined into the final JavaScript bundle
- No separate CSS file will be generated

:::tip

Sass, Less, and Stylus plugins also support the `?inline` query parameter.

:::

### raw

Rslib supports importing raw CSS files as strings in JavaScript by using the `?raw` query parameter.

```ts title="src/index.js"
import rawCss from './style.css?raw';

console.log(rawCss); // Output the raw content of the CSS file
```

Using import `"*.css?raw"` has the following behaviors:

- Get the raw text content of the CSS file, without any preprocessing or compilation
- The content of the CSS file will be inlined into the final JavaScript bundle
- No separate CSS file will be generated

:::tip

Sass, Less, and Stylus plugins also support the `?raw` query parameter.

:::

## Lightning CSS

:::tip

[Lightning CSS](https://lightningcss.dev) is a high-performance CSS parser, transformer and minifier written in Rust. It supports parsing and transforming many modern CSS features into syntax supported by target browsers, and delivers better compression ratios.

:::

Rslib uses Rspack's built-in [lightningcss-loader](https://rspack.rs/guide/features/builtin-lightningcss-loader) to transform CSS code. It automatically reads the [syntax](/config/lib/syntax.md) configuration in the project and converts CSS code to syntax supported by target browsers.

For more information, see [Lightning CSS](https://rsbuild.rs/guide/styling/css-usage#lightning-css).

## CSS minification

Rslib disables CSS minification by default (`output.minify.css` is `false` by default).

If you need to enable CSS minification, you can set `output.minify.css` to `true` via the [output.minify](/config/rsbuild/output.md#outputminify) option. Rslib will enable Rspack's built-in [LightningCssMinimizerRspackPlugin](https://rspack.rs/plugins/rspack/lightning-css-minimizer-rspack-plugin) to minify CSS assets.

:::note

Note that the `output.minify` option you configure will completely override Rslib's default configuration. See the [output.minify](/config/rsbuild/output.md#outputminify) documentation for more details.

:::

Additionally, you can use [@rsbuild/plugin-css-minimizer](https://github.com/rstackjs/rsbuild-plugin-css-minimizer) to customize the CSS minimizer, switching to [cssnano](https://github.com/cssnano/cssnano) or another CSS minimizer.



---
url: /guide/advanced/dts.md
---

# Declaration files

This chapter introduces what [TypeScript Declaration Files](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html) are and how to generate declaration files in Rslib.

## What is declaration files

TypeScript Declaration Files provide type information for JavaScript code. Declaration files typically have a `.d.ts` extension. They allow the TypeScript compiler to understand the type structure of JavaScript code, enabling features like:

1. **Type Checking**: Provide type information for JavaScript code, helping developers catch potential type errors at compile time.
2. **Code Completion**: Enhance code editor features like autocomplete and code navigation.
3. **Documentation Generation**: Generate documentation for JavaScript code, providing better developer experience.
4. **IDE Support**: Improve the developer experience in IDEs like Visual Studio Code, WebStorm, and others.
5. **Library Consumption**: Make it easier for users to use and understand your library.

## What are bundle declaration files and bundleless declaration files

### Bundle declaration files

Bundle declaration files involves bundling multiple TypeScript declaration files into a single declaration file.

- **Pros:**
  - **Simplified Management**: Simplifies the management and referencing of type files.
  - **Easy Distribution**: Reduces the number of files users need to handle when using the library.

- **Cons:**
  - **Complex Generation**: Generating and maintaining a single bundle file can become complex in large projects.
  - **Debugging Challenges**: Debugging type issues may not be as intuitive as with separate files.

### Bundleless declaration files

Bundleless declaration files involves generating a separate declaration file for each module in the library, just like `tsc` does.

- **Pros:**
  - **Modular**: Each module has its own type definitions, making maintenance and debugging easier.
  - **Flexibility**: Suitable for large projects, avoiding the complexity of a single file.

- **Cons:**
  - **Multiple Files**: Users may need to handle multiple declaration files when using the library.
  - **Complex Management**: May require additional configuration to correctly reference all files.

## How to generate declaration files in Rslib

Rslib supports generating declaration files using both the [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) and [tsgo](https://github.com/microsoft/typescript-go), and also supports bundling declaration files with [API Extractor](https://api-extractor.com/).

| Type       | Supported Method                        | Description    |
| ---------- | --------------------------------------- | -------------- |
| bundleless | TypeScript Compiler API                 | Default method |
| bundleless | tsgo                                    |                |
| bundle     | TypeScript Compiler API + API Extractor | Default method |
| bundle     | tsgo + API Extractor                    |                |

### Generate bundleless declaration files

Configure in the Rslib config file:

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      dts: true; // [!code highlight]
      // or
      // [!code highlight:3]
      dts: {
        bundle: false;
      }
    },
  ],
};
```

### Generate bundle declaration files

1. Install `@microsoft/api-extractor` as a development dependency, which is the underlying tool used for bundling declaration files.


```sh [npm]
npm add @microsoft/api-extractor -D
```

```sh [yarn]
yarn add @microsoft/api-extractor -D
```

```sh [pnpm]
pnpm add @microsoft/api-extractor -D
```

```sh [bun]
bun add @microsoft/api-extractor -D
```

```sh [deno]
deno add npm:@microsoft/api-extractor -D
```

2. Configure in the Rslib config file:

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      // [!code highlight:3]
      dts: {
        bundle: true;
      }
    },
  ],
};
```

### Generate declaration files with tsgo

::: tip

This feature is currently an **experimental feature**. Since tsgo is still in the **experimental stage**, there may be some bugs and unresolved issues or limitations. So, make sure to fully test it in your project before enabling this option.

:::

1. Install `@typescript/native-preview` as a development dependency:


```sh [npm]
npm add @typescript/native-preview -D
```

```sh [yarn]
yarn add @typescript/native-preview -D
```

```sh [pnpm]
pnpm add @typescript/native-preview -D
```

```sh [bun]
bun add @typescript/native-preview -D
```

```sh [deno]
deno add npm:@typescript/native-preview -D
```

::: tip Version requirements

`@typescript/native-preview` requires Node.js 20.6.0 or higher.

:::

2. Configure in the Rslib config file:

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      dts: {
        tsgo: true, // [!code highlight]
      },
    },
  ],
};
```

3. In order to ensure the consistency of local development, you need to install the corresponding [VS Code Preview Extension](https://marketplace.visualstudio.com/items?itemName=TypeScriptTeam.native-preview) and add the following configuration in the VS Code settings:

```json title=".vscode/settings.json"
{
  "typescript.experimental.useTsgo": true
}
```

### Notes

During the generation of declaration files, Rslib will automatically enforce some configuration options in `tsconfig.json` to ensure that the [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) or [tsgo](https://github.com/microsoft/typescript-go) generates only declaration files.

```json
{
  "compilerOptions": {
    "noEmit": false,
    "declaration": true,
    "emitDeclarationOnly": true
  }
}
```

The priority from highest to lowest of final output directory of declaration files:

- The configuration option [dts.distPath](/config/lib/dts.md#dtsdistpath)
- The configuration option `declarationDir` in `tsconfig.json`
- The configuration option [output.distPath](/config/rsbuild/output.md#outputdistpath) or [output.distPath.root](/config/rsbuild/output.md#outputdistpath)

## Related configuration of declaration files

| Configuration item                                                     | Description                                                                                                            |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [dts.bundle](/config/lib/dts.md#dtsbundle)                             | Whether to bundle the declaration files.                                                                               |
| [dts.distPath](/config/lib/dts.md#dtsdistpath)                         | The output directory of declaration files.                                                                             |
| [dts.build](/config/lib/dts.md#dtsbuild)                               | Whether to generate declaration files with building the project references.                                            |
| [dts.abortOnError](/config/lib/dts.md#dtsabortonerror)                 | Whether to abort the build process when an error occurs during declaration files generation.                           |
| [dts.autoExtension](/config/lib/dts.md#dtsautoextension)               | Whether to automatically set the declaration file extension based on the [format](/config/lib/format.md) option.       |
| [dts.alias](/config/lib/dts.md#dtsalias)                               | The path alias of the declaration files.                                                                               |
| [dts.tsgo](/config/lib/dts.md#dtstsgo)                                 | Whether to generate declaration files with [tsgo](https://github.com/microsoft/TypeScript/pull/48729).                 |
| [banner.dts](/config/lib/banner.md#bannerdts)                          | Inject content into the top of each declaration output file.                                                           |
| [footer.dts](/config/lib/footer.md#footerdts)                          | Inject content into the bottom of each declaration file.                                                               |
| [redirect.dts.path](/config/lib/redirect.md#redirectdtspath)           | Whether to automatically redirect the import paths of TypeScript declaration output files.                             |
| [redirect.dts.extension](/config/lib/redirect.md#redirectdtsextension) | Whether to automatically redirect the file extension to import paths based on the TypeScript declaration output files. |



---
url: /guide/advanced/json-files.md
---

# JSON

Rslib supports importing JSON files in code, and also supports importing [YAML](https://yaml.org/) and [TOML](https://toml.io/en/) files and converting them to JSON format.

## JSON file

You can directly import JSON files in JavaScript files.

:::warning

In bundle mode, JSON files support both default and named import.

In bundleless mode, JSON files only support named import.

:::

### Default import

```json title="example.json"
{
  "name": "foo",
  "items": [1, 2]
}
```

```js title="index.js"
import example from './example.json';

console.log(example.name); // 'foo';
console.log(example.items); // [1, 2];
```

### Named import

Rslib also supports importing JSON files through named import.

Here is an example, assuming the source code is as follows:


**src/index.ts**

```js
import { name } from './example.json';

console.log(name); // 'foo';
```


**src/example.json**

```json
{
  "name": "foo",
  "items": [1, 2]
}
```


Based on the configuration in the [output structure](/guide/basic/output-structure.md) specified in the configuration file, the following outputs will be emitted:


**bundle**


**dist/index.js**

```tsx
var example_namespaceObject = {
  u: 'foo',
};
console.log(example_namespaceObject.u);
```



**bundleless**


**dist/index.js**

```tsx
import * as example from './example.js';

console.log(example.name);
```


**dist/example.js**

```tsx
var example_namespaceObject = JSON.parse('{"name":"foo","items":[1,2]}');
var __webpack_exports__items = example_namespaceObject.items;
var __webpack_exports__name = example_namespaceObject.name;
export { __webpack_exports__items as items, __webpack_exports__name as name };
```



### Use import attributes

In bundle mode, Rslib supports [import attributes](https://github.com/tc39/proposal-import-attributes), and you can import JSON files through import attributes:

```js title="index.js"
import json from './example.json' with { type: 'json' };
```

In bundleless mode, when importing JSON files through import attributes, you need to ensure that references to the JSON files are preserved in the output, refer to [document](#bundleless) for configuration.

## YAML file

[YAML](https://yaml.org/) is a data serialization language commonly used for writing configuration files.

By adding the [@rsbuild/plugin-yaml](https://github.com/rstackjs/rsbuild-plugin-yaml) plugin, you can import `.yaml` or `.yml` files in JavaScript and they will be automatically converted to JavaScript objects.


```sh [npm]
npm add @rsbuild/plugin-yaml -D
```

```sh [yarn]
yarn add @rsbuild/plugin-yaml -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-yaml -D
```

```sh [bun]
bun add @rsbuild/plugin-yaml -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-yaml -D
```

### Register plugin

You can register the plugin in the `rslib.config.ts` file:

```ts title="rslib.config.ts"
import { pluginYaml } from '@rsbuild/plugin-yaml';

export default {
  plugins: [pluginYaml()],
};
```

### Example


**src/index.ts**

```ts
import example from './example.yaml';

console.log(example.hello); // 'world';
console.log(example.foo); // { bar: 'baz' };
```


**src/example.yaml**

```yaml
hello: world
foo:
  bar: baz
```


## TOML file

[TOML](https://toml.io/) is a semantically explicit, easy-to-read configuration file format.

By adding the [@rsbuild/plugin-toml](https://github.com/rstackjs/rsbuild-plugin-toml) plugin, you can import `.toml` files in JavaScript and it will be automatically converted to JavaScript objects.


```sh [npm]
npm add @rsbuild/plugin-toml -D
```

```sh [yarn]
yarn add @rsbuild/plugin-toml -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-toml -D
```

```sh [bun]
bun add @rsbuild/plugin-toml -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-toml -D
```

### Register plugin

You can register the plugin in the `rslib.config.ts` file:

```ts title="rslib.config.ts"
import { pluginToml } from '@rsbuild/plugin-toml';

export default {
  plugins: [pluginToml()],
};
```

### Example


**src/index.ts**

```ts
import example from './example.toml';

console.log(example.hello); // 'world';
console.log(example.foo); // { bar: 'baz' };
```


**src/example.toml**

```toml
hello = "world"

[foo]
bar = "baz"
```


## Type declaration

When you import YAML or TOML files in TypeScript code, please create a `src/env.d.ts` file in your project and add the corresponding type declarations.

- Method 1: If the `@rslib/core` package is installed, you can reference the [preset types](/guide/basic/typescript.md#preset-types) provided by `@rslib/core`:

```ts title="src/env.d.ts"
/// <reference types="@rslib/core/types" />
```

- Method 2: Manually add the required type declarations:

```ts title="src/env.d.ts"
declare module '*.yaml' {
  const content: Record<string, any>;
  export default content;
}
declare module '*.yml' {
  const content: Record<string, any>;
  export default content;
}
declare module '*.toml' {
  const content: Record<string, any>;
  export default content;
}
```

## Bundle mode and output

Rslib supports outputting JSON / YAML / TOML files in different forms under different bundle modes.

### bundle

In bundle mode ([`bundle: true`](/config/lib/bundle.md)), JSON files will be directly bundled into JavaScript output, and unused keys in JSON files will be tree-shaken. The same applies to TOML and YAML files.

### bundleless

In bundleless mode ([`bundle: false`](/config/lib/bundle.md)), each JSON / YAML / TOML file will be converted into a corresponding JavaScript output file. JSON files will be converted to `JSON.parse` form and exported, while YAML and TOML files will be converted to JavaScript objects and exported.

If you want JSON / YAML / TOML files to be output to the distribution directory as-is, and keep the reference paths to these files in the output JavaScript files, you can achieve this through the following steps:

1. Exclude JSON / YAML / TOML files from the [bundleless](/config/rsbuild/source.md#sourceentry) entry file glob pattern.
2. Reserve request paths for JSON / YAML / TOML files in [output.externals](/config/rsbuild/output.md#outputexternals).
3. Add [output.copy](/config/rsbuild/output.md#outputcopy) option to the output configuration, specifying the output path for JSON / YAML / TOML files.

For example, the following configuration will output all JSON files in the `src` directory as-is:

```ts title="rslib.config.ts"
export default defineConfig({
  lib: [
    {
      bundle: false,
      source: {
        entry: {
          index: ['./src/**', '!./src/**/*.json'], // [!code highlight]
        },
      },
      output: {
        // [!code highlight:2]
        copy: [{ from: './**/*.json', context: './src' }],
        externals: [/.*\.json$/],
      },
    },
  ],
});
```



---
url: /guide/advanced/module-federation.md
---

# Module Federation

This chapter introduces how to build [Module Federation](/guide/basic/output-format.md#mf) output in Rslib.

## Usage scenarios

Module federation has some typical usage scenarios, including:

- Allows independent applications (called "Micro-Frontend" in the Micro-Frontend architecture) to share modules without having to recompile the entire application.
- Different teams work on different parts of the same application without having to recompile the entire application.
- Dynamic code loading and sharing between applications at runtime.

Module Federation can help you:

- Reduce code duplication
- Improve code maintainability
- Reduce the overall size of the application
- Improve application performance

## Quick start

First install the [Module Federation Rsbuild Plugin](https://www.npmjs.com/package/@module-federation/rsbuild-plugin).


```sh [npm]
npm add @module-federation/rsbuild-plugin -D
```

```sh [yarn]
yarn add @module-federation/rsbuild-plugin -D
```

```sh [pnpm]
pnpm add @module-federation/rsbuild-plugin -D
```

```sh [bun]
bun add @module-federation/rsbuild-plugin -D
```

```sh [deno]
deno add npm:@module-federation/rsbuild-plugin -D
```

Then register the plugin in the `rslib.config.ts` file:

```ts title="rslib.config.ts" twoslash
import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    // ... other format
    // [!code highlight:33]
    {
      format: 'mf',
      output: {
        distPath: './dist/mf',
        // for production, add online assetPrefix here
        assetPrefix: 'http://localhost:3001/mf',
      },
      // for Storybook to dev
      dev: {
        assetPrefix: 'http://localhost:3001/mf',
      },
      plugins: [
        pluginModuleFederation(
          {
            name: 'rslib_provider',
            exposes: {
              // add expose here
            },
            // can not add 'remote' here, because you may build 'esm' or 'cjs' assets in one build.
            // if you want the Rslib package use remote module, please see below.
            shared: {
              react: {
                singleton: true,
              },
              'react-dom': {
                singleton: true,
              },
            },
          },
          {},
        ),
      ],
    },
  ],
  // for Storybook to dev
  server: {
    port: 3001,
  },
  output: {
    target: 'web',
  },
  plugins: [pluginReact()],
});
```

In this way, we have completed the integration of Rslib Module as a producer. After the construction is completed, we can see that the mf directory has been added to the product, and consumers can directly consume this package.

In the above example we added a new `format: 'mf'` , which will help you add an additional Module Federation product, while also configuring the format of `cjs` and `esm` , which does not conflict.

However, if you want this Rslib Module to consume other producers at the same time, do not use the build configuration `remote` parameter, because in other formats, this may cause errors, please refer to the example below using the Module Federation runtime.

## Develop MF remote module

### Use host app

Rslib support developing Module Federation Rslib project with a host application.

#### 1. Start `rslib mf-dev` command of library

Adding the `dev` command to the `package.json` file:

```json title="package.json"
{
  "scripts": {
    "dev": "rslib mf-dev"
  }
}
```

Then run the `dev` command can start the Module Federation development mode,
enabling consumption by your host app, along
with Hot Module Replacement (HMR).


```sh [npm]
npm run dev
```

```sh [yarn]
yarn run dev
```

```sh [pnpm]
pnpm run dev
```

```sh [bun]
bun run dev
```

```sh [deno]
deno run npm:dev
```

#### 2. Start host app

Set up the host app to consume the Rslib Module Federation library. Check out the [@module-federation/rsbuild-plugin
](https://www.npmjs.com/package/@module-federation/rsbuild-plugin) for more information.

```ts title="rsbuild.config.ts" twoslash
import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  plugins: [
    pluginReact(),
    // [!code highlight:17]
    pluginModuleFederation(
      {
        name: 'rsbuild_host',
        remotes: {
          rslib: 'rslib@http://localhost:3001/mf/mf-manifest.json',
        },
        shared: {
          react: {
            singleton: true,
          },
          'react-dom': {
            singleton: true,
          },
        },
        // Enable this when the output of Rslib is build under 'production' mode, while the host app is 'development'.
        // Reference: https://rslib.rs/guide/advanced/module-federation#faqs
        shareStrategy: 'loaded-first',
      },
      {},
    ),
  ],
});
```

Then start the host app with `rsbuild dev`.

### Use Storybook

Rslib support developing Module Federation Rslib project with Storybook.

#### 1. Start `rslib mf-dev` command of library

Adding the `dev` command to the `package.json` file:

```json title="package.json"
{
  "scripts": {
    "dev": "rslib mf-dev"
  }
}
```

Then run the `dev` command can start the Module Federation development mode, enabling consumption by Storybook, along with Hot Module Replacement (HMR).


```sh [npm]
npm run dev
```

```sh [yarn]
yarn run dev
```

```sh [pnpm]
pnpm run dev
```

```sh [bun]
bun run dev
```

```sh [deno]
deno run npm:dev
```

#### 2. Set up Storybook configuration

First, set up Storybook with the Rslib project. You can refer to the [Storybook chapter](/guide/advanced/storybook.md) to learn how to do this. In this chapter, we will use React as the framework for our example.

1. Install the following Storybook addons to let Storybook work with Rslib Module Federation:

   - [storybook-addon-rslib](https://www.npmjs.com/package/storybook-addon-rslib): Storybook addon that lets Storybook load the Rslib config.
   - [@module-federation/storybook-addon](https://www.npmjs.com/package/@module-federation/rsbuild-plugin): Storybook addon that sets up the Module Federation config for Storybook.

   <PackageManagerTabs command="add storybook-addon-rslib @module-federation/storybook-addon -D" />

2. Then set up the Storybook configuration file `.storybook/main.ts`, specify the stories and addons, and set the framework with corresponding framework integration.

   ```ts title=".storybook/main.ts"
   import { dirname, join } from 'node:path';
   import type { StorybookConfig } from 'storybook-react-rsbuild';

   function getAbsolutePath(value: string): any {
     return dirname(require.resolve(join(value, 'package.json')));
   }

   const config: StorybookConfig = {
     stories: [
       '../stories/**/*.mdx',
       '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)',
     ],
     framework: {
       name: getAbsolutePath('storybook-react-rsbuild'),
       options: {},
     },
     addons: [
       // [!code highlight:21]
       {
         name: getAbsolutePath('storybook-addon-rslib'),
         options: {
           rslib: {
             include: ['**/stories/**'],
           },
         },
       },
       {
         name: '@module-federation/storybook-addon/preset',
         options: {
           // add your rslib module manifest here for storybook dev
           // we have set dev.assetPrefix and server.port to 3001 in rslib.config.ts above
           remotes: {
             'rslib-module':
               // you can also add shared here for storybook app
               // shared: {}
               'rslib-module@http://localhost:3001/mf/mf-manifest.json',
           },
         },
       },
     ],
   };

   export default config;
   ```

#### 3. Writing stories with remote module

Import components from remote module.

```ts title="stories/index.stories.tsx"
import React from 'react';
// [!code highlight:2]
// Load your remote module here, Storybook will act as the host app.
import { Counter } from 'rslib-module';

const Component = () => <Counter />;

export default {
  title: 'App Component',
  component: Component,
};

export const Primary = {};
```

#### 4. Add Module Federation types and stories into `tsconfig.json`.

```json title="tsconfig.json"
{
  "compilerOptions": {
    // ...
    "paths": {
      "*": ["./@mf-types/*"]
    }
  },
  "include": ["src/**/*", ".storybook/**/*", "stories/**/*"]
}
```

#### 5. Start Storybook app

There you go, start Storybook with `npx storybook dev`.

## Consume other Module Federation modules

Because there are multiple formats in Rslib, if you configure the `remote` parameter to consume other modules during construction, it may not work properly in all formats. It is recommended to access through the [Module Federation Runtime](https://module-federation.io/guide/basic/runtime.html)

First install the runtime dependencies


```sh [npm]
npm add @module-federation/enhanced -D
```

```sh [yarn]
yarn add @module-federation/enhanced -D
```

```sh [pnpm]
pnpm add @module-federation/enhanced -D
```

```sh [bun]
bun add @module-federation/enhanced -D
```

```sh [deno]
deno add npm:@module-federation/enhanced -D
```

Then consume other Module Federation modules at runtime, for example

```ts
import { init, loadRemote } from '@module-federation/enhanced/runtime';
import { Suspense, createElement, lazy } from 'react';

init({
  name: 'rslib_provider',
  remotes: [
    {
      name: 'mf_remote',
      entry: 'http://localhost:3002/mf-manifest.json',
    },
  ],
});

export const Counter: React.FC = () => {
  return (
    <div>
      <Suspense fallback={<div>loading</div>}>
        {createElement(
          lazy(
            () =>
              loadRemote('mf_remote') as Promise<{
                default: React.FC;
              }>,
          ),
        )}
      </Suspense>
    </div>
  );
};
```

This ensures that modules can be loaded as expected in multiple formats.

## FAQs

### How to control the loading strategy of shared dependencies when the producer and consumer build patterns are different

If the Rslib producer is built with build, this means that the `process.env.NODE_ENV` of the producer is `production` . If the consumer is started in dev mode at this time,
due to the shared loading strategy of Module Federation being `version-first` by default, there may be problems loading into different modes of react and react-dom (e.g. react in development mode, react-dom in production mode).
You can set up [shareStrategy](https://module-federation.io/configure/sharestrategy) at the consumer to solve this problem, but make sure you fully understand this configuration

```ts
pluginModuleFederation({
  // ...
  shareStrategy: 'loaded-first',
}, {}),
```

### How to make module federated outputs generate export of ES modules

If you want Rslib producers' module federated outputs to generate the export of ES Modules, you can additionally configure as follows:

```ts title="rslib.config.ts"
export default defineConfig({
  lib: [
    {
      format: 'mf',
      // ...
      // [!code highlight:7]
      tools: {
        rspack(config) {
          config.experiments = {
            outputModule: true,
          };
        },
      },
    },
  ],
});
```

## Examples

You can refer to the example projects in [Rslib Module Federation Example](https://github.com/rstackjs/rstack-examples/tree/main/rslib/module-federation).

- `mf-host`: Rsbuild App Consumer
- `mf-react-component`: Rslib Module, which is both a producer and a consumer, provides the module to the `mf-host` as a producer, and consumes the `mf-remote`
- `mf-remote`: Rsbuild App Producer



---
url: /guide/advanced/output-compatibility.md
---

# Output compatibility

This chapter introduces how to specify which target environment should be supported.

## Syntax downgrade

In Rslib, you can configure the syntax to which JavaScript and CSS will be downgraded by setting [lib.syntax](/config/lib/syntax.md). This configuration supports setting the ECMAScript version directly, such as `es2015`, `es2022`, etc., and also supports setting the query syntax of [Browserslist](https://browsersl.ist/), such as `last 2 versions`, `> 1%`, `node >= 16`, `chrome >= 80`, etc.

By default, the syntax is set to `ESNext`, which will only supports only the latest version of mainstream browsers (Chrome / Firefox / Edge / macOS Safari / iOS Safari) or Node.js according to [output.target](/config/rsbuild/output.md#outputtarget).

It should be noted that Rslib does not read the Browserslist related configuration files (such as `.browserslistrc` or the `browserslist` field in `package.json`). You can override by setting [output.overrideBrowserslist](/config/rsbuild/output.md#outputoverridebrowserslist) which has a higher priority than [lib.syntax](/config/lib/syntax.md).

## Polyfill

Before dealing with compatibility issues, it is recommended that you understand the following background knowledge to better handle related issues. Check out the background knowledge on [syntax transpilation and API polyfill](https://rsbuild.rs/guide/advanced/browser-compatibility#syntax-downgrade-and-api-downgrade).

### Browser

Normally, we don't need to inject polyfill for npm packages, this step should be done on the web application framework side, but in some scenarios we need to inject polyfill in order to make our library run directly in low version browsers.

Note that this plugin does not transform your code syntax, it only injects polyfill for unsupported functions used in your code, importing them as normal functions instead of polluting the global. You need to install the [core-js-pure](https://www.npmjs.com/package/core-js-pure) dependency.

#### Set up

The polyfill relies on Babel to inject the polyfill code, so you need to install the [Rsbuild Babel plugin](https://rsbuild.rs/plugins/list/plugin-babel) and [babel-plugin-polyfill-corejs3](https://www.npmjs.com/package/babel-plugin-polyfill-corejs3) to inject the polyfill code.


```sh [npm]
npm add @rsbuild/plugin-babel babel-plugin-polyfill-corejs3 -D
```

```sh [yarn]
yarn add @rsbuild/plugin-babel babel-plugin-polyfill-corejs3 -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-babel babel-plugin-polyfill-corejs3 -D
```

```sh [bun]
bun add @rsbuild/plugin-babel babel-plugin-polyfill-corejs3 -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-babel npm:babel-plugin-polyfill-corejs3 -D
```

And install [core-js-pure](https://www.npmjs.com/package/core-js-pure) as the runtime relied code.


```sh [npm]
npm add core-js-pure
```

```sh [yarn]
yarn add core-js-pure
```

```sh [pnpm]
pnpm add core-js-pure
```

```sh [bun]
bun add core-js-pure
```

```sh [deno]
deno add npm:core-js-pure
```

Configure the Babel plugin with polyfill options, set the [targets](https://babeljs.io/docs/options#targets) field to specify the target browser version.

```ts title="rslib.config.ts"
import { pluginBabel } from '@rsbuild/plugin-babel'; // [!code highlight]
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
    },
  ],
  plugins: [
    // [!code highlight:14]
    pluginBabel({
      babelLoaderOptions: {
        plugins: [
          [
            require('babel-plugin-polyfill-corejs3'),
            {
              method: 'usage-pure',
              targets: { ie: '10' },
              version: '3.29',
            },
          ],
        ],
      },
    }),
  ],
});
```

#### Configurations

Check out [babel-plugin-polyfill-corejs3](https://www.npmjs.com/package/babel-plugin-polyfill-corejs3) documentation for more details.

### Node.js

:::tip About Node Polyfill
Normally, we don't need to use Node libs on the browser side. However, it is possible to use some Node libs when the code will run on both the Node side and the browser side, and Node Polyfill provides browser versions of polyfills for these Node libs.
:::

By using [@rsbuild/plugin-node-polyfill](https://github.com/rstackjs/rsbuild-plugin-node-polyfill), Node core libs polyfills are automatically injected into the browser-side, allowing you to use these modules on the browser side with confidence.

#### Set up

Rslib uses [@rsbuild/plugin-node-polyfill](https://github.com/rstackjs/rsbuild-plugin-node-polyfill) to provide the Node Polyfill feature.


```sh [npm]
npm add @rsbuild/plugin-node-polyfill -D
```

```sh [yarn]
yarn add @rsbuild/plugin-node-polyfill -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-node-polyfill -D
```

```sh [bun]
bun add @rsbuild/plugin-node-polyfill -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-node-polyfill -D
```

Then add the plugin into the plugins field.

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
import { pluginNodePolyfill } from '@rsbuild/plugin-node-polyfill';

export default defineConfig({
  lib: [{ format: 'esm' }],
  plugins: [pluginNodePolyfill()],
});
```

#### Configurations

- For projects with `bundle` enabled, the Node Polyfill will be injected and included in the output.
- For projects with `bundle` disabled, polyfills are not injected into the output by default. To avoid inlining the polyfill in every module, the modules are externalized and need to be added to dependencies manually, follow these steps:

  1. Configure `output.external` with `resolvedPolyfillToModules`, which you can import from [@rsbuild/plugin-node-polyfill](https://github.com/rstackjs/rsbuild-plugin-node-polyfill). This will externalize the polyfill modules to the installed polyfill dependencies.
  2. Install used polyfill modules as dependencies.

  With the above steps, every usage of the polyfill module will be replaced by the corresponding module in the `externals` field. Checkout the <SourceCode href="https://github.com/web-infra-dev/rslib/blob/main/tests/integration/node-polyfill/bundle-false/rslib.config.ts" /> of the example for more details.

Check out the documentation of [@rsbuild/plugin-node-polyfill](https://github.com/rstackjs/rsbuild-plugin-node-polyfill), all the configurations are applicable for Rslib.



---
url: /guide/advanced/rsdoctor.md
---

# Use Rsdoctor

[Rsdoctor](https://rsdoctor.rs/) is a build analyzer tailored for the Rspack ecosystem.

Rsdoctor aims to be a one-stop, intelligent build analyzer that makes the build process transparent, predictable, and optimizable through visualization and smart analysis, helping teams pinpoint bottlenecks, improve performance, and raise engineering quality.

Use Rsdoctor to debug build outputs or the build process.

## Quick start

In an Rslib project, enable Rsdoctor as follows:

1. Install the Rsdoctor plugin:


```sh [npm]
npm add @rsdoctor/rspack-plugin -D
```

```sh [yarn]
yarn add @rsdoctor/rspack-plugin -D
```

```sh [pnpm]
pnpm add @rsdoctor/rspack-plugin -D
```

```sh [bun]
bun add @rsdoctor/rspack-plugin -D
```

```sh [deno]
deno add npm:@rsdoctor/rspack-plugin -D
```

2. Set the `RSDOCTOR=true` environment variable before running the CLI command:

```json title="package.json"
{
  "scripts": {
    "build:rsdoctor": "RSDOCTOR=true rslib build"
  }
}
```

Because Windows does not support this syntax, you can use [cross-env](https://npmjs.com/package/cross-env) to set environment variables across different systems:

```json title="package.json"
{
  "scripts": {
    "build:rsdoctor": "cross-env RSDOCTOR=true rslib build"
  },
  "devDependencies": {
    "cross-env": "^7.0.0"
  }
}
```

After running these scripts, Rslib automatically registers the Rsdoctor plugin and opens the build analysis page when the build finishes. See the [Rsdoctor documentation](https://rsdoctor.rs/) for all features.

## Options

To configure the [options](https://rsdoctor.rs/config/options/options) exposed by the Rsdoctor plugin, manually register the plugin:

```ts title="rslib.config.ts"
import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    // ...lib configuration
  ],
  tools: {
    rspack: {
      plugins: [
        process.env.RSDOCTOR === 'true' &&
          new RsdoctorRspackPlugin({
            // plugin options
          }),
      ],
    },
  },
});
```



---
url: /guide/advanced/rspress.md
---

# Use Rspress

[Rspress](https://rspress.rs/) is a Rspack-based static site generator, ideal for building demos and API docs for component libraries. With [plugin-preview](https://rspress.rs/plugin/official-plugins/preview) and [plugin-api-docgen](https://rspress.rs/plugin/official-plugins/api-docgen), you can reuse Rslib sources and typings to preview components and view APIs in one site.

## New project

:::info
When using `create-rslib`, choose the React + TypeScript template and enable the extra tool **“Rspress - documentation”** to auto-generate docs folder, scripts, and Rspress config—no manual setup needed.
:::

Run `npm create rslib@latest` and select Rspress to get the following structure:

```tree
├── docs
│   └── index.mdx
├── src
│   └── Button.tsx
├── package.json
├── tsconfig.json
├── rslib.config.ts
└── rspress.config.ts
```

The template includes [rsbuild-plugin-workspace-dev](https://github.com/rstackjs/rsbuild-plugin-workspace-dev), which will run Rslib watch while the Rspress dev server is running.

Run `npm run doc` to start the Rspress dev server and preview your Rslib components:

```json title="package.json"
{
  "scripts": {
    "dev": "rslib build --watch",
    "doc": "rspress dev" // run this, it also runs the dev script
  }
}
```

## Existing project

If you are using Rslib to build a component library, follow these steps to add Rspress documentation support.

### Install deps

```sh [npm]
npm add @rspress/core @rspress/plugin-api-docgen @rspress/plugin-preview rsbuild-plugin-workspace-dev -D
```

```sh [yarn]
yarn add @rspress/core @rspress/plugin-api-docgen @rspress/plugin-preview rsbuild-plugin-workspace-dev -D
```

```sh [pnpm]
pnpm add @rspress/core @rspress/plugin-api-docgen @rspress/plugin-preview rsbuild-plugin-workspace-dev -D
```

```sh [bun]
bun add @rspress/core @rspress/plugin-api-docgen @rspress/plugin-preview rsbuild-plugin-workspace-dev -D
```

```sh [deno]
deno add npm:@rspress/core npm:@rspress/plugin-api-docgen npm:@rspress/plugin-preview npm:rsbuild-plugin-workspace-dev -D
```
### Add scripts in `package.json`
```json title="package.json"
{
  "name": "@your-scope/your-package",
  "version": "0.1.0",
  "scripts": {
    "dev": "rslib build --watch",
    "build": "rslib build",
    "doc": "rspress dev", // [!code highlight]
    "doc:build": "rspress build", // [!code highlight]
    "doc:preview": "rspress preview" // [!code highlight]
  }
}
```
### Create `rspress.config.ts`
Add preview-related plugins like [plugin-preview](https://rspress.rs/plugin/official-plugins/preview) and [plugin-api-docgen](https://rspress.rs/plugin/official-plugins/api-docgen).
```ts title="rspress.config.ts"
import * as path from 'node:path';
import { defineConfig } from '@rspress/core';
import { pluginApiDocgen } from '@rspress/plugin-api-docgen';
import { pluginPreview } from '@rspress/plugin-preview';
import { pluginWorkspaceDev } from 'rsbuild-plugin-workspace-dev';

export default defineConfig({
  root: path.join(__dirname, 'docs'),
  title: 'Component Library Docs',
  lang: 'en',
  builderConfig: {
    plugins: [
      pluginWorkspaceDev({
        startCurrent: true, // run current package dev/watch when docs start
      }),
    ],
  },
  plugins: [
    pluginApiDocgen({
      entries: {
        Button: './src/Button.tsx',
      },
      apiParseTool: 'react-docgen-typescript',
    }),
    pluginPreview(),
  ],
});
```
### Import built output by package name
Set `paths` in `tsconfig.json` to point to your package, or declare your package as a dependency via `"workspace:*"` in `package.json`, so `plugin-preview` resolves demos from the built artifact.
```json title="tsconfig.json"
{
  "compilerOptions": {
    "paths": {
      // [!code highlight:1]
      "@your-scope/your-package": ["."]
    }
  },
  "include": ["src", "docs", "rspress.config.ts", "rslib.config.ts"]
}
```
:::tip
In [plugin-preview](https://rspress.rs/plugin/official-plugins/preview), we recommend importing component outputs by package name rather than relative paths. This keeps the preview environment consistent with how users consume the library.
If your project uses the `exports` field, we recommend `"workspace:*"` instead:
```json title="package.json"
{
  "name": "@your-scope/your-package",
  "version": "0.1.0",
  "dependencies": {
    // [!code highlight:1]
    "@your-scope/your-package": "workspace:*"
  }
}
```
This approach avoids changes to `tsconfig.json` and supports multi-entry exports.
:::
### Example
Add docs under `docs/` (see the template’s `docs/Button.mdx`):
````mdx title="docs/Button.mdx"
# Button

## Size

```jsx preview
import { Button } from '@your-scope/your-package';

export default () => <Button size="medium" label="Click me" />;
```

## Background

```jsx preview
import { Button } from '@your-scope/your-package';

export default () => <Button backgroundColor="red" label="Red" />;
```

## API

<API moduleName="Button" />
````

## References

- [Rspress docs & plugins](https://rspress.rs/)
- [`rsbuild-plugin-workspace-dev`](https://www.npmjs.com/package/rsbuild-plugin-workspace-dev)
- [`@rspress/plugin-api-docgen`](https://rspress.rs/plugin/official-plugins/api-docgen)
- [`@rspress/plugin-preview`](https://rspress.rs/plugin/official-plugins/preview)



---
url: /guide/advanced/rstest.md
---

# Use Rstest

[Rstest](https://rstest.rs) is a test framework based on Rspack that provides comprehensive, first-class support for the Rspack ecosystem, you can use the same set of configurations for both development and testing.

Using Rstest will bring a seamless testing experience to your Rslib project.

## Quick start

### New project

You can use Rslib to create a new Rslib + Rstest project. Just add the `--tools rstest` flag when creating the project:

```bash
npx create-rslib --dir my-project --template react-ts --tools rstest
```

### Existing project

To add Rstest to an existing Rslib project, simply install the `@rstest/core` package as a development dependency and add the Rstest command to the npm scripts in your package.json:


```sh [npm]
npm add -D @rstest/core
```

```sh [yarn]
yarn add -D @rstest/core
```

```sh [pnpm]
pnpm add -D @rstest/core
```

```sh [bun]
bun add -D @rstest/core
```

```sh [deno]
deno add -D npm:@rstest/core
```

```json title="package.json"
{
  "scripts": {
    "test": "rstest"
  }
}
```

After completing the above steps, you can create test files in your project, write tests using the Rstest API, and run the tests with the `npm test` command.

For example, create a `sum.test.ts` file with the following content:

```ts title="test/sum.test.ts"
import { test, expect } from '@rstest/core';
import { sum } from '../src/sum';

test('sum', () => {
  expect(sum(1, 2)).toBe(3);
});
```

Now, you can run the `npm test` command to execute the tests. Rstest will output the following:

```
 ✓ test/sum.test.ts (1)

 Test Files 1 passed
      Tests 1 passed
   Duration 71ms (build 20ms, tests 51ms)
```

## Configuring Rstest

Rstest provides various configuration options that can be set by creating an `rstest.config.ts` file in the root of your project. Here is an example configuration file:

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';

export default defineConfig({
  include: ['test/**/*.test.ts'],
  testEnvironment: 'node',
});
```

In the configuration file, you can specify test file matching patterns, set the test environment, configure code coverage, etc. For detailed information on all available configuration options, please refer to the [Rstest documentation](https://rstest.rs/config).

## Reusing Rslib configuration

`@rstest/adapter-rslib` is the official adapter provided by Rstest that allows Rstest to automatically inherit the configuration from your existing Rslib configuration file. This ensures that the test environment is consistent with the build configuration, avoiding duplicate configuration.

```ts title="rstest.config.ts"
import { defineConfig } from '@rstest/core';
import { withRslibConfig } from '@rstest/adapter-rslib';

export default defineConfig({
  extends: withRslibConfig(),
  // Additional rstest-specific configuration
});
```

For more information about the `withRslibConfig` function, please refer to the [Rstest documentation](https://rstest.rs/guide/integration/rslib#reusing-rslib-configuration).



---
url: /guide/advanced/static-assets.md
---

# Static assets

Rslib supports import static assets, including images, fonts, audio and video.

## Assets format

The following are the formats supported by Rslib by default:

- **images**: png, jpg, jpeg, gif, svg, bmp, webp, ico, apng, avif, tif, tiff, jfif, pjpeg, pjp, cur.
- **fonts**: woff, woff2, eot, ttf, otf, ttc.
- **audio**: mp3, wav, flac, aac, m4a, opus.
- **video**: mp4, webm, ogg, mov.

To import assets in other formats, refer to [Extend Asset Types](#extend-asset-types).

## Import assets in JavaScript file

In JavaScript files, you can directly import static assets with relative paths through `import`:

```tsx
// Import the logo.png image in the 'src/assets' directory
import logo from './assets/logo.png';

console.log(logo); // "/static/logo.[hash].png"

export default = () => <img src={logo} />;
```

Import with **alias** is also available:

```tsx
import logo from '@/assets/logo.png';

console.log(logo); // "/static/logo.[hash].png"

export default = () => <img src={logo} />;
```

When the [format](/config/lib/format.md) is set to `cjs` or `esm`, Rslib treats the output as an mid-level artifact that will be consumed by other build tools again and transforms the source file into a JavaScript file and a static asset file that is emitted according to [output.distPath](/config/rsbuild/output.md#outputdistpath) by default with preserving the `import` or `require` statements for static assets.

The following is an example of usage, assuming the source code is as follows:


**src/index.ts**

```tsx
import logo from './assets/logo.svg';

console.log(logo);
```


**src/assets/logo.svg**

![](https://assets.rspack.rs/rslib/rslib-logo.svg)

Based on the configuration in the [output structure](/guide/basic/output-structure.md) in the configuration file, the following outputs will be emitted:


**bundle**


**dist/index.mjs**

```tsx
import logo_namespaceObject from './static/svg/logo.svg';

console.log(logo_namespaceObject);
```


**dist/static/svg/logo.svg**

![](https://assets.rspack.rs/rslib/rslib-logo.svg)


**bundleless**


**dist/index.mjs**

```tsx
import logo from './assets/logo.mjs';

console.log(logo);
```


**dist/assets/logo.mjs**

```tsx
import logo_namespaceObject from '../static/svg/logo.svg';
export { logo_namespaceObject as default };
```


**dist/static/svg/logo.svg**

![](https://assets.rspack.rs/rslib/rslib-logo.svg)


## Import assets in CSS file

In CSS files, you can import static assets with relative paths:

```css title="src/index.css"
.logo {
  background-image: url('./assets/logo.png');
}
```

Import with **alias** are also supported:

```css title="src/index.css"
.logo {
  background-image: url('@/assets/logo.png');
}
```

When the [format](/config/lib/format.md) is set to `cjs` or `esm`, Rslib treats the output as an mid-level artifact that will be consumed by other build tools again and preserves relative reference paths in CSS outputs by default via setting [output.assetPrefix](/config/rsbuild/output.md#outputassetprefix) to `"auto"`.

The following is an example of usage, assuming the source code is as follows:


**src/index.css**

```css
.logo {
  background-image: url('./assets/logo.png');
}
```


**src/assets/logo.png**

![](https://assets.rspack.rs/rslib/rslib-logo-192x192.png)

The following output will be emitted:


**dist/index.css**

```css
.logo {
  background-image: url('./static/image/logo.png');
}
```


**dist/static/image/logo.png**

![](https://assets.rspack.rs/rslib/rslib-logo-192x192.png)

***

### Ignore some assets imported in CSS

If you need to import a static asset with an absolute path in a CSS file:

```css
@font-face {
  font-family: DingTalk;
  src: url('/image/font/foo.ttf');
}
```

By default, the built-in `css-loader` in Rslib will resolve absolute paths in `url()` and look for the specified modules. If you want to skip resolving absolute paths, you can configure [`tools.cssLoader`](/config/rsbuild/tools.md#toolscssloader) to filter out the specified paths. The filtered paths are preserved as they are in the code.

```ts
export default {
  tools: {
    cssLoader: {
      url: {
        filter: (url) => {
          if (/\/image\/font/.test(url)) {
            return false;
          }
          return true;
        },
      },
    },
  },
};
```

## Inline static assets

When the [format](/config/lib/format.md) is set to `cjs` or `esm`, Rslib treats the output as an mid-level artifact that will be consumed by other build tools again and sets [output.dataUriLimit](/config/rsbuild/output.md#outputdataurilimit) to `0` by default to not inline any static assets.

## Build output directory

Once static assets are imported, they will automatically be output to the build output directory. You can:

- Modify the filename of the outputs through [output.filename](/config/rsbuild/output.md#outputfilename). For example, add a hash value to the filename of the outputs, which is usually used when there are files with the same name to avoid filename conflicts.

```ts title="rslib.config.ts"
export default {
  output: {
    filename: {
      svg: '[name].[contenthash:10].svg',
      font: '[name].[contenthash:10][ext]',
      image: '[name].[contenthash:10][ext]',
      media: '[name].[contenthash:10][ext]',
      assets: '[name].[contenthash:10][ext]',
    },
  },
};
```

- Change the output path of the outputs through [output.distPath](/config/rsbuild/output.md#outputdistpath). For example, emit static assets output to the `dist/resource` directory.

```ts title="rslib.config.ts"
export default {
  output: {
    distPath: {
      svg: 'resource/svg',
      font: 'resource/font',
      image: 'resource/image',
      media: 'resource/media',
      assets: 'resource/assets',
    },
  },
};
```

## Type declaration

When you import static assets in TypeScript code, TypeScript may prompt that the module is missing a type definition:

```
TS2307: Cannot find module './logo.png' or its corresponding type declarations.
```

To fix this, you need to add a type declaration file for the static assets, please create a `src/env.d.ts` file, and add the corresponding type declaration.

- Method 1: If the `@rslib/core` package is installed, you can reference the [preset types](/guide/basic/typescript.md#preset-types) provided by `@rslib/core`:

```ts
/// <reference types="@rslib/core/types" />
```

- Method 2: Manually add the required type declarations:

```ts title="src/env.d.ts"
// Taking png images as an example
declare module '*.png' {
  const content: string;
  export default content;
}
```

After adding the type declaration, if the type error still exists, you can try to restart the current IDE, or adjust the directory where `env.d.ts` is located, making sure the TypeScript can correctly identify the type definition.

## Extend asset types

If the built-in static assets type of Rslib does not meet your needs, you can extend the additional static assets type in the following ways.

### Use `source.assetsInclude`

By using the [source.assetsInclude](/config/rsbuild/source.md#sourceassetsinclude) config, you can specify additional file types to be treated as static assets.

```ts title="rslib.config.ts"
export default {
  source: {
    assetsInclude: /\.pdf$/,
  },
};
```

After adding the above configuration, you can import `*.pdf` files in your code, for example:

```js
import myFile from './static/myFile.pdf';

console.log(myFile);
```

### Use `tools.rspack`

You can modify the built-in Rspack configuration and add custom static assets handling rules via [tools.rspack](/config/rsbuild/tools.md#toolsrspack).

For example, to treat `*.pdf` files as assets and output them to the dist directory, you can add the following configuration:

```ts title="rslib.config.ts"
export default {
  tools: {
    rspack(config, { addRules }) {
      addRules([
        {
          test: /\.pdf$/,
          // Convert assets to separate files and keep import statements
          type: 'asset/resource',
          generator: {
            importMode: 'preserve',
          },
        },
      ]);
    },
  },
};
```

For more information about asset modules, please refer to [Rspack - Asset modules](https://rspack.rs/guide/features/asset-module).



---
url: /guide/advanced/storybook.md
---

# Use Storybook

[Storybook](https://storybook.js.org/) is a powerful tool for developing UI components in isolation for React, Vue, and other frameworks. It enables you to build and test components independently, which can accelerate both development and testing.

[storybook-rsbuild](https://github.com/rstackjs/storybook-rsbuild) is the Rsbuild powered Storybook builder, and provided the framework integration for React, Vue3 and vanilla JavaScript. The coherent Rsbuild system could make Storybook use an unified configuration with Rslib.

:::info Storybook Rsbuild version map

The table below shows how Storybook Rsbuild matches Storybook versions. If you are on Storybook v9 or earlier, follow the [official migration guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-9x-to-1000) to upgrade to the latest release.

| Storybook                              | Storybook Rsbuild                                                                  |
| -------------------------------------- | ---------------------------------------------------------------------------------- |
| [v10](https://storybook.js.org/docs/)  | [^3.0.0](https://storybook.rsbuild.rs)                                             |
| [v9](https://storybook.js.org/docs/9/) | [^2.0.0](https://storybook-v2.rsbuild.rs)                                          |
| [v8](https://storybook.js.org/docs/8/) | [^1.0.0](https://github.com/rstackjs/storybook-rsbuild/tree/v1/website/docs/guide) |

:::

## Getting started

### Setup a Rslib project

This is the prerequisite for setting up Storybook. You need to have a Rslib project with components that you want to showcase in Storybook, check out [Solution](/guide/solution/index.md) to setup a Rslib project.

:::tip
You can create a new project with Storybook already wired up via [create-rslib](/guide/start/quick-start.md#creating-an-rslib-project), without manual setup.
:::

### Add Storybook to project

Set up a Storybook project with an existing Rslib project. To use React, Vue 3, vanilla JavaScript, or other frameworks, you must first install the appropriate Storybook framework package. For installation instructions, refer to the [Storybook Rsbuild documentation](https://storybook.rsbuild.rs/guide/framework.html).

Using React as an example, at this step you need to:

1. Install the dependencies for Storybook Rsbuild React framework. The essential ones include

   - [storybook](https://www.npmjs.com/package/storybook): The Storybook core.
   - [@storybook/react](https://www.npmjs.com/package/@storybook/react): React renderer for Storybook.
   - [@storybook/addon-docs](https://www.npmjs.com/package/@storybook/addon-docs): Documentation tooling for Storybook.
   - [@storybook/addon-onboarding](https://www.npmjs.com/package/@storybook/addon-onboarding): Interactive onboarding experience for Storybook.
   - [@rsbuild/core](https://www.npmjs.com/package/@rsbuild/core): Storybook builder.
   - [storybook-addon-rslib](https://www.npmjs.com/package/storybook-addon-rslib): This addon will make Storybook Rsbuild could derive Rsbuild configuration from Rslib config file.
     The addon will automatically read the Rslib configuration and apply it to Storybook Rsbuild, ensuring that the configuration is unified. You can check the [storybook-addon-rslib](https://storybook.rsbuild.rs/guide/integrations/rslib.html) documentation for available options.

   <PackageManagerTabs
     command={{
     npm: 'npm add storybook @storybook/react @storybook/addon-docs @storybook/addon-onboarding storybook-addon-rslib @rsbuild/core -D',
     yarn: 'yarn add storybook @storybook/react @storybook/addon-docs @storybook/addon-onboarding storybook-addon-rslib @rsbuild/core -D',
     pnpm: 'pnpm add storybook @storybook/react @storybook/addon-docs @storybook/addon-onboarding storybook-addon-rslib @rsbuild/core -D',
     bun: 'bun add storybook @storybook/react @storybook/addon-docs @storybook/addon-onboarding storybook-addon-rslib @rsbuild/core -D',
   }}
   />

   The dependencies varies for each framework, please refer to the [Storybook Rsbuild documentation](https://storybook.rsbuild.rs/guide/framework.html) for details. In this React example, we will install [storybook-react-rsbuild](https://www.npmjs.com/package/storybook-react-rsbuild) as the framework integration.

   <Tabs>
     <Tab label="React">
       <PackageManagerTabs command="add storybook-react-rsbuild -D" />
     </Tab>

     <Tab label="Vue">
       <PackageManagerTabs command="add storybook-vue3-rsbuild -D" />
     </Tab>
   </Tabs>

2. Configure the Storybook configuration file `.storybook/main.js`, specify the stories and addons, and set the framework with corresponding framework integration.

   ```js title=".storybook/main.js"
   export default {
     stories: [
       '../stories/**/*.mdx',
       '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)',
     ],
     addons: [
       '@storybook/addon-docs',
       '@storybook/addon-onboarding',
       'storybook-addon-rslib',
     ],
     framework: 'storybook-react-rsbuild', // storybook-react-rsbuild for example
   };
   ```

3. Add a simple story to the `stories` directory. For example, create a `Button.stories.js` file with the following content:

   ```js title="stories/Button.stories.js"
   import { Button } from '../src/Button';

   const meta = {
     title: 'Example/Button',
     component: Button,
   };

   export default meta;

   export const Primary = {
     args: {
       primary: true,
       label: 'Button',
     },
   };
   ```

:::tip
In case you are using [Yarn Plug-n-Play](https://yarnpkg.com/features/pnp) or your project is set up within a mono repository environment, you might run into issues with module resolution. In such cases, you can add an `getAbsolutePath('storybook-addon-rslib')` function to resolve the addon. Check the [Storybook's FAQ](https://storybook.js.org/docs/faq#how-do-i-fix-module-resolution-in-special-environments) for more information.
:::

There you go, you could start and build the Storybook server with the following command:

```bash
npx storybook dev   // development mode
npx storybook build // build static files
```

Check out more details in the [Storybook Rsbuild documentation](https://storybook.rsbuild.rs/) and the [Storybook documentation](https://storybook.js.org/docs/react/get-started/introduction).

## Example

- [React component library + Rslib + Storybook](https://github.com/rstackjs/rstack-examples/tree/main/rslib/react-storybook)
- [Vue component library + Rslib + Storybook](https://github.com/rstackjs/rstack-examples/tree/main/rslib/vue-storybook)



---
url: /guide/advanced/svgr-files.md
---

# SVGR

By default, Rslib treats SVG images as static assets.

By adding the [@rsbuild/plugin-svgr](https://rsbuild.rs/plugins/list/plugin-svgr) plugin, Rslib supports transforming SVG to React components via [SVGR](https://react-svgr.com/).

## Quick start

### Install the plugin

You can install the plugin using the following command:


```sh [npm]
npm add @rsbuild/plugin-svgr -D
```

```sh [yarn]
yarn add @rsbuild/plugin-svgr -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-svgr -D
```

```sh [bun]
bun add @rsbuild/plugin-svgr -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-svgr -D
```

### Register the plugin

You can register the plugin in the `rslib.config.ts` file:

```ts title="rslib.config.ts"
import { pluginSvgr } from '@rsbuild/plugin-svgr';

export default {
  plugins: [pluginSvgr()],
};
```

## Examples

### Bundle mode

In bundle mode, all usages supported by [@rsbuild/plugin-svgr](https://rsbuild.rs/plugins/list/plugin-svgr) are available in Rslib. The only difference is that when using an SVG file in URL form, Rslib will retain the `import` statement for the static asset in the output according to [Static assets](/guide/advanced/static-assets.md).

Here is an example of usage:

```jsx title="App.jsx"
import Logo from './logo.svg?react';

export const App = () => <Logo />;
```

If the import path does not include the `?react` suffix, the SVG will be treated as a normal static asset, and the `import` statement for the static asset will be retained.

`@rsbuild/plugin-svgr` also supports default imports and mixed imports:

```js
import logoURL from './static/logo.svg';

console.log(logoURL);
```

`@rsbuild/plugin-svgr` also supports default import and mixed import:

- Enable default import by setting [svgrOptions.exportType](https://rsbuild.rs/plugins/list/plugin-svgr#svgroptionsexporttype) to `'default'`.
- Enable mixed import through the [mixedImport](https://rsbuild.rs/plugins/list/plugin-svgr#mixedimport) option to use both default and named import.

### Bundleless mode

In bundleless mode, since each file undergoes code transformation independently, the import ways of `?react` and `?url` are not supported. However, the following two usage forms are supported:

#### Named import

`@rsbuild/plugin-svgr` supports named import of `ReactComponent` to use SVGR. You need to set [svgrOptions.exportType](https://rsbuild.rs/plugins/list/plugin-svgr#svgroptionsexporttype) to `'named'`.

```js
pluginSvgr({
  svgrOptions: {
    exportType: 'named',
  },
});
```

```jsx title="App.jsx"
import { ReactComponent as Logo } from './logo.svg';

export const App = () => <Logo />;
```

All `.svg` files will be transformed into React components. At this time, you can:

- Exclude files that do not need to be transformed by setting [exclude](https://rsbuild.rs/plugins/list/plugin-svgr#exclude).
- Change to default export by setting [svgrOptions.exportType](https://rsbuild.rs/plugins/list/plugin-svgr#svgroptionsexporttype) to `'default'`.

#### Mixed import

If your library has both URL and React component import forms for SVG files, you can also use mixed import.

```ts
pluginSvgr({
  mixedImport: true,
  svgrOptions: {
    exportType: 'named',
  },
});
```

At this time, the imported SVG file will export both the URL and the React component.

```js
import logoUrl, { ReactComponent as Logo } from './logo.svg';

console.log(logoUrl); // -> string
console.log(Logo); // -> React component
```

For more information, refer to the [mixedImport](https://rsbuild.rs/plugins/list/plugin-svgr#mixedimport) option.



---
url: /guide/advanced/third-party-deps.md
---

# Handle third-party dependencies

This section introduces how to handle third-party dependencies in bundle mode.

Generally, third-party dependencies required by a project can be installed via the `install` command in the package manager. After the third-party dependencies are successfully installed, they will generally appear under `dependencies` and `devDependencies` in the project `package.json`.

```json title="package.json"
{
  "dependencies": {},
  "devDependencies": {}
}
```

Dependencies under `"dependencies"` are generally required for the package in runtime, and if these third-party dependencies are declared under `"devDependencies"`, then there will be missing dependencies in production runtime.

In addition to `"dependencies"`, `"peerDependencies"`can also declare dependencies that are needed in the production environment, but it puts more emphasis on the existence of these dependencies declared by `"peerDependencies"` in the project's runtime environment, similar to the plugin mechanism.

## Default handling of third-party dependencies

By default, when generating CJS or ESM outputs, third-party dependencies under `"dependencies"`, `"optionalDependencies"` and `"peerDependencies"` are not bundled by Rslib.

This is because when the npm package is installed, its `"dependencies"` will also be installed. By not packaging `"dependencies"`, you can reduce the size of the package product.

If you need to package some dependencies, it is recommended to move them from `"dependencies"` to `"devDependencies"`, which is equivalent to prebundle the dependencies and reduces the size of the dependency installation.

### Example

If the project depends on `foo`.

```json title="package.json"
{
  "dependencies": {
    "foo": "^1.0.0"
  },
  // or
  "peerDependencies": {
    "foo": "^1.0.0"
  }
}
```

When the `foo` dependency is used in the source code:

```tsx title="src/index.ts"
import foo from 'foo';
console.info(foo);
```

The `foo` package will not be bundled into the output:

```js title="dist/index.js"
import foo from 'foo';
console.info(foo);
```

If you want to modify the default processing, you can use the following API:

- [lib.autoExternal](/config/lib/auto-external.md)
- [output.externals](/config/rsbuild/output.md#outputexternals)

## Exclude specified third-party dependencies

The configuration described above allows you to implement more fine-grained handling of third-party dependencies.

For example, when we need to leave only certain dependencies unbundled, we can configure it as follows.

:::tip
In this case, some dependencies may not be suitable for bundling. If so, you can handle it as follows.
:::

```ts
export default defineConfig({
  lib: [
    {
      // ...
      autoExternal: true,
      output: {
        externals: ['pkg-1', /pkg-2/],
      },
      // ...
    },
  ],
});
```



---
url: /guide/basic/cli.md
---

# CLI

Rslib comes with a lightweight CLI that includes commands such as [rslib build](#rslib-build) and [rslib inspect](#rslib-inspect).

## All commands

To view all available CLI commands, run the following command in the project directory:

```bash
npx rslib -h
```

The output is shown below:

```bash
Usage:
  $ rslib [command] [options]

Commands:
  build    build the library for production (default if no command is given)
  inspect  inspect the Rsbuild / Rspack configs of Rslib projects
  mf-dev   start Rsbuild dev server of Module Federation format
```

## Common flags

Rslib CLI provides several common flags that can be used with all commands:

| Flag                       | Description                                                                                                                                                    |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-c, --config <config>`    | Specify the configuration file, can be a relative or absolute path, see [Specify config file](/guide/basic/configure-rslib.md#specify-config-file)             |
| `--config-loader <loader>` | Set the config file loader (`auto` \| `jiti` \| `native`), see [Specify config loader](/guide/basic/configure-rslib.md#specify-config-loader)                  |
| `--env-dir <dir>`          | Specify the directory to load `.env` files, see [Rsbuild - Env directory](https://rsbuild.rs/guide/advanced/env-vars#env-directory)                            |
| `--env-mode <mode>`        | Specify the env mode to load the `.env.[mode]` file, see [Rsbuild - Env mode](https://rsbuild.rs/guide/advanced/env-vars#env-mode)                             |
| `-h, --help`               | Display help for command                                                                                                                                       |
| `--lib <id>`               | Specify the library to run commands (repeatable, e.g. `--lib esm --lib cjs`), see [lib.id](/config/lib/id.md) to learn how to get or set the ID of the library |
| `--log-level <level>`      | Set the log level (`info` \| `warn` \| `error` \| `silent`), see [logLevel](/config/rsbuild/log-level.md)                                                      |
| `--no-env`                 | Disable loading of `.env` files                                                                                                                                |
| `-r, --root <root>`        | Specify the project root directory, can be an absolute path or a path relative to cwd                                                                          |

## rslib build

The `rslib build` command will build the outputs for production in the `dist/` directory by default.

```bash
Usage:
  $ rslib build

Options:
  -w, --watch            turn on watch mode, watch for changes and rebuild
  --entry <entry>        set entry file or pattern (repeatable)
  --dist-path <dir>      set output directory
  --bundle               enable bundle mode (use --no-bundle to disable)
  --format <format>      specify the output format (esm | cjs | umd | mf | iife)
  --syntax <syntax>      set build syntax target (repeatable)
  --target <target>      set runtime target (web | node)
  --dts                  emit declaration files (use --no-dts to disable)
  --externals <pkg>      add package to externals (repeatable)
  --minify               minify output (use --no-minify to disable)
  --clean                clean output directory before build (use --no-clean to disable)
  --auto-extension       control automatic extension redirect (use --no-auto-extension to disable)
  --auto-external        control automatic dependency externalization (use --no-auto-external to disable)
  --tsconfig <path>      use specific tsconfig (relative to project root)
```

:::note
If the [Rslib configuration file](/guide/basic/configure-rslib.md#configuration-file) is not present in your project, the CLI will automatically use the default configuration containing only a single [lib](/config/lib/index.md) and apply all build options from the command line. You can add a configuration file once you need a more complex configuration or want to build outputs in multiple formats.
:::

### Environment variables

Rslib supports injecting environment variables or expressions into the code during the build, which is helpful for distinguishing running environments or replacing constants. You can see more details in [Rsbuild - Environment variables](https://rsbuild.rs/guide/advanced/env-vars).

By default, Rslib sets the `process.env.NODE_ENV` environment variable, which is always `'production'` during the build. If you need to distinguish watch mode to dynamically set different configurations, you can set as follows:

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

const isWatch = process.argv.includes('--watch');

export default defineConfig({
  lib: [
    {
      format: 'esm',
    },
  ],
  source: {
    alias: {
      '@request': isWatch ? './src/request.dev.js' : './src/request.prod.js',
    },
  },
});
```

::: note

- If [format](/config/lib/format.md) is `esm` or `cjs`, `process.env.NODE_ENV` in source code will be preserved in the build output.
- If [format](/config/lib/format.md) is `mf` or `umd`, `process.env.NODE_ENV` in source code will be replaced to ensure that the output can run in the browser.

:::

## rslib inspect

The `rslib inspect` command is used to view the Rsbuild config and Rspack config of the Rslib project.

```bash
Usage:
  $ rslib inspect

Options:
  --output <output>     specify inspect content output path (default: ".rsbuild")
  --verbose             show full function definitions in output
```

When you run the command `npx rslib inspect` in the project root directory, the following files will be generated in the `dist/.rsbuild` directory of the project:

- `rsbuild.config.mjs`: Represents the Rsbuild configuration used during the build.
- `rspack.config.web.mjs`: Represents the Rspack configuration used during the build.
- `rslib.config.mjs`: Represents the final Rslib configuration after normalization.

```text
➜ npx rslib inspect

Inspect config succeed, open following files to view the content:

  - Rsbuild Config: /project/dist/.rsbuild/rsbuild.config.mjs
  - Rspack Config (esm): /project/dist/.rsbuild/rspack.config.esm.mjs
  - Rslib Config: /project/dist/.rsbuild/rslib.config.mjs
```

### Verbose content

By default, the inspect command omits the content of functions in the configuration object. You can add the `--verbose` option to output the complete content of functions:

```bash
rslib inspect --verbose
```

### Multiple output formats

If the current project has multiple output formats, such as ESM artifact and CJS artifact simultaneously, multiple Rspack configuration files will be generated in the `dist/.rsbuild` directory.

```text
➜ npx rslib inspect

Inspect config succeed, open following files to view the content:

  - Rsbuild Config (esm): /project/dist/.rsbuild/rsbuild.config.esm.mjs
  - Rsbuild Config (cjs): /project/dist/.rsbuild/rsbuild.config.cjs.mjs
  - Rspack Config (esm): /project/dist/.rsbuild/rspack.config.esm.mjs
  - Rspack Config (cjs): /project/dist/.rsbuild/rspack.config.cjs.mjs
  - Rslib Config: /project/dist/.rsbuild/rslib.config.mjs
```

## rslib mf-dev

The `rslib mf-dev` command is utilized to start Rsbuild dev server for the [Module Federation](/guide/advanced/module-federation.md) format.

This enables you to develop and debug your mf format module within the host app.



---
url: /guide/basic/configure-rslib.md
---

# Configure Rslib

Rslib's configuration is based on Rsbuild, which means that you can use all of Rsbuild configurations, as well as the `lib` configuration specific to Rslib.

## Configuration structure

Rslib provides the `lib` option to configure the library outputs. It is an array, and each object is used to describe a format of the output.

For example, output ESM and CJS formats, and use `es2021` syntax:

```js title="rslib.config.mjs"
export default {
  lib: [
    { format: 'esm', syntax: 'es2021' },
    { format: 'cjs', syntax: 'es2021' },
  ],
};
```

### Common Rsbuild configurations

You can set common Rsbuild configurations outside the `lib` field, which will be inherited by each configuration object inside the `lib` field.

For example, set the [output.target](/config/rsbuild/output.md#outputtarget) of Rsbuild to `web`, which will affect the output of all `lib` configuration objects:

```js title="rslib.config.mjs"
export default {
  lib: [
    { format: 'esm', syntax: 'es2021' },
    { format: 'cjs', syntax: 'es2021' },
  ],
  output: {
    target: 'web',
  },
};
```

### Separate Rsbuild configurations

In the `lib` field, you can set separate Rsbuild configurations for each output format, which will override the common Rsbuild configurations outside the `lib` field.

For example, separately set the [output.target](/config/rsbuild/output.md#outputtarget) of the ESM output to `web`:

```js title="rslib.config.mjs"
export default {
  lib: [
    // The target of the ESM output is `web`
    {
      format: 'esm',
      output: {
        target: 'web',
      },
    },
    // The CJS output inherits the common configuration and target is `node`
    {
      format: 'cjs',
    },
  ],
  output: {
    target: 'node',
  },
};
```

Rslib will generate the [environments](https://rsbuild.rs/config/environments) configuration of Rsbuild internally, you can run [rslib inspect](/guide/basic/cli.md#rslib-inspect) command to view the final generated configuration.

You can also refer to the [Configuration Overview](/config/index.md) page to view the detailed introduction of all configurations.

## Configuration file

When you use the CLI of Rslib, Rslib will automatically read the configuration file in the root directory of the current project and resolve it in the following order:

- `rslib.config.mjs`
- `rslib.config.ts`
- `rslib.config.js`
- `rslib.config.cjs`
- `rslib.config.mts`
- `rslib.config.cts`

We recommend using the `.mjs` or `.ts` format for the configuration file and importing the `defineConfig` utility function from `@rslib/core`. It provides friendly TypeScript type hints and autocompletion, which can help you avoid errors in the configuration.

For example, in `rslib.config.ts`, you can define the Rslib [syntax](/config/lib/syntax.md) configuration and the Rsbuild [output.target](https://rsbuild.rs/config/output/target#outputtarget) configuration:

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
      syntax: 'es2021',
    },
  ],
  output: {
    target: 'node',
  },
});
```

If you are developing a non-TypeScript project, you can use the `.mjs` format for the configuration file.

:::tip

When you use the `.ts`, `.mts`, and `.cts` extensions, Rslib will use [jiti](https://github.com/unjs/jiti) to load configuration files, providing interoperability between ESM and CommonJS. The behavior of module resolution differs slightly from the native behavior of Node.js.

:::

## Specify config file

Rslib CLI uses the `--config` option to specify the config file, which can be set to a relative path or an absolute path.

For example, if you need to use the `rslib.prod.config.mjs` file when running `build`, you can add the following scripts to `package.json`:

```json title="package.json"
{
  "scripts": {
    "build": "rslib build --config rslib.prod.config.mjs"
  }
}
```

You can also abbreviate the `--config` option to `-c`:

```bash
rslib build -c rslib.prod.config.mjs
```

## Specify config loader

Rslib provides three ways to load configuration files:

- `jiti`: When you use a configuration file with the `.ts`, `.mts`, and `.cts` extensions, Rslib will use [jiti](https://github.com/unjs/jiti) to load configuration files, providing interoperability between ESM and CommonJS. The behavior of module resolution differs slightly from the native behavior of Node.js.

- `native`: Use Node.js native loader to load the configuration file. This can ensure that the module resolution behavior is consistent with the native behavior of Node.js and has better performance. This requires that your JavaScript runtime already natively supports TypeScript.

  For example, Node.js v22.6.0+ already natively supports TypeScript, you can use the following command to use the Node.js native loader to load the configuration file:

  ```bash
  # Node.js >= v22.18.0
  # No need to set --experimental-strip-types
  npx rslib build --config-loader native

  # Node.js v22.6.0 - v22.17.1
  # Need to set --experimental-strip-types
  NODE_OPTIONS="--experimental-strip-types" npx rslib build --config-loader native
  ```

- `auto`(Default): Use Node.js's native loader to load configuration files first, fallback to using jiti if it fails.

### About Node.js native loader

When using Node.js's native loader, please note the following limitations:

1. When importing JSON files, you need to use import attributes:

   ```ts
   import pkgJson from './package.json' with { type: 'json' }; // ✅ Correct
   import pkgJson from './package.json'; // ❌ Incorrect
   ```

2. When importing TypeScript files, you need to include the `.ts` extension:

   ```ts
   import baseConfig from './rslib.base.config.ts'; // ✅ Correct
   import baseConfig from './rslib.base.config'; // ❌ Incorrect
   ```

> See [Node.js - Running TypeScript Natively](https://nodejs.org/en/learn/typescript/run-natively#running-typescript-natively) for more details.

## Using environment variables

In the configuration file, you can use Node.js environment variables to dynamically set different configurations:

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
    },
  ],
  source: {
    alias: {
      '@language':
        process.env.LANGUAGE === 'en'
          ? './src/language/en.js'
          : './src/language/zh.js',
    },
  },
});
```

## Configure Rsbuild

Rslib allows you to use most of the Rsbuild configurations. Currently, the `environments` config is not supported because it is generated internally by Rslib.

- Refer to [Rsbuild Configuration](/config/rsbuild/index.md) for common Rsbuild configurations.
- Refer to [Rsbuild Documentation](https://rsbuild.rs/config/index#config-overview) for all Rsbuild configurations.

## Configure Rspack

Rslib is built on top of Rsbuild and Rsbuild supports directly modifying the Rspack configuration object and also supports modifying the built-in Rspack configuration of Rsbuild through `rspack-chain`. This means you can configure Rspack related configurations in an Rslib project as well.

For more details, refer to [Configure Rspack](https://rsbuild.rs/guide/basic/configure-rspack).

## Debug mode

You can add the `DEBUG=rslib` environment variable when building to enable Rslib's debug mode.

```bash
DEBUG=rslib pnpm build
```

In debug mode, Rslib will output additional log information and write the final Rsbuild config and Rspack config after processing by Rslib to the output directory, making it convenient for developers to view and debug.

Here is an example of a library that sets both CJS and ESM formats:

```
Inspect config succeed, open following files to view the content:

  - Rsbuild Config (esm): /project/dist/.rsbuild/rsbuild.config.esm.mjs
  - Rsbuild Config (cjs): /project/dist/.rsbuild/rsbuild.config.cjs.mjs
  - Rspack Config (esm): /project/dist/.rsbuild/rspack.config.esm.mjs
  - Rspack Config (cjs): /project/dist/.rsbuild/rspack.config.cjs.mjs
  - Rslib Config: /project/dist/.rsbuild/rslib.config.mjs
```

- Open the generated `/dist/.rsbuild/rsbuild.config.esm.mjs` file to see the complete content of the Rsbuild config.
- Open the generated `/dist/.rsbuild/rspack.config.esm.mjs` file to see the complete content of the Rspack config.
- Open the generated `/dist/.rsbuild/rslib.config.mjs` file to see the complete content of the Rslib config.



---
url: /guide/basic/output-format.md
---

# Output format

There are multiple supported output formats for the generated JavaScript files in Rslib: [ESM](#esm--cjs), [CJS](#esm--cjs), [UMD](#umd), [MF](#mf), and [IIFE](#iife). In this chapter, we will introduce the differences between these formats and how to choose the right one for your library.

## ESM / CJS

Library authors need to carefully consider which module formats to support. Let's understand ESM (ECMAScript Modules) and CJS (CommonJS) and when to use them.

### What are ESM and CJS?

- **ESM**: <ESM />

- **CommonJS**: <CJS />

::: tip

Read the [Node.js Package Configuration Guide](https://nodejs.github.io/package-examples/) to learn more about ESM and CJS, including file structure, `package.json` configuration, module interoperability, and best practices.

:::

### Choose module formats

For different shapes of libraries, the choice of module format may vary. Here are two common scenarios:

#### ship [pure ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) package

shipping only ESM is the best choice for libraries that are intended to be used in modern environments, such as browser applications or Node.js applications that support ESM. However, if the upstream library is in format of CJS, they only can import pure ESM by using dynamic import like `const pureEsmLib = await import('pure-esm-lib')`.

- **Pros:**
  - ESM is the official JavaScript standard, making it more future-proof and widely supported across environments.
  - ESM enables static analysis, which facilitates optimizations like tree-shaking to remove unused code.
  - The syntax is cleaner and more intuitive, with import and export statements that are easier to read compared to CommonJS.
  - ESM allows for better compatibility across both browser and server environments, making it ideal for isomorphic or universal JavaScript applications.
- **Cons:**
  - ESM modules are loaded asynchronously, which can complicate conditional imports and lazy loading in some cases.
  - Some Node.js tools and libraries still have limited or incomplete support for ESM, requiring workarounds or additional configuration.
  - You must explicitly include file extensions in import paths, which can be cumbersome, especially when working with TypeScript or other transpiled languages.

#### ship [ESM & CJS (dual)](https://antfu.me/posts/publish-esm-and-cjs#compatibility) package

The community is migrating to ESM, but there are still many projects using CJS. If you want to support both ESM and CJS, you can publish a dual package. For most library authors, offering dual formats is a safer and smoother way to access the best of both worlds. You could read antfu' blog post [Publish ESM and CJS packages](https://antfu.me/posts/publish-esm-and-cjs) for more details.

- **Pros:**
  - Wider compatibility: Dual packages support both modern ESM environments and legacy CJS environments, ensuring broader usage across different ecosystems.
  - Gradual migration: Developers can gradually transition from CJS to ESM without breaking existing projects, allowing for smoother adoption of the new standard.
  - Flexibility for consumers: Users of the package can choose which module system best fits their project, providing flexibility in different build tools and environments.
  - Cross-runtime support: Dual packages can work in multiple runtimes, such as Node.js and browsers, without requiring additional bundling or transpilation.

- **Cons:**
  - Increased complexity: Maintaining two module formats adds complexity to the build process, requiring additional configuration and testing to ensure both versions work correctly.
  - Dual package hazard: Mixing ESM and CJS can lead to issues such as broken instanceof checks or unexpected behavior when dependencies are loaded in different formats.

## UMD

### What is UMD?

UMD stands for [Universal Module Definition](https://github.com/umdjs/umd), a pattern for writing JavaScript modules that can work universally across different environments, such as both the browser and Node.js. Its primary goal is to ensure compatibility with the most popular module systems, including AMD (Asynchronous Module Definition), CommonJS (CJS), and browser globals.

### When to use UMD?

If you are building a library that needs to be used in both the browser and Node.js environments, UMD is a good choice. UMD can be used as a standalone script tag in the browser or as a CommonJS module in Node.js.

A detailed answer from StackOverflow: [What is the Universal Module Definition (UMD)?](https://stackoverflow.com/a/77284527/8063488)

> However, for frontend libraries, you still offer a single file for convenience, that users can download (from a CDN) and directly embed in their web pages. This still commonly employs a UMD pattern, it's just no longer written/copied by the library author into their source code, but added automatically by the transpiler/bundler.
>
> And similarly, for backend/universal libraries that are supposed to work in
> Node.js, you still also distribute a commonjs module build via npm to support
> all the users who still use a legacy version of Node.js (and don't want/need
> to employ a transpiler themselves). This is less common nowadays for new
> libraries, but existing ones try hard to stay backwards-compatible and not
> cause applications to break.

### How to build a UMD library?

- Set the [lib.format](/config/lib/format.md) to `umd` in the Rslib configuration file.
- If the library need to be exported with a name, set [lib.umdName](/config/lib/umd-name.md) to the name of the UMD library.
- Use [output.externals](/config/rsbuild/output.md#outputexternals) to specify the external dependencies that the UMD library depends on, [lib.autoExtension](/config/lib/auto-extension.md) is enabled by default for UMD.

### Examples

The following Rslib config is an example to build a UMD library.

- `lib.format: 'umd'`: instruct Rslib to build in UMD format.
- `lib.umdName: 'RslibUmdExample'`: set the export name of the UMD library.
- `output.externals.react: 'React'`: specify the external dependency `react` could be accessed by `window.React`.
- `runtime: 'classic'`: use the classic runtime of React to support applications that using React version under 18.

```ts title="rslib.config.ts"
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      // [!code highlight:6]
      format: 'umd',
      umdName: 'RslibUmdExample',
      output: {
        externals: {
          react: 'React',
        },
        distPath: './dist/umd',
      },
    },
  ],
  output: {
    target: 'web',
  },
  plugins: [
    pluginReact({
      swcReactOptions: {
        runtime: 'classic', // [!code highlight]
      },
    }),
  ],
});
```

## MF

### What is MF?

MF stands for Module Federation. Module Federation is an architectural pattern for JavaScript application decomposition (similar to microservices on the server-side), allowing you to share code and resources between multiple JavaScript applications (or micro-frontends).

See [Module Federation](https://rsbuild.rs/guide/advanced/module-federation) for more details.

## IIFE


The iife format stands for "immediately-invoked function expression" and is intended to be run in the browser. Wrapping your code in a function expression ensures that any variables in your code don't accidentally conflict with variables in the global scope. If your entry point has exports that you want to expose as a global in the browser, you can configure that global's name using the global name setting.

In IIFE format, [output.globalObject](https://rspack.rs/config/output#outputglobalobject) is set to [globalThis](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) by default. The `import` statements that match [externals](/config/rsbuild/output.md#outputexternals) in the source code will be transformed to access properties through `globalThis`. You can override [output.globalObject](https://rspack.rs/config/output#outputglobalobject) to any value.

When specifying the `iife` format, the source code and corresponding output are as follows:

```js title="source code"
// parent-sdk is marked as externals
// externals: ['parent-sdk']
import { version } from 'parent-sdk';
alert(version);
```

```js title="IIFE output"
(
  () => {
    const external_parent_sdk_namespaceObject = globalThis['parent-sdk'];
    alert(external_parent_sdk_namespaceObject.version);
  },
)();
```



---
url: /guide/basic/output-structure.md
---

# Output structure

## bundle / bundleless

So first let's understand bundle and bundleless.

Bundle refers to the process of packaging the build outputs, which may be a single file or multiple files based on a certain [code splitting strategy](https://rspack.rs/guide/optimization/code-splitting).

Bundleless, on the other hand, means that each source file is compiled and built separately, but not bundled together. Each output file can be found with its corresponding source code file. The process of bundleless build can also be understood as the process of code transformation of source files only.

![rslib-bundleless-mode](https://assets.rspack.rs/rslib/rslib-bundleless-mode.png)

They have their own benefits.

- bundle can reduce the size of build artifacts and also prebundle dependencies to reduce the size of installed dependencies and increase security. Packaging libraries in advance can speed up application project builds.
- bundleless maintains the original file structure and is more conducive to debugging and tree shaking.

:::warning

bundleless is a single-file compilation mode, so for referencing and exporting types, you need to add the `type` keyword. For example, `import type { A } from './types'`. Please refer to [TypeScript - isolatedModules](/guide/basic/typescript.md#isolatedmodules) for more information.

:::

You can specify whether to bundle using the [bundle](/config/lib/bundle.md) option, which is set to `true` by default.



---
url: /guide/basic/typescript.md
---

# Use TypeScript

Rslib supports TypeScript by default, allowing you to directly use `.ts` and `.tsx` files in your projects.

## TypeScript transpilation

Rslib uses SWC by default for transpiling TypeScript code, and it also supports switching to Babel for transpilation.

### isolatedModules

Unlike the native TypeScript compiler, tools like SWC and Babel compile each file separately and cannot determine whether an imported name is a type or a value. Therefore, when using TypeScript in Rslib, you need to enable the [isolatedModules](https://typescriptlang.org/tsconfig/#isolatedModules) option in your `tsconfig.json` file:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "isolatedModules": true
  }
}
```

This option can help you avoid using certain syntax that cannot be correctly compiled by SWC and Babel, such as cross-file type references. It will guide you to correct the corresponding usage:

```ts
// Wrong
export { SomeType } from './types';

// Correct
export type { SomeType } from './types';
```

> See [SWC - Migrating from tsc](https://swc.rs/docs/migrating-from-tsc) for more details about the differences between SWC and tsc.

## Preset types

`@rslib/core` provides some preset type definitions, including CSS Modules, static assets, `import.meta` and other types.

You can create a `src/env.d.ts` file to reference it:

```ts title="src/env.d.ts"
/// <reference types="@rslib/core/types" />
```

## Type checking

When transpiling TypeScript code using tools like SWC and Babel, type checking is not performed.

Rslib provides the [lib.dts](/config/lib/dts.md) configuration item for generating TypeScript declaration files, and type checking is performed by default during the generation process.

You can skip type checking by setting the [noCheck](https://www.typescriptlang.org/tsconfig/#noCheck) configuration item to `true` in the `tsconfig.json` file.

## tsconfig.json path

Rslib by default reads the `tsconfig.json` file from the root directory. You can use [source.tsconfigPath](/config/rsbuild/source.md#sourcetsconfigpath) to configure a custom `tsconfig.json` file path.

```ts title="rslib.config.ts"
export default {
  lib: [
    // ...
  ],
  source: {
    tsconfigPath: './tsconfig.custom.json',
  },
};
```

## Decorators version

By default, Rslib uses the [`2022-03`](https://rsbuild.rs/config/source/decorators#2022-03) version of the decorators.

If [experimentalDecorators](https://www.typescriptlang.org/tsconfig/#experimentalDecorators) is enabled in `tsconfig.json`, Rslib will set [source.decorators.version](/config/rsbuild/source.md#sourcedecorators) to `legacy` to use the legacy decorators.



---
url: /guide/basic/upgrade-rslib.md
---

# Upgrade Rslib

This section explains how to upgrade the project's Rslib dependencies to the latest version.



:::info

Rslib is still in 0.x version stage, and the API may change frequently. We recommend upgrading to the latest version to access new features and bug fixes.

:::

## Using taze

We recommend using [Taze](https://github.com/antfu-collective/taze) to upgrade the Rslib version. Taze is a CLI tool for updating npm dependencies.

### Usage

Run the following command to upgrade all dependencies that include `rslib` and `rsbuild` in their names:

```bash
npx taze major --include "/(rsbuild|rslib)/" -w
```

:::tip
Rslib has not yet reached version 1.0.0, so you need to add the `major` parameter when updating.
:::

The result will look similar to:

```bash
rslib - 2 major, 1 patch

  @rsbuild/plugin-react       dev  ~2mo  ^1.0.1   →  ^1.0.6
  @rslib/core                 dev  ~7d  ^0.0.15  →  ^0.0.16
  rsbuild-plugin-dts          dev  ~7d  ^0.0.15  →  ^0.0.16

ℹ changes written to package.json, run npm i to install updates.
```

You can also adjust the `include` pattern to match specific packages, for example, to upgrade only packages under the `@rslib` scope:

```bash
npx taze --include /@rslib/ -w
```

### Options

Here are some examples of using taze options.

- In a monorepo, you can add the `-r` option to upgrade recursively:

```bash
npx taze --include /(rsbuild|rslib)/ -w -r
```

- Add `-l` to upgrade locked versions:

```bash
npx taze --include /(rsbuild|rslib)/ -w -l
```

- To upgrade to a major version:

```bash
npx taze major --include /(rsbuild|rslib)/ -w
```

> For more options, please refer to the [taze documentation](https://github.com/antfu-collective/taze).



---
url: /guide/faq/features.md
---

# Features FAQ

## Style processing

### How to skip the preprocessing of Less / Sass files in bundleless mode?

Bundleless means that each source file is compiled and built separately, which can be understood as the process of code transformation of source files only. To skip the preprocessing of `.less/.scss` files, you need to:

1. Set `source.entry` to remove `.less/.scss` files from the entry.
2. Set `output.copy` to copy `.less/.scss` files to the output directory.
3. Set `redirect.style.extension` to `false` to disable the redirect behavior for the import path of `.less/.scss` files.

Below is an example of skipping the `.scss` file processing. All `.scss` files in `src` will be copied to the output directory and retained with consistent relative paths.

```ts title="rslib.config.ts"
export default defineConfig({
  lib: [
    {
      // ...
      source: {
        entry: {
          index: ['./src/**', '!src/**/*.scss'],
        },
      },
      output: {
        copy: [{ from: '**/*.scss', context: path.join(__dirname, 'src') }],
      },
      redirect: {
        style: {
          extension: false,
        },
      },
    },
  ],
});
```

## Static assets processing

### How to skip the processing of static asset files in bundleless mode?

In bundleless mode, Rslib transforms the source static asset file into a JavaScript file and a static asset file that is emitted according to [output.distPath](/config/rsbuild/output.md#outputdistpath) by default, while preserving the `import` or `require` statements for static assets. To skip the above processing of static asset files, you need to:

1. Set `source.entry` to remove static asset files from the entry.
2. Set `output.copy` to copy static asset files to the output directory.
3. Set `redirect.asset.extension` to `false` to disable the redirect behavior for the import path of static asset files.

Below is an example of skipping the `.png` file processing. All `.png` files in `src` will be copied to the output directory and retained with consistent relative paths.

```ts title="rslib.config.ts"
export default defineConfig({
  lib: [
    {
      // ...
      source: {
        entry: {
          index: ['./src/**', '!src/**/*.png'],
        },
      },
      output: {
        copy: [{ from: '**/*.png', context: path.join(__dirname, 'src') }],
      },
      redirect: {
        asset: {
          extension: false,
        },
      },
    },
  ],
});
```

## Code minification

### How to preserve all comments in the output files?

By default, Rslib uses SWC to remove comments. The corresponding SWC [jsc.minify.format](https://swc.rs/docs/configuration/minification#jscminifyformat) configuration is

```js
{
    comments: 'some',
    preserveAnnotations: true,
}
```

This will only preserve some legal comments and annotations. If you want to preserve all comments, you can refer to the following configuration:

```ts title="rslib.config.ts"
export default {
  lib: [
    // ...
  ],
  output: {
    minify: {
      jsOptions: {
        minimizerOptions: {
          format: {
            comments: 'all', // This will preserve all comments
          },
        },
      },
    },
  },
};
```

### How to compress the output size while preserving code readability?

Compressing code can reduce the output size and improve loading speed, but the compressed code is less readable and harder to debug. If you want to preserve code readability, you can keep variable names and disable compression to facilitate debugging. Refer to [web-infra-dev/rsbuild#966](https://github.com/web-infra-dev/rsbuild/pull/3966).

```ts title="rslib.config.ts"
export default {
  lib: [
    // ...
  ],
  output: {
    minify: {
      jsOptions: {
        minimizerOptions: {
          // preserve variable name and disable minify for easier debugging
          mangle: false,
          minify: false,
          compress: true,
        },
      },
    },
  },
};
```

## Declaration files generation

### How to avoid generating declaration files for certain files?

As shown below, Rslib ignores the files under the `src/tests` directory when emitting JavaScript outputs, but these files still generate corresponding declaration files.

```ts title="rslib.config.ts"
export default {
  lib: [
    source: {
      entry: {
        index: ['src/**/*', '!src/tests/**/*'],
      }
    }
  ],
};
```

The entry set by [source.entry](/config/lib/bundle.md#bundle-false) can exclude some files that do not generate corresponding JavaScript outputs, but cannot exclude the generation of corresponding declaration files. This needs to be achieved by setting [include](https://www.typescriptlang.org/tsconfig/#include) and [exclude](https://www.typescriptlang.org/tsconfig/#exclude) in `tsconfig.json`, as shown below:

```json title="tsconfig.json"
{
  "compilerOptions": {
    // ...
  },
  "include": ["src/**/*"],
  "exclude": ["src/tests/**/*"]
}
```

If you want to keep type prompts and checking for these files, but do not generate corresponding declaration files, you can inherit a basic `tsconfig.json` by [extends](https://www.typescriptlang.org/tsconfig/#extends) and then override the `include` and `exclude` options as follows:

```json title="tsconfig.json"
{
  "compilerOptions": {
    // ...
  },
  "include": ["src/**/*", "rslib.config.ts"]
}
```

```json title="tsconfig.build.json"
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    // ...
  },
  "include": ["src/**/*"],
  "exclude": ["src/tests/**/*"]
}
```

The newly added `tsconfig.build.json` needs to be configured in the [source.tsconfigPath](/config/rsbuild/source.md#sourcetsconfigpath) option in `rslib.config.ts`:

```ts title="rslib.config.ts"
export default {
  lib: [
    source: {
      entry: {
        index: ['src/**/*', '!src/tests/**/*'],
      }
    }
  ],
  source: {
    tsconfigPath: 'tsconfig.build.json',
  },
};
```

### How to additionally exclude specified dependencies when `dts.bundle` is `true`?

Rslib uses [rsbuild-plugin-dts](https://github.com/web-infra-dev/rslib/blob/main/packages/plugin-dts/README.md) to generate declaration files, which supports configuration via [output.externals](/config/rsbuild/output.md#outputexternals) for excluding certain dependencies from bundled declaration files.

For example, if `@types/foo` is only declared in `devDependencies`, according to the dependency handling logic of [autoExternal](/config/lib/auto-external.md), Rslib will try to bundle `@types/foo` into the declaration output files during the build. In this case, you can exclude `@types/foo` by configuring [output.externals](/config/rsbuild/output.md#outputexternals).

```ts title="rslib.config.ts"
export default {
  lib: [
    // ...
  ],
  output: {
    externals: ['@types/foo'],
  },
};
```

In addition, if you only want to specify a few dependencies to be bundled into the declaration output files, you can configure [dts.bundle.bundledPackages](/config/lib/dts.md#dtsbundlebundledpackages) to achieve this. All other dependencies not in this configuration will be excluded.

### Why does the directory structure of the declaration files not meet expectations?

The directory structure of the declaration files is related to the `rootDir` configuration in `tsconfig.json`. If `rootDir` is not configured explicitly, TypeScript will automatically infer it, which may cause the output structure to be inconsistent with your expectations.

For example, assuming your project structure is as follows, when `composite` is set to `true`, TypeScript will automatically infer `rootDir` as the project root directory, and the declaration files will be output to `dist/src/index.d.ts`.

```
.
├── dist
│   └── src
│       └── index.d.ts
├── src
│   └── index.ts
└── tsconfig.json
```

You can explicitly set `rootDir` to `'./src'` in `tsconfig.json` to ensure that declaration files are output to the expected `dist/index.d.ts`.

```json title="tsconfig.json"
{
  "compilerOptions": {
    "rootDir": "./src"
  }
}
```

## Rsbuild plugin

### Why does using `modifyRsbuildConfig` to modify the configuration does not take effect?

Rslib internally generates Rsbuild's environments configurations, and each configuration item in the [lib](/config/lib/index.md) array corresponds to a specific environment configuration.

[modifyRsbuildConfig](https://rsbuild.rs/plugins/dev/hooks#modifyrsbuildconfig) is a global hook that cannot be effective for configurations under a specific environment. It is usually used in Rslib to modify globally effective plugins, etc. Therefore, you need to use [modifyEnvironmentConfig](https://rsbuild.rs/plugins/dev/hooks#modifyenvironmentconfig) instead to modify the configuration of a specific environment.

Refer to [Environment Plugin](https://rsbuild.rs/plugins/dev/#environment-plugin) to learn how to develop an Environment Plugin.

## Miscellaneous

### How to preserve module variables such as `__webpack_hash__` in the source code when generating outputs?

Rslib based on Rspack will transform [module variables](https://rspack.rs/api/runtime-api/module-variables) like `__webpack_hash__`, `__webpack_nonce__`, `__webpack_public_path__`, etc. to runtime code containing `__webpack_require__` by default during build process. If you need to preserve these module variables in the outputs, you can configure [source.define](/config/rsbuild/source.md#sourcedefine) as follows:

1. Replace the module variables that need to be preserved in the source code with a unique name, such as `__webpack_hash__` with `WEBPACK_HASH`, `__webpack_nonce__` with `WEBPACK_NONCE`, `__webpack_public_path__` with `WEBPACK_PUBLIC_PATH`, etc.

```ts
const isUpdateAvailable = () => lastCompilationHash !== __webpack_hash__; // [!code --]
const isUpdateAvailable = () => lastCompilationHash !== WEBPACK_HASH; // [!code ++]
```

2. Add the module variables that need to be preserved in `source.define`. The key of the passed configuration object is the replaced variable name in the source code, and the value is the module variable that needs to be preserved in the outputs.

```ts title="rslib.config.ts"
export default defineConfig({
  source: {
    define: {
      WEBPACK_HASH: '__webpack_hash__',
      WEBPACK_NONCE: '__webpack_nonce__',
      WEBPACK_PUBLIC_PATH: '__webpack_public_path__',
    },
  },
});
```



---
url: /guide/migration/modernjs-module.md
---

# Modern.js Module

This section introduces how to migrate a project using Modern.js Module to Rslib.

## Adapt package.json

`Rslib` has a minimal dependency footprint. For the basic functionality you only need the package `@rslib/core`.

You can create a new Rslib project by following the [Quick start](/guide/start/quick-start.md) to see the `package.json` file. Then update your existing `package.json` file like below:

- Remove the fields `main`, `lint-staged`, `simple-git-hooks`, `sideEffects` and `publishConfig`
- Change the `types` field from `./dist/types/index.d.ts` to `./dist/index.d.ts`
- Change the `module` field from `./dist/es/index.js` to `./dist/index.js`
- Remove the scripts fields `prepare`, `build:watch`, `reset`, `change`, `bump`, `pre`, `change-status`, `gen-release-note`, `release`, `new`, `upgrade`
- Change the script `build` from `modern build` to `rslib build`
- Change the script `dev` from `modern dev` to `rslib build --watch`
- Change the script `lint` name to `check` and keep the value
- Add a new script `format` with the value `biome format --write`
- Add the script `test` with the value `vitest run`
- Add the field `exports` (object)
  - Add the field `"."` (object)
  - Add the fields `"types": "./dist/index.d.ts"` and `"import": "./dist/index.js"`
- Add the field `files` with the value `["dist"]`
- Depending on your configuration and use-case the `devDependencies` can vary
  - It is important to replace `@modern-js/module-tools` with `@rslib/core`
  - We do not need `rimraf`, `lint-staged` and `simple-git-hooks` anymore for starters
- Copy over your required `dependencies` and `peerDependencies` if needed

Your `package.json` should look something like this:

```json title="package.json"
{
  "name": "rslib",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  },
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "rslib build",
    "check": "biome check --write",
    "dev": "rslib build --watch",
    "format": "biome format --write",
    "test": "vitest run"
  },
  "devDependencies": {
    "@biomejs/biome": "^2.0.0",
    "@rslib/core": "^0.1.3",
    "typescript": "^5.6.3",
    "vitest": "^2.1.8"
  },
  "peerDependencies": {},
  "dependencies": {}
}
```

## Adapt bundler config

Now we have a clean slate to work with. We will continue with the `Rslib` configuration. It follows the same pattern as all `Rs*` projects. Since this step is very unique for every environment, below is an basic example:

Replace your `modern.config.ts` with a `rslib.config.ts`:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  source: {
    entry: {
      index: ['./src/**'],
    },
  },
  lib: [
    {
      bundle: false,
      dts: true,
      format: 'esm',
    },
  ],
});
```

## TypeScript declaration

If you use TypeScript in your `Modern.js Module` and need to generate declaration files, add the following changes:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  //...
  lib: [
    {
      //...
      dts: true,
    },
  ],
});
```

## React

If you use React in your `Modern.js Module`, add the following changes:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
// Quick tip: You can use all Rsbuild plugins here since they are compatible with Rslib
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  //...
  output: {
    target: 'web',
  },
  plugins: [pluginReact()],
});
```

In addition, you have to install the `@rsbuild/plugin-react` package as `devDependencies`.


```sh [npm]
npm add @rsbuild/plugin-react -D
```

```sh [yarn]
yarn add @rsbuild/plugin-react -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-react -D
```

```sh [bun]
bun add @rsbuild/plugin-react -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-react -D
```

## Sass

If you use Sass in your `Modern.js Module`, add the following changes:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
// Quick tip: You can use all Rsbuild plugins here since they are compatible with Rslib
import { pluginSass } from '@rsbuild/plugin-sass';

export default defineConfig({
  //...
  plugins: [pluginSass()],
});
```

In addition, you have to install the `@rsbuild/plugin-sass` package as `devDependencies`.


```sh [npm]
npm add @rsbuild/plugin-sass -D
```

```sh [yarn]
yarn add @rsbuild/plugin-sass -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-sass -D
```

```sh [bun]
bun add @rsbuild/plugin-sass -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-sass -D
```

If you run TypeScript together with Sass, you might run into declaration files generation errors. This can be resolved by adding a `env.d.ts` file in your `/src` directory.

```ts title="src/env.d.ts"
declare module '*.scss' {
  const content: { [className: string]: string };
  export default content;
}
```

or

```ts title="src/env.d.ts"
/// <reference types="@rslib/core/types" />
```

## CSS Modules

If you use CSS Modules in your `Modern.js Module`, add the following changes:

```js title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
import { pluginSass } from '@rsbuild/plugin-sass';

export default defineConfig({
  lib: [
    {
      //...
      output: {
        cssModules: {
          // the CSS Modules options are 1:1 the same as in the official "css-modules" package
          localIdentName: '[local]--[hash:base64:5]',
        },
      },
    },
  ],
  plugins: [pluginSass()],
});
```

## Contents supplement

This migration doc is contributed by community user [YanPes](https://github.com/YanPes). Much appreciation for his contribution!



---
url: /guide/migration/tsc.md
---

# tsc

This section introduces how to migrate a project using `tsc` (TypeScript Compiler) to Rslib.

## Using Agent Skills

If you are using a Coding Agent that supports Skills, install the [migrate-to-rslib](https://github.com/rstackjs/agent-skills#migrate-to-rslib) skill to help with the migration process.


```sh [npx]
npx skills add rstackjs/agent-skills --skill migrate-to-rslib
```

```sh [yarn]
yarn dlx skills add rstackjs/agent-skills --skill migrate-to-rslib
```

```sh [pnpm]
pnpm dlx skills add rstackjs/agent-skills --skill migrate-to-rslib
```

```sh [bunx]
bunx skills add rstackjs/agent-skills --skill migrate-to-rslib
```

```sh [deno]
deno run -A npm:skills add rstackjs/agent-skills --skill migrate-to-rslib
```

After installation, let the Coding Agent guide you through the migration process.

## Installing dependencies

First, you need to add Rslib's core dependency.


```sh [npm]
npm add @rslib/core -D
```

```sh [yarn]
yarn add @rslib/core -D
```

```sh [pnpm]
pnpm add @rslib/core -D
```

```sh [bun]
bun add @rslib/core -D
```

```sh [deno]
deno add npm:@rslib/core -D
```

## Updating npm scripts

Next, you need to update the npm scripts in your `package.json` to use Rslib's CLI commands instead of `tsc`.

```diff title="package.json"
{
  "scripts": {
-   "build": "tsc",
-   "dev": "tsc --watch"
+   "build": "rslib build",
+   "dev": "rslib build --watch"
  }
}
```

## Create configuration file

Create an Rslib configuration file `rslib.config.ts` in the same directory as `package.json`.

To match the behavior of `tsc`, set `bundle: false` to enable bundleless mode. You can also configure `format` according to the required output format:

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
      bundle: false,
    },
  ],
});
```

## Configuration migration

Here is a mapping of common `tsc` compiler options (usually in `tsconfig.json`) to Rslib configurations:

| tsc (`compilerOptions`)                                                   | Rslib                                                            |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| [declaration](https://www.typescriptlang.org/tsconfig/#declaration)       | [lib.dts](/config/lib/dts.md)                                    |
| [declarationDir](https://www.typescriptlang.org/tsconfig/#declarationDir) | [lib.dts.distPath](/config/lib/dts.md#dtsdistpath)               |
| [outDir](https://www.typescriptlang.org/tsconfig/#outDir)                 | [output.distPath.root](/config/rsbuild/output.md#outputdistpath) |
| [module](https://www.typescriptlang.org/tsconfig/#module)                 | [lib.format](/config/lib/format.md)                              |
| [target](https://www.typescriptlang.org/tsconfig/#target)                 | [lib.syntax](/config/lib/syntax.md)                              |

You do not need to migrate the `compilerOptions.paths` configuration. Rslib automatically recognizes the path aliases in `tsconfig.json`.

## CLI option migration

- `-p`: For projects using a custom tsconfig file (e.g., `tsc -p tsconfig.build.json`), you can configure it via [source.tsconfigPath](/config/rsbuild/source.md#sourcetsconfigpath).

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
      bundle: false,
    },
  ],
  source: {
    tsconfigPath: 'tsconfig.build.json',
  },
});
```

- `-b`: If the original project uses TypeScript's Project References (i.e. `tsc -b`), it can be supported in Rslib by configuring `dts: { build: true }`. It should be noted that `build: true` only takes effect on the generation of type declaration files (`.d.ts`) and will not affect the compilation of JS outputs.

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
      bundle: false,
      dts: {
        build: true,
      },
    },
  ],
});
```

## Handling JSX

For projects containing JSX, you can choose different configurations depending on whether you need to transform JSX syntax.

If you need to transform JSX (e.g., using `"jsx": "react-jsx"` in `tsconfig.json`), you can use the `@rsbuild/plugin-react` to support React compilation and set `output.target` to `'web'`.

First, install the plugin:


```sh [npm]
npm add @rsbuild/plugin-react -D
```

```sh [yarn]
yarn add @rsbuild/plugin-react -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-react -D
```

```sh [bun]
bun add @rsbuild/plugin-react -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-react -D
```

Then, register the plugin in `rslib.config.ts` and configure `output.target`:

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  lib: [
    {
      format: 'esm',
      bundle: false,
    },
  ],
  output: {
    target: 'web',
  },
  plugins: [pluginReact()],
});
```

If you need to preserve JSX (e.g., using `"jsx": "preserve"` in `tsconfig.json`), you can use the `@rsbuild/plugin-react` plugin and set `runtime: 'preserve'`. In addition, you need to configure `output.filename.js` to set the output file extension to `.jsx` to avoid JSX syntax errors.

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  lib: [
    {
      format: 'esm',
      bundle: false,
      output: {
        filename: {
          js: '[name].jsx',
        },
      },
    },
  ],
  output: {
    target: 'web',
  },
  plugins: [
    pluginReact({
      swcReactOptions: {
        runtime: 'preserve',
      },
    }),
  ],
});
```

## Validating results

After completing the above steps, you have finished the basic migration from tsc to Rslib. You can now run the `npm run build` command to build the outputs and verify that the directory structure and extensions of the outputs are consistent with those before the migration.

If you encounter issues during the build process, please debug according to the error logs. You can also enable [debug mode](/guide/basic/configure-rslib.md#debug-mode) to view the final configurations generated by Rslib, or check the `tsconfig.json` configuration to see if any required configurations have not been migrated to Rslib.

## Contents supplement

The current document only covers part of the migration process. If you find suitable content to add, feel free to contribute to the documentation via a pull request 🤝.

> The documentation for Rslib can be found in the [rslib/website](https://github.com/web-infra-dev/rslib/tree/main/website) directory.



---
url: /guide/migration/tsup.md
---

# tsup

This section introduces how to migrate a project using tsup to Rslib.

## Using Agent Skills

If you are using a Coding Agent that supports Skills, install the [migrate-to-rslib](https://github.com/rstackjs/agent-skills#migrate-to-rslib) skill to help with the migration process.


```sh [npx]
npx skills add rstackjs/agent-skills --skill migrate-to-rslib
```

```sh [yarn]
yarn dlx skills add rstackjs/agent-skills --skill migrate-to-rslib
```

```sh [pnpm]
pnpm dlx skills add rstackjs/agent-skills --skill migrate-to-rslib
```

```sh [bunx]
bunx skills add rstackjs/agent-skills --skill migrate-to-rslib
```

```sh [deno]
deno run -A npm:skills add rstackjs/agent-skills --skill migrate-to-rslib
```

After installation, let the Coding Agent guide you through the migration process.

## Installing dependencies

First, you need to replace the npm dependencies of tsup with Rslib's dependencies.

- Remove tsup:


```sh [npm]
npm remove tsup
```

```sh [yarn]
yarn remove tsup
```

```sh [pnpm]
pnpm remove tsup
```

```sh [bun]
bun remove tsup
```

```sh [deno]
deno remove npm:tsup
```

- Install Rslib:


```sh [npm]
npm add @rslib/core -D
```

```sh [yarn]
yarn add @rslib/core -D
```

```sh [pnpm]
pnpm add @rslib/core -D
```

```sh [bun]
bun add @rslib/core -D
```

```sh [deno]
deno add npm:@rslib/core -D
```

## Updating npm scripts

Next, you need to update the npm scripts in your `package.json` to use Rslib's CLI commands.

```diff title="package.json"
{
  "scripts": {
-   "build": "tsup",
-   "build:watch": "tsup --watch",
+   "build": "rslib build",
+   "build:watch": "rslib build --watch"
  }
}
```

## Create configuration file

Create a Rslib configuration file `rslib.config.ts` in the same directory as `package.json`, and add the following content:

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({});
```

## Configuration migration

Here is the corresponding Rslib configuration for tsup configuration:

| tsup          | Rslib                                                                                                            |
| ------------- | ---------------------------------------------------------------------------------------------------------------- |
| banner        | [lib.banner](/config/lib/banner.md)                                                                              |
| bundle        | [lib.bundle](/config/lib/bundle.md)                                                                              |
| clean         | [output.cleanDistPath](/config/rsbuild/output.md#outputcleandistpath)                                            |
| define        | [source.define](/config/rsbuild/source.md#sourcedefine)                                                          |
| dts           | [lib.dts](/config/lib/dts.md)                                                                                    |
| entry         | [source.entry](/config/rsbuild/source.md#sourceentry)                                                            |
| external      | [output.externals](/config/rsbuild/output.md#outputexternals) / [lib.autoExternal](/config/lib/auto-external.md) |
| format        | [lib.format](/config/lib/format.md)                                                                              |
| footer        | [lib.footer](/config/lib/footer.md)                                                                              |
| minify        | [output.minify](/config/rsbuild/output.md#outputminify)                                                          |
| platform      | [output.target](/config/rsbuild/output.md#outputtarget)                                                          |
| plugins       | [plugins](/config/rsbuild/plugins.md)                                                                            |
| sourcemap     | [output.sourceMap](/config/rsbuild/output.md#outputsourcemap)                                                    |
| shims         | [lib.shims](/config/lib/shims.md)                                                                                |
| terserOptions | [output.minify](/config/rsbuild/output.md#outputminify)                                                          |
| tsconfig      | [source.tsconfigPath](/config/rsbuild/source.md#sourcetsconfigpath)                                              |

## Example

Here is an example of migrating a typical `tsup` configuration to Rslib:

```ts title="tsup.config.ts"
import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['./src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  clean: true,
});
```

The corresponding Rslib configuration is as follows:

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
      dts: true,
    },
    {
      format: 'cjs',
      dts: true,
    },
  ],
  source: {
    entry: {
      index: './src/index.ts',
    },
  },
  output: {
    cleanDistPath: true,
  },
});
```

## Validating results

After completing the above steps, you have finished the basic migration from tsup to Rslib. You can now run the `npm run build` command to build the outputs and verify that the directory structure and extensions of the outputs are consistent with those before the migration.

If you encounter issues during the build process, please debug according to the error logs. You can also enable [debug mode](/guide/basic/configure-rslib.md#debug-mode) to view the final configurations generated by Rslib, or check the `tsup.config.ts` configuration to see if any required configurations have not been migrated to Rslib.

## Contents supplement

The current document only covers part of the migration process. If you find suitable content to add, feel free to contribute to the documentation via a pull request 🤝.

> The documentation for Rslib can be found in the [rslib/website](https://github.com/web-infra-dev/rslib/tree/main/website) directory.



---
url: /guide/solution/index.md
---

# Overview

In this chapter, we will introduce how to use Rslib to development libraries for browser and Node.js. We will also cover how to create libraries for different UI frameworks.

## Browser target

When developing a library that runs in the browser, you can package it in both [ESM](/guide/basic/output-format.md#esm--cjs) and [CJS](/guide/basic/output-format.md#esm--cjs) formats for integration with application bundlers. Configuring the package [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) to ESM output allows for better tree shaking. Additionally, you can create [UMD](/guide/basic/output-format.md#umd) format output for direct browser use and even generate [Module Federation ](/guide/advanced/module-federation.md) formats for dynamic loading by other applications. Configure [Browserslist](https://rsbuild.rs/guide/advanced/browserslist) according to the target browser support to determine the downgrade syntax of the output, or add a [polyfill](/guide/advanced/output-compatibility.md) for API compatibility.

When publishing to npm, you can choose not to [minify](/config/rsbuild/output.md#outputminify) your code or to minify it while providing a [sourcemap](/config/rsbuild/output.md#outputsourcemap) to enhance the debugging experience for users of your library. For styling, you can use CSS, or CSS pre-processors like Sass, Less, or Stylus, or apply PostCSS for CSS post-processing. Tools like Tailwind CSS can also help in building your styles. Using CSS Modules to create CSS modules is another option.

In terms of resource management, Rslib handles static assets used in your code, such as SVG and PNG files. You can also build a component library of [React](/guide/solution/react.md), [Preact](https://github.com/rstackjs/rstack-examples/tree/main/rslib/preact), or other frameworks, and use [Storybook](/guide/advanced/storybook.md) for UI component development and testing.

Refer to the solutions in this chapter to learn how to use Rslib to develop browser libraries for different frameworks.



## Node.js target

Rslib set [target](/config/rsbuild/output.md#outputtarget) to `"node"` by default to development libraries for Node.js.

You can create a [pure ESM](/guide/basic/output-format.md#esm--cjs) package or a [dual package](/guide/basic/output-format.md#esm--cjs) that supports both ESM and CJS as needed. In CJS output, `import.meta.url` will be automatically [shimmed](/config/lib/shims.md) for compatibility and `__dirname` and `__filename` got optional ESM shims to ensure proper use across different module system. Node.js's built-in packages will be [externalized by default](/guide/advanced/third-party-deps.md).





---
url: /guide/solution/nodejs.md
---

# Node.js

In this document, you will learn how to build a Node.js library using Rslib. You can check out Node.js related example projects in [Examples](https://github.com/rstackjs/rstack-examples/tree/main/rslib).

## Create Node.js project

You can use `create-rslib` to create a project with Rslib + Node.js. Just execute the following command:


```sh [npm]
npm create rslib@latest
```

```sh [yarn]
yarn create rslib
```

```sh [pnpm]
pnpm create rslib@latest
```

```sh [bun]
bun create rslib@latest
```

Then select `Node.js` when prompted to "Select template".

## Use Rslib in an existing project

Rslib offers seamless support for Node.js projects, allowing you to build Node.js project effortlessly with minimal configuration.

For example, in `rslib.config.ts`:

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      format: 'esm',
      output: {
        distPath: './dist/esm',
      },
    },
    {
      format: 'cjs',
      output: {
        distPath: './dist/cjs',
      },
    },
  ],
});
```

## Target for Node.js

Rslib sets [target](/config/rsbuild/output.md#outputtarget) to `"node"` by default, which is different from the default target of Rsbuild.

When target is set to `"node"`, Rslib adjusts many configurations for Node.js. For example, [output.externals](/config/rsbuild/output.md#outputtarget) will exclude built-in Node.js modules, and [shims](/config/lib/shims.md) will add a shim for `import.meta.url` in CJS output by default.

### Externals

All Node.js [built-in modules](https://nodejs.org/docs/latest/api/) are externalized by default.

### Shims

- `global`: leave it as it is, while it's recommended to use [globalThis](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) instead.
- `__filename`: When outputting in ESM format, replace `__filename` with the result of `fileURLToPath(import.meta.url)`.
- `__dirname`: When outputting in ESM format, replace `__dirname` with the result of `dirname(fileURLToPath(import.meta.url))`.






---
url: /guide/solution/react.md
---

# React

In this document, you will learn how to build a React component library with Rslib. You can check out React related example projects in [Examples](https://github.com/rstackjs/rstack-examples/tree/main/rslib).

## Create React project

You can use `create-rslib` to create a project with Rslib + React. Just execute the following command:


```sh [npm]
npm create rslib@latest
```

```sh [yarn]
yarn create rslib
```

```sh [pnpm]
pnpm create rslib@latest
```

```sh [bun]
bun create rslib@latest
```

Then select `React` when prompted to "Select template".

## Use Rslib in an existing project

To develop a React library, you need to set the [target](/config/rsbuild/output.md#outputtarget) to `"web"` in `rslib.config.ts`. This is crucial because Rslib sets the `target` to `"node"` by default, which differs from the default target of Rsbuild.

To compile React (JSX and TSX), you need to register the Rsbuild [React Plugin](https://rsbuild.rs/plugins/list/plugin-react). The plugin will automatically add the necessary configuration for React builds.

For example, register in `rslib.config.ts`:

```ts title="rslib.config.ts" twoslash
import { defineConfig } from '@rslib/core';
import { pluginReact } from '@rsbuild/plugin-react'; // [!code highlight]

export default defineConfig({
  lib: [
    // ...
  ],
  // [!code highlight:4]
  output: {
    target: 'web',
  },
  plugins: [pluginReact(/** options here */)],
});
```

## JSX transform

- **Type:** `'automatic' | 'classic' | 'preserve'`
- **Default:** `'automatic'`

React introduced a [new JSX transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) in version 17. This new transform removes the need to import `React` when using JSX.

By default, Rslib uses the new JSX transform, which is `runtime: 'automatic'`. It requires at least React `16.14.0` or higher and the `peerDependencies` should be specified as `"react": ">=16.14.0"`.

To change the JSX transform, you can set the [swcReactOptions](https://rsbuild.rs/plugins/list/plugin-react#swcreactoptionsruntime) option in `@rsbuild/plugin-react`.

For example, to use the classic runtime:

```ts title="rslib.config.ts" twoslash
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    // ...
  ],
  output: {
    target: 'web',
  },
  plugins: [
    pluginReact({
      // [!code highlight:3]
      swcReactOptions: {
        runtime: 'classic',
      },
    }),
  ],
});
```

When you need to keep native JSX in the build output, you can set the runtime to `'preserve'` to leave JSX syntax unchanged without transforming it, which is useful for subsequent processing by other bundlers.

::: warning

When using `runtime: 'preserve'`, you must set `bundle: false` to enable [bundleless mode](/guide/basic/output-structure.md#bundle--bundleless) to keep files unbundled.

:::

To emit `.jsx` files, you can configure the JS filename template through [output.filename](/config/rsbuild/output.md#outputfilename) option:

```ts title="rslib.config.ts" twoslash
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    {
      bundle: false,
      format: 'esm',
      // [!code highlight:5]
      output: {
        filename: {
          js: '[name].jsx',
        },
      },
    },
  ],
  plugins: [
    pluginReact({
      swcReactOptions: {
        runtime: 'preserve',
      },
    }),
  ],
});
```

## JSX import source

- **Type**: `string`
- **Default**: `'react'`

When `runtime` is set to `'automatic'`, you can specify the import path of the JSX transform through `importSource`.

For example, when using [Emotion](https://emotion.sh/), you can set `importSource` to `'@emotion/react'`:

```ts title="rslib.config.ts" twoslash
import { pluginReact } from '@rsbuild/plugin-react';
import { defineConfig } from '@rslib/core';

export default defineConfig({
  lib: [
    // ...
  ],
  output: {
    target: 'web',
  },
  plugins: [
    pluginReact({
      // [!code highlight:3]
      swcReactOptions: {
        importSource: '@emotion/react',
      },
    }),
  ],
});
```

## SVGR

Read [SVGR](/guide/advanced/svgr-files.md) for more details.

## Further reading

- [Rsbuild React Plugin](https://rsbuild.rs/plugins/list/plugin-react#swcreactoptionsruntime)
- [SWC Compilation - jsc.transform.react](https://swc.rs/docs/configuration/compilation#jsctransformreact)



---
url: /guide/solution/vue.md
---

# Vue

In this document, you will learn how to build a Vue component library using Rslib. You can check out Vue related example projects in [Examples](https://github.com/rstackjs/rstack-examples/tree/main/rslib).

::: note

1. Only Vue 3 is supported, Vue 2 is not supported.

2. Vue's declaration files are generated by [vue-tsc](https://www.npmjs.com/package/vue-tsc), so [lib.dts](/config/lib/dts.md) / [lib.redirect.dts](/config/lib/redirect.md#redirectdts) / [lib.banner.dts](/config/lib/banner.md#bannerdts) / [lib.footer.dts](/config/lib/footer.md#bannerdts) are not effective in Vue projects.

:::

## Create Vue project

You can use `create-rslib` to create a project with Rslib + Vue. Just execute the following command:


```sh [npm]
npm create rslib@latest
```

```sh [yarn]
yarn create rslib
```

```sh [pnpm]
pnpm create rslib@latest
```

```sh [bun]
bun create rslib@latest
```

Then select `Vue` when prompted to "Select template".

## Use Rslib in an existing project

For developing Vue components, you need to set the [target](/config/rsbuild/output.md#outputtarget) to `"web"` in `rslib.config.ts`. This is crucial because Rslib sets `target` to `"node"` by default, which is different from Rsbuild's default target value.

To compile Vue (.vue single-file components), you need to register the [rsbuild-plugin-unplugin-vue](https://github.com/rstackjs/rsbuild-plugin-unplugin-vue) plugin based on [unplugin-vue](https://github.com/unplugin/unplugin-vue). This plugin will automatically add the necessary configurations for Vue build.

For example, register in `rslib.config.ts`:

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
import { pluginUnpluginVue } from 'rsbuild-plugin-unplugin-vue'; // [!code highlight]

export default defineConfig({
  lib: [
    // ...
  ],
  // [!code highlight:4]
  output: {
    target: 'web',
  },
  plugins: [pluginUnpluginVue(/** options here */)],
});
```

::: note
Currently, the [rsbuild-plugin-unplugin-vue](https://github.com/rstackjs/rsbuild-plugin-unplugin-vue) plugin does not support packaging Vue SFC [scoped CSS](https://vuejs.org/api/sfc-css-features#scoped-css) styles. You can choose styling solutions like Less or Sass.
:::

For more configuration options, please refer to the [rsbuild-plugin-unplugin-vue](https://github.com/rstackjs/rsbuild-plugin-unplugin-vue) plugin documentation.



---
url: /guide/start/ai.md
---

# AI

To help AI better understand Rslib's features, configuration, and best practices so it can provide more accurate assistance during day-to-day development and troubleshooting, Rslib provides the following capabilities:

- [Agent Skills](#agent-skills)
- [llms.txt](#llmstxt)
- [Markdown docs](#markdown-docs)
- [AGENTS.md](#agentsmd)

## Agent Skills

Agent Skills are domain-specific knowledge packs that can be installed into Agents, enabling them to give more accurate and professional suggestions or perform actions in specific scenarios.

In the [rstackjs/agent-skills](https://github.com/rstackjs/agent-skills) repository, there are many skills for the Rstack ecosystem. The skills related to Rslib include:

- [rslib-best-practices](https://github.com/rstackjs/agent-skills#rslib-best-practices): Best practices for Rslib.
- [migrate-to-rslib](https://github.com/rstackjs/agent-skills#migrate-to-rslib): Migrate existing tsc or tsup projects to Rslib.

In Coding Agents that support skills, you can use the [skills](https://www.npmjs.com/package/skills) package to install a specific skill with the following command:


```sh [npx]
npx skills add rstackjs/agent-skills --skill migrate-to-rslib
```

```sh [yarn]
yarn dlx skills add rstackjs/agent-skills --skill migrate-to-rslib
```

```sh [pnpm]
pnpm dlx skills add rstackjs/agent-skills --skill migrate-to-rslib
```

```sh [bunx]
bunx skills add rstackjs/agent-skills --skill migrate-to-rslib
```

```sh [deno]
deno run -A npm:skills add rstackjs/agent-skills --skill migrate-to-rslib
```

After installation, simply use natural language prompts to trigger the skill, for example:

```
Help me migrate this tsc project to Rslib
```

## llms.txt

[llms.txt](https://llmstxt.org/) is a standard that helps LLMs discover and use project documentation. Rslib follows this standard and publishes the following two files:

- [llms.txt](https://rslib.rs/llms.txt): A structured index file containing the titles, links, and brief descriptions of all documentation pages.

```
https://rslib.rs/llms.txt
```

- [llms-full.txt](https://rslib.rs/llms-full.txt): A full-content file that concatenates the complete content of every documentation page into a single file.

```
https://rslib.rs/llms-full.txt
```

You can choose the file that best fits your use case:

- `llms.txt` is smaller and consumes fewer tokens, making it suitable for AI to fetch specific pages on demand.
- `llms-full.txt` contains the complete documentation content, so AI doesn't need to follow individual links — ideal when you need AI to have a comprehensive understanding of Rslib, though it consumes more tokens and is best used with AI tools that support large context windows.

## Markdown docs

Every Rslib documentation page has a corresponding `.md` plain-text version that can be provided directly to AI. On any doc page, you can click “Copy Markdown” or “Copy Markdown Link” under the title to get the Markdown content or link.

```
https://rslib.rs/guide/start/index.md
```

Providing the Markdown link or content allows AI to focus on a specific chapter, which is useful for targeted troubleshooting or looking up a particular topic.

## AGENTS.md

When you create a new project with [create-rslib](https://www.npmjs.com/package/create-rslib), the generated project includes an `AGENTS.md` file. This file follows the [AGENTS.md](https://agents.md/) specification and provides key project information to Agents.

Example `AGENTS.md` content:

```markdown wrapCode
# AGENTS.md

You are an expert in JavaScript, Rspack, Rsbuild, Rslib, and library development. You write maintainable, performant, and accessible code.

## Commands

- `npm run build` - Build the library for production
- `npm run dev` - Turn on watch mode, watch for changes and rebuild the library

## Docs

- Rslib: https://rslib.rs/llms.txt
- Rsbuild: https://rsbuild.rs/llms.txt
- Rspack: https://rspack.rs/llms.txt
```

You can also customize it for your project, adding more details about the project structure, overall architecture, and other relevant information so Agents can better understand your project.

::: tip

If you are using Claude Code, you can create a `CLAUDE.md` file and reference the `AGENTS.md` file in it.

```markdown title="CLAUDE.md"
@AGENTS.md
```

:::



---
url: /guide/start/glossary.md
---

# Glossary

## ESM

ESM stands for [ECMAScript modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules), which is a modern module system introduced in ES2015 that allows JavaScript code to be organized into reusable, self-contained modules. ESM is now the standard for both [browser](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) and [Node.js](https://nodejs.org/api/esm.html) environments, replacing older module systems like [CommonJS (CJS)](https://nodejs.org/api/modules.html) and [AMD](https://requirejs.org/docs/whyamd.html).

## CJS

CJS stands for [CommonJS modules](https://nodejs.org/api/modules.html#modules-commonjs-modules), which is a module system used in JavaScript, particularly in server-side environments like Node.js. It was created to allow JavaScript to be used outside of the browser by providing a way to manage modules and dependencies.

## UMD

UMD stands for [Universal Module Definition](https://github.com/umdjs/umd), a pattern for writing JavaScript modules that can work universally across different environments, such as both the browser and Node.js. Its primary goal is to ensure compatibility with the most popular module systems, including AMD (Asynchronous Module Definition), CommonJS (CJS), and browser globals.

## Bundleless

Bundleless means that each source file is compiled and built separately, but not bundled together. Each output file can be found with its corresponding source code file. The process of bundleless build can also be understood as the process of code transformation of source files only.

## Module Federation

Module Federation is an architectural pattern for JavaScript application decomposition (similar to microservices on the server-side), allowing you to share code and resources between multiple JavaScript applications (or micro-frontends).

See [Module Federation](https://rsbuild.rs/guide/advanced/module-federation) for more details.

## More

See more glossary in [Rsbuild - Glossary](https://rsbuild.rs/guide/start/glossary) and [Rspack - Glossary](https://rspack.rs/misc/glossary).



---
url: /guide/start/index.md
---

# Introduction

Rslib is a library development tool that leverages the well-designed configurations and plugins of [Rsbuild](https://rsbuild.rs), empowering library developers to take advantage of the extensive knowledge and ecosystem of webpack and Rspack.

Rslib provides a comprehensive set of build features for library development, including:

- **Compilation of diverse languages**: TypeScript, JSX, Sass, Less, CSS Modules, Wasm, and more.
- **Flexible build modes**: Bundle and bundleless options to meet varying needs.
- **Multiple output formats**: ESM, CJS, and UMD for maximum compatibility.
- **Declaration file generation**: Including isolated declarations.
- **Advanced features**: Module Federation, asset compression, PostCSS, Lightning CSS, and more.

## ✨ Why Rslib

During the development of component or utility libraries, developers need to focus not only on implementing project logic, but also on handling tasks that are separate from the code itself, such as building, debugging, documentation, and testing. Although many community tools and solutions can address some of these needs, developers who are not familiar with them often face cumbersome configuration requirements or need to coordinate multiple tools to meet these demands.

Based on Rspack and Rsbuild, Rslib offers a comprehensive solution tailored to the diverse requirements of library development, effectively addressing issues such as incomplete tool ecosystems, high costs for module standard compatibility, and insufficient output optimization. Rslib optimizes webpack's limited support for library ESM outputs, reducing redundant runtime code and generating high-quality ESM outputs that are tree-shaking friendly for library consumers. Additionally, Rslib fully leverages the build performance advantages of Rspack and capitalizes the strengths of both the webpack and Rspack ecosystems to robustly support features such as Module Federation.

Furthermore, Rslib utilizes Rsbuild's out-of-the-box configuration to facilitate configuration sharing between application and library projects, resolving the challenge of reusing build configurations between application projects and library projects, thereby reducing the configuration overhead for developers and improving development efficiency and experience.

In the future, Rslib will explore additional possibilities by leveraging the new features of Rspack.

## 🔥 Features

Rslib has the following features:

- **Easy to Configure**: Rslib aims to simplify library development by offering ready-to-use build capabilities, enabling developers to kickstart their library projects with minimal configuration.
- **Performance Oriented**: Rslib integrates high-performance Rust-based tools from the community, including [Rspack](https://rspack.rs/), [SWC](https://swc.rs/) and [Lightning CSS](https://lightningcss.dev/), to deliver first-class build speed and development experience.
- **Plugin Ecosystem**: Powered by Rsbuild, Rslib benefits from a lightweight plugin system and a collection of high-quality official plugins. Furthermore, Rsbuild's compatibility with most webpack plugins and all Rspack plugins allows library developers to seamlessly integrate existing community or in-house plugins into their library projects.

## 🎯 Ecosystem

Rslib is implemented based on Rsbuild and fully reuses the capabilities and ecosystem of Rsbuild.

The following diagram illustrates the relationship between Rslib and other tools in the ecosystem:

![Rspack stack layers](https://assets.rspack.rs/rsbuild/assets/rspack-stack-layers.png)

## 🦀 Rstack

Rstack is a unified JavaScript toolchain centered on Rspack, with high performance and consistent architecture.

| Name                                                  | Description              | Version                                                                                                                                                                          |
| ----------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Rspack](https://github.com/web-infra-dev/rspack)     | Bundler                  | <a href="https://npmjs.com/package/@rspack/core"><img src="https://img.shields.io/npm/v/@rspack/core?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" /></a>     |
| [Rsbuild](https://github.com/web-infra-dev/rsbuild)   | Build tool               | <a href="https://npmjs.com/package/@rsbuild/core"><img src="https://img.shields.io/npm/v/@rsbuild/core?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" /></a>   |
| [Rslib](https://github.com/web-infra-dev/rslib)       | Library development tool | <a href="https://npmjs.com/package/@rslib/core"><img src="https://img.shields.io/npm/v/@rslib/core?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" /></a>       |
| [Rspress](https://github.com/web-infra-dev/rspress)   | Static site generator    | <a href="https://npmjs.com/package/@rspress/core"><img src="https://img.shields.io/npm/v/@rspress/core?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" /></a>   |
| [Rsdoctor](https://github.com/web-infra-dev/rsdoctor) | Build analyzer           | <a href="https://npmjs.com/package/@rsdoctor/core"><img src="https://img.shields.io/npm/v/@rsdoctor/core?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" /></a> |
| [Rstest](https://github.com/web-infra-dev/rstest)     | Testing framework        | <a href="https://npmjs.com/package/@rstest/core"><img src="https://img.shields.io/npm/v/@rstest/core?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" /></a>     |
| [Rslint](https://github.com/web-infra-dev/rslint)     | Linter                   | <a href="https://npmjs.com/package/@rslint/core"><img src="https://img.shields.io/npm/v/@rslint/core?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" /></a>     |

## 🔗 Links

- [awesome-rstack](https://github.com/rstackjs/awesome-rstack): A curated list of awesome things related to Rstack.
- [rstack-examples](https://github.com/rstackjs/rstack-examples): Examples for Rstack.
- [storybook-rsbuild](https://github.com/rstackjs/storybook-rsbuild): Storybook builder powered by Rsbuild.
- [rsbuild-plugin-template](https://github.com/rstackjs/rsbuild-plugin-template): Use this template to create your own Rsbuild plugin.
- [rstack-design-resources](https://github.com/rstackjs/rstack-design-resources): Design resources for Rstack.

## 🧑‍💻 Community

Come and chat with us on [Discord](https://discord.gg/XsaKEEk4mW)! The Rstack team and users are active there, and we're always looking for contributions.



---
url: /guide/start/npm-packages.md
---

# Packages

This document showcases all the npm package information maintained by Rslib team.

## @rslib/core

![](https://img.shields.io/npm/v/@rslib/core?style=flat-square\&colorA=564341\&colorB=F8F5FF)

Rslib core package that provides CLI commands and build capabilities based on Rsbuild.

- [npm](https://npmjs.com/package/@rslib/core)
- [Source Code](https://github.com/web-infra-dev/rslib/tree/main/packages/core)

## rsbuild-plugin-dts

![](https://img.shields.io/npm/v/rsbuild-plugin-dts?style=flat-square\&colorA=564341\&colorB=F8F5FF)

Rsbuild plugin that supports emitting declaration files for TypeScript.

- [npm](https://npmjs.com/package/rsbuild-plugin-dts)
- [Source Code](https://github.com/web-infra-dev/rslib/tree/main/packages/plugin-dts)

## create-rslib

![](https://img.shields.io/npm/v/create-rslib?style=flat-square\&colorA=564341\&colorB=F8F5FF)

Used to create a new Rslib project.

- [npm](https://npmjs.com/package/create-rslib)
- [Source Code](https://github.com/web-infra-dev/rslib/tree/main/packages/create-rslib)



---
url: /guide/start/quick-start.md
---

# Quick start

## Environment preparation

Rslib supports using [Node.js](https://nodejs.org/), [Deno](https://deno.com/), or [Bun](https://bun.sh/) as the JavaScript runtime.

Use one of the following installation guides to set up a runtime:

- [Install Node.js](https://nodejs.org/en/download)
- [Install Bun](https://bun.com/docs/installation)
- [Install Deno](https://docs.deno.com/runtime/getting_started/installation/)

:::tip Version requirements

- Rslib >= 0.20 requires Node.js version 20.19+, 22.12+.
- Rslib \< 0.20 requires Node.js 18.12.0 or higher.

:::

## Creating an Rslib project

Use [`create-rslib`](https://www.npmjs.com/package/create-rslib) to create a new Rslib project. Run the following command:


```sh [npm]
npm create rslib@latest
```

```sh [yarn]
yarn create rslib
```

```sh [pnpm]
pnpm create rslib@latest
```

```sh [bun]
bun create rslib@latest
```

```sh [deno]
deno init --npm rslib@latest
```

Follow the prompts step by step. During the creation process, you can choose whether to add optional tools such as TypeScript, ESLint, etc.

After creating the project, do the following:

- Run `git init` to initialize a Git repository.
- Run `npm install` (or your package manager's install command) to install dependencies.
- Run `npm run dev` to start watch mode and begin development.

### Templates

When creating a project, you can choose from the following templates provided by `create-rslib`:

| Template                     | Description                  |
| ---------------------------- | ---------------------------- |
| Node.js dual ESM/CJS package | Node.js dual ESM/CJS package |
| Node.js pure ESM package     | Node.js pure ESM package     |
| React                        | React component library      |
| Vue                          | Vue component library        |

### Optional tools

`create-rslib` can help you set up some commonly used tools, including [Biome](https://biomejs.dev/), [ESLint](https://eslint.org/), [Prettier](https://prettier.io/), [Rspress](https://rspress.rs/), [Storybook](https://storybook.js.org/) and [Rstest](https://rstest.rs/). Use the arrow keys to navigate and the space bar to select. Press Enter without selecting anything to skip these tools.

- Rspress is available for React + TypeScript template, used for generating component documentation sites.
- Storybook is available for web targeted templates (React, Vue), used for component development and preview.
- Rstest is available for all templates, used for testing.

```text
◆  Select additional tools (Use <space> to select, <enter> to continue)
│  ◻ Biome - linting & formatting
│  ◻ ESLint - linting
│  ◻ Prettier - formatting
│  ◻ Rspress - documentation
│  ◻ Storybook - component development
│  ◻ Rstest - testing
```

:::tip
Biome provides similar linting and formatting features to ESLint and Prettier. If you select Biome, you typically won't need to choose ESLint or Prettier as well.
:::

### Current directory

To create a project in the current directory, set the target folder to `.`:

```text
◆  Create Rslib Project
│
◇  Project name or path
│  .
│
◇  "." is not empty, please choose:
│  Continue and override files
```

### Non-interactive mode

[create-rslib](https://www.npmjs.com/package/create-rslib) supports a non-interactive mode via command-line options. This mode skips prompts and creates the project directly, which is useful for scripts, CI, and automation.

For example, the following command creates a React project in the `my-project` directory:

```bash
npx -y create-rslib@latest my-project --template react

# Using abbreviations
npx -y create-rslib@latest my-project -t react

# Specify multiple tools
npx -y create-rslib@latest my-project -t react --tools rstest,biome
```

All CLI flags supported by `create-rslib`:

```text
Usage: create-rslib [dir] [options]

Options:

  -h, --help            display help for command
  -d, --dir <dir>       create project in specified directory
  -t, --template <tpl>  specify the template to use
  --tools <tool>        add additional tools, comma separated
  --override            override files in target directory
  --packageName <name>  specify the package name

Available templates:
  node-dual-js, node-dual-ts, node-esm-js, node-esm-ts, react-js, react-ts, vue-js, vue-ts

Optional tools:
  biome, eslint, prettier, rspress, storybook, rstest
```

## Migrate from existing projects

To migrate from an existing project to Rslib, refer to the following guides:

- [Migrating from tsup](/guide/migration/tsup.md)
- [Migrating from Modern.js Module](/guide/migration/modernjs-module.md)

### Other projects

For other types of projects, you can manually install the [@rslib/core](https://www.npmjs.com/package/@rslib/core) package:


```sh [npm]
npm add @rslib/core -D
```

```sh [yarn]
yarn add @rslib/core -D
```

```sh [pnpm]
pnpm add @rslib/core -D
```

```sh [bun]
bun add @rslib/core -D
```

```sh [deno]
deno add npm:@rslib/core -D
```

Then refer to the guide and documentation to enable the features you need:

- See [CLI](/guide/basic/cli.md) to learn about available CLI commands.
- See [Configure Rslib](/guide/basic/configure-rslib.md) to configure Rslib.



---
url: /config/index.md
---

# Config overview

This page lists all the configurations for Rslib. See [Configure Rslib](/guide/basic/configure-rslib.md) for detail.

### [Lib configurations](/config/lib/index.md)

- [lib.autoExtension](/config/lib/auto-extension.md)
- [lib.autoExternal](/config/lib/auto-external.md)
- [lib.banner](/config/lib/banner.md)
- [lib.bundle](/config/lib/bundle.md)
- [lib.dts](/config/lib/dts.md)
- [lib.experiments](/config/lib/experiments.md)
- [lib.externalHelpers](/config/lib/external-helpers.md)
- [lib.footer](/config/lib/footer.md)
- [lib.format](/config/lib/format.md)
- [lib.id](/config/lib/id.md)
- [lib.outBase](/config/lib/out-base.md)
- [lib.redirect](/config/lib/redirect.md)
- [lib.shims](/config/lib/shims.md)
- [lib.syntax](/config/lib/syntax.md)
- [lib.umdName](/config/lib/umd-name.md)

### [Rsbuild configurations](/config/rsbuild/index.md)

- [logLevel](/config/rsbuild/log-level.md)
- [output](/config/rsbuild/output.md)
- [performance](/config/rsbuild/performance.md)
- [plugins](/config/rsbuild/plugins.md)
- [resolve](/config/rsbuild/resolve.md)
- [source](/config/rsbuild/source.md)
- [tools](/config/rsbuild/tools.md)



---
url: /config/lib/auto-extension.md
---

# lib.autoExtension

- **Type:** `boolean`
- **Default:** `true`
- **CLI:** `--auto-extension` / `--no-auto-extension`

Whether to automatically set the file extension based on the [`format`](/config/lib/format.md) option in the JavaScript output files.

## Default extension

By default that when `autoExtension` is set to `true`, the file extension will be:

- `.js` with `esm` format and `.cjs` with `cjs` format when `type: module` in `package.json`.

- `.js` with `cjs` format and `.mjs` with `esm` format when `type: commonjs` or no `type` field in `package.json`.

When `autoExtension` is set to `false`, the file extension will be default to `.js`.

## Customize extension

You can set `autoExtension` to `false` and use [output.filename](https://rsbuild.rs/config/output/filename) to customize the JavaScript output files.

```ts title="rslib.config.ts"
export default defineConfig({
  lib: [
    {
      format: 'cjs',
      autoExtension: false,
      output: {
        filename: {
          js: '[name].cjs',
        },
      },
    },
    {
      format: 'esm',
      output: {
        filename: {
          js: '[name].mjs',
        },
      },
    },
  ],
});
```



---
url: /config/lib/auto-external.md
---

# lib.autoExternal

:::info

`autoExternal` is a specific configuration for bundle mode. It will not take effect in bundleless mode (set [lib.bundle](/config/lib/bundle.md) to `false`) since deps will not be bundled in bundleless mode.

:::

- **Type:**

```ts
type AutoExternal =
  | boolean
  | {
      dependencies?: boolean;
      optionalDependencies?: boolean;
      devDependencies?: boolean;
      peerDependencies?: boolean;
    };
```

- **Default:**
  - `true` when [format](/config/lib/format.md) is `cjs` or `esm`
  - `false` when [format](/config/lib/format.md) is `umd` or `mf`
- **CLI:** `--auto-external` / `--no-auto-external`

Whether to automatically externalize dependencies of different dependency types and do not bundle them.

## Object type

### autoExternal.dependencies

- **Type:** `boolean`
- **Default:** `true`

Whether to automatically externalize dependencies of type `dependencies`.

### autoExternal.optionalDependencies

- **Type:** `boolean`
- **Default:** `true`

Whether to automatically externalize dependencies of type `optionalDependencies`.

### autoExternal.peerDependencies

- **Type:** `boolean`
- **Default:** `true`

Whether to automatically externalize dependencies of type `peerDependencies`.

### autoExternal.devDependencies

- **Type:** `boolean`
- **Default:** `false`

Whether to automatically externalize dependencies of type `devDependencies`.

## Default value

The default value of `autoExternal` is `true`, which means the following dependency types will **not be bundled**:

- `dependencies`
- `optionalDependencies`
- `peerDependencies`

And the following dependency types will be **bundled**:

- `devDependencies`

This configuration is equivalent to the following object type:

```ts
export default {
  lib: [
    {
      format: 'esm',
      autoExternal: {
        dependencies: true,
        optionalDependencies: true,
        peerDependencies: true,
        devDependencies: false,
      },
    },
  ],
};
```

## Example

### Customize externalized dependency types

To disable the processing of a specific type of dependency, you can configure `autoExternal` as an object like this:

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      autoExternal: {
        dependencies: false,
        peerDependencies: false,
      },
    },
  ],
};
```

### Disable default behavior

If you want to disable the default behavior, you can set `autoExternal` to `false`:

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      autoExternal: false,
    },
  ],
};
```

For more details about handling third-party dependencies, please refer to [Handle Third-party Dependencies](/guide/advanced/third-party-deps.md).



---
url: /config/lib/banner.md
---

# lib.banner

- **Type:**

```ts
type Banner = {
  js?: string;
  css?: string;
  dts?: string;
};
```

- **Default:** `{}`

Inject content into the top of each JavaScript, CSS or declaration output file.

## Object type

### banner.js

- **Type:** `string`
- **Default:** `undefined`

Inject content into the top of each JavaScript output file.

### banner.css

- **Type:** `string`
- **Default:** `undefined`

Inject content into the top of each CSS output file.

### banner.dts

- **Type:** `string`
- **Default:** `undefined`

Inject content into the top of each declaration output file.

## Notice

The banner content in JavaScript and CSS file is based on the [BannerPlugin](https://rspack.rs/plugins/webpack/banner-plugin) of Rspack. You should notice the following points:

- `raw: true` is enabled by default, so the banner content will be injected as a raw string instead of wrapping in a comment. So if you want to inject a comment, you should add `/*` and `*/` or other comment syntax by yourself.
- The `stage` option is set to the stage after the JavaScript and CSS files are optimized, thus preventing the banner content from being optimized away.

## Customize banner content

If the above default settings cannot meet your requirements, you can customize the banner content through `tools.rspack.plugins` to add a [BannerPlugin](https://rspack.rs/plugins/webpack/banner-plugin) instance with the corresponding options.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      // ...
      tools: {
        rspack: {
          plugins: [
            new rspack.BannerPlugin({
              // ... options
            }),
          ],
        },
      },
    },
  ],
};
```

:::warning

The banner content in declaration files is handled differently from JavaScript and CSS output files. It is written directly using the file system API, so setting `BannerPlugin` will not affect it.

:::



---
url: /config/lib/bundle.md
---

# lib.bundle

- **Type:** `boolean`
- **Default:** `true`
- **CLI:** `--bundle` / `--no-bundle`

Specify whether to bundle the library, which is known as bundle mode when `bundle` is set to `true`, and bundleless mode when set to `false`.

See [bundle / bundleless](/guide/basic/output-structure.md#bundle--bundleless) for more details.

## Set entry

We should specify the entry file for the build.

### bundle: true

When `bundle` is set to `true`, the entry should be set to the entry file. The default entry in bundle mode is `src/index.(ts|js|tsx|jsx|mjs|cjs)`. You should make sure that the entry file exists, or customize the entry through the [source.entry](https://rsbuild.rs/config/source/entry) configuration.

**Example:**

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'cjs',
      bundle: true,
    },
  ],
  source: {
    entry: {
      index: './foo/index.ts',
    },
  },
};
```

### bundle: false

When `bundle` is set to `false`, the entry should be set to a [glob pattern](https://github.com/micromatch/picomatch#globbing-features) to include all the files. The default entry in bundleless mode is `src/**`.

**Example:**

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'cjs',
      bundle: false,
    },
  ],
  source: {
    entry: {
      index: './foo/**',
    },
  },
};
```

You can also use with an exclamation mark to exclude some files. For example, exclude test files within the `src` folder:

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'cjs',
      bundle: false,
    },
  ],
  source: {
    entry: {
      index: ['./src/**', '!src/**/*.test.ts'],
    },
  },
};
```

::: note

If [declaration files generation](/config/lib/dts.md) is enabled, remember to set [exclude](https://www.typescriptlang.org/tsconfig/#exclude) field in `tsconfig.json` to avoid generating TypeScript declaration files for the corresponding files.

For example, exclude test files within the `src` folder:

```json
// tsconfig.json
{
  "include": ["src"],
  "exclude": ["src/**/*.test.ts"]
}
```

:::

## Example

For below file structure of source code:

```
.
├── src
│   ├── index.ts
│   ├── foo.ts
│   └── bar.ts
└── package.json
```

### bundle: true

```ts title="rslib.config.ts"
export default defineConfig({
  lib: [
    {
      format: 'cjs',
      bundle: true,
    },
  ],
});
```

When `bundle` is set to `true`, as known as bundle mode, Rslib will bundle the library into a single file.

```diff
  .
+ ├── dist
+ │   └── index.js
  ├── src
  │   ├── index.ts
  │   ├── foo.ts
  │   └── bar.ts
  └── package.json
```

### bundle: false

```ts title="rslib.config.ts"
export default defineConfig({
  lib: [
    {
      format: 'cjs',
      bundle: false,
    },
  ],
  source: {
    entry: {
      index: ['./src/**'],
    },
  },
});
```

When `bundle` is set to `false`, as known as bundleless mode, Rslib will transform the code into multiple files.

```diff
  .
+ ├── dist
+ │   ├── index.js
+ │   ├── foo.js
+ │   └── bar.js
  ├── src
  │   ├── index.ts
  │   ├── foo.ts
  │   └── bar.ts
  └── package.json
```



---
url: /config/lib/dts.md
---

# lib.dts

- **Type:**

```ts
type Dts =
  | {
      bundle?: boolean | { bundledPackages?: string[] };
      distPath?: string;
      build?: boolean;
      abortOnError?: boolean;
      autoExtension?: boolean;
      alias?: Record<string, string>;
      tsgo?: boolean;
    }
  | boolean;
```

- **Default:** `undefined`
- **CLI:** `--dts` / `--no-dts`

Configure the generation of the TypeScript declaration files.

## Boolean type

Declaration files generation is an optional feature, you can set `dts: true` to enable [bundleless declaration files](/guide/advanced/dts.md#bundleless-declaration-files) generation.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      dts: true, // [!code highlight]
    },
  ],
};
```

If you want to disable declaration files generation, you can set `dts: false` or do not specify the `dts` option.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      dts: false, // [!code highlight]
    },
  ],
};
```

## Object type

If you want to customize the declaration files generation, you can set the `dts` option to an object.

### dts.bundle

- **Type:** `boolean | { bundledPackages?: string[] }`
- **Default:** `false`

Whether to bundle the declaration files.

If you want to [bundle declaration files](/guide/advanced/dts.md#bundle-declaration-files) files, you should:

1. Install [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor) as a development dependency, which is the underlying tool used for bundling declaration files.


```sh [npm]
npm add @microsoft/api-extractor -D
```

```sh [yarn]
yarn add @microsoft/api-extractor -D
```

```sh [pnpm]
pnpm add @microsoft/api-extractor -D
```

```sh [bun]
bun add @microsoft/api-extractor -D
```

```sh [deno]
deno add npm:@microsoft/api-extractor -D
```

2. Set `dts.bundle` to `true`.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      // [!code highlight:3]
      dts: {
        bundle: true,
      },
    },
  ],
};
```

#### dts.bundle.bundledPackages

- **Type:** `string[]`

Specifies the dependencies whose declaration files should be bundled. This configuration is passed to the [bundledPackages](https://api-extractor.com/pages/configs/api-extractor_json/#bundledpackages) option of `@microsoft/api-extractor`.

By default, Rslib determines externalized dependencies based on the following configurations. For details, refer to [Handle third-party dependencies](/guide/advanced/third-party-deps.md).

- [autoExternal](/config/lib/auto-external.md) configuration
- [output.externals](/config/rsbuild/output.md#outputexternals) configuration

Direct dependencies (declared in `package.json`) that are not externalized will be automatically added to `bundledPackages`, and their declaration files will be bundled into the final output.

When the default behavior does not meet the requirements, you can explicitly specify the dependencies whose declaration files need to be bundled through `dts.bundle.bundledPackages`. After setting this configuration, the above default behavior will be completely overwritten.

This is typically used for bundling transitive dependencies (dependencies of direct dependencies). For example, if the project directly depends on `foo`, and `foo` depends on `bar`, you can bundle both `foo` and `bar`'s declaration files as follows:

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      dts: {
        // [!code highlight:3]
        bundle: {
          bundledPackages: ['foo', 'bar'],
        },
      },
    },
  ],
};
```

::: note
`bundledPackages` can be specified with the [minimatch](https://www.npmjs.com/package/minimatch) syntax, but will only match the declared direct dependencies in `package.json`.
:::

### dts.distPath

- **Type:** `string`

The output directory of declaration files.

#### Default value

The default value follows the priority below:

1. The `dts.distPath` value in the current lib configuration.
2. The `declarationDir` value in the `tsconfig.json` file.
3. The [output.distPath](/config/rsbuild/output.md#outputdistpath) or [output.distPath.root](/config/rsbuild/output.md#outputdistpath) value in the current lib configuration.

#### Example

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      // [!code highlight:3]
      dts: {
        distPath: './dist-types',
      },
    },
  ],
};
```

### dts.build

- **Type:** `boolean`
- **Default:** `false`

Whether to generate declaration files with building the project references. This is equivalent to using the `--build` flag with the `tsc` command. See [Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) for more details.

When the project references are configured but the referenced project has not been built separately (for example, the source code of other projects is directly referenced in monorepo, but the corresponding declaration file is missing in the project), this option needs to be enabled to ensure that the declaration files of referenced projects can be generated correctly, thereby ensuring the integrity of the type system.

::: note

- This option can only be used when [dts.bundle](/config/lib/dts.md#dtsbundle) is `false`.
- When this option is enabled, `declarationDir` or `outDir` needs to be explicitly set in `tsconfig.json` to meet build requirements.

:::

### dts.abortOnError

- **Type:** `boolean`
- **Default:** `true`

Whether to abort the build process when an error occurs during declaration files generation.

By default, type errors will cause the build to fail.

When `abortOnError` is set to `false` like below, the build will still succeed even if there are type issues in the code.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      // [!code highlight:3]
      dts: {
        abortOnError: false,
      },
    },
  ],
};
```

::: warning

When this configuration is disabled, there is no guarantee that the type files will be generated correctly.

:::

### dts.autoExtension

- **Type:** `boolean`
- **Default:** `false`

Whether to automatically set the declaration file extension based on the [format](/config/lib/format.md) option.

#### Default extension

By default that when `dts.autoExtension` is `false`, the declaration file extension will be `.d.ts`.

When `dts.autoExtension` is set to `true`, the declaration file extension will be:

- `.d.ts` with `esm` format and `.d.cts` with `cjs` format when `type: module` in `package.json`.

- `.d.ts` with `cjs` format and `.d.mts` with `esm` format when `type: commonjs` or no `type` field in `package.json`.

::: note

1. It follows the same logic as [lib.autoExtension](/config/lib/auto-extension.md), but the default value is different since the declaration file extension may cause some issues with different module resolution strategies.

2. Type declaration import extensions are controlled by the [redirect.dts.extension](/config/lib/redirect.md#redirectdtsextension) configuration.

3. When [dts.tsgo](/config/lib/dts.md#dtstsgo) is enabled, if the project also enables [dts.build](/config/lib/dts.md#dtsbuild) or emits declaration files with different extensions to the same directory, `dts.autoExtension` may not work correctly.

:::

### dts.alias

- **Type:** `Record<string, string>`
- **Default:** `{}`

Configure the path alias for declaration files.

The path aliases configured in `dts.alias` should be resolved relative to the directory specified by `compilerOptions.baseUrl` in `tsconfig.json`. These aliases will be merged with `compilerOptions.paths`, and `dts.alias` takes higher precedence.

In most cases, you don't need to use `dts.alias`, but consider using it when you need to use path alias only in declaration files without wanting to affect JavaScript outputs. For example, map the declaration file of `foo` to `./compiled/foo`.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      // [!code highlight:5]
      dts: {
        alias: {
          foo: './compiled/foo',
        },
      },
    },
  ],
};
```

At this time, when [redirect.dts.path](/config/lib/redirect.md#redirectdtspath) is enabled, the import path of `foo` in the declaration file will be redirected to `./compiled/foo`.

```diff title="index.d.ts"
- export * from 'foo';
+ export * from './compiled/foo';
```

### dts.tsgo

- **Type:** `boolean`
- **Default:** `false`

Whether to generate declaration files with [tsgo](https://github.com/microsoft/typescript-go), which can provide faster generation of declaration files, especially for large projects.

::: tip

This feature is currently an **experimental feature**. Since tsgo is still in the **experimental stage**, there may be some bugs and unresolved issues or limitations. So, make sure to fully test it in your project before enabling this option.

:::

To enable this option, you need to:

1. Install [@typescript/native-preview](https://www.npmjs.com/package/@typescript/native-preview) as a development dependency.


```sh [npm]
npm add @typescript/native-preview -D
```

```sh [yarn]
yarn add @typescript/native-preview -D
```

```sh [pnpm]
pnpm add @typescript/native-preview -D
```

```sh [bun]
bun add @typescript/native-preview -D
```

```sh [deno]
deno add npm:@typescript/native-preview -D
```

::: tip Version requirements

`@typescript/native-preview` requires Node.js 20.6.0 or higher.

:::

2. Configure in the Rslib config file:

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      dts: {
        tsgo: true, // [!code highlight]
      },
    },
  ],
};
```

3. In order to ensure the consistency of local development, you need to install the corresponding [VS Code Preview Extension](https://marketplace.visualstudio.com/items?itemName=TypeScriptTeam.native-preview) and add the following configuration in the VS Code settings:

```json title=".vscode/settings.json"
{
  "typescript.experimental.useTsgo": true
}
```



---
url: /config/lib/experiments.md
---

# lib.experiments

Used to enable some Rslib experimental features.

## experiments.advancedEsm

::: tip

`experiments.advancedEsm` is deprecated since Rslib v0.20 and will be removed in v1. Advanced ESM output is now the default for ESM format, so this option has no effect.

:::

- **Type:** `boolean`
- **Default:** `true`

Controls whether to enable Rspack experimental ESM output. When enabled, it emits ESM output that is high-quality, more friendly to static analysis, and supports code splitting.

:::info
Currently this option only takes effect in bundle mode when format is `'esm'`.
:::

If you need to disable this feature, you can set it to `false`:

```js title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'esm',
      bundle: true,
      experiments: {
        advancedEsm: false,
      },
    },
  ],
};
```

### Version history

| Version | Changes                                          |
| ------- | ------------------------------------------------ |
| v0.17.0 | Added this option                                |
| v0.19.0 | Changed default value from `false` to `true`     |
| v0.20.0 | Deprecated this option, no longer has any effect |



---
url: /config/lib/external-helpers.md
---

# lib.externalHelpers

- **Type:** `boolean`
- **Default:** `false`

Whether to import SWC helper functions from [@swc/helpers](https://www.npmjs.com/package/@swc/helpers) instead of inlining them.

By default, the output JavaScript file may depend on helper functions to support the target environment or output format, and these helper functions will be inlined in the file that requires it.

When `externalHelpers` set to `true`, the output JavaScript will import helper functions from the external module `@swc/helpers`. This helps reduce duplicate helper code in the final bundles, and reduces the bundle size.

::: note

Make sure to declare and install `@swc/helpers` in `dependencies` field of `package.json`.

:::

## Example

Take the following code as an example:

```ts title="index.ts"
export default class FOO {
  get bar() {
    return;
  }
}
```

When `externalHelpers` is disabled, the output JavaScript will inline helper functions.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      syntax: 'es5',
      externalHelpers: false, // [!code highlight]
    },
  ],
};
```

Below is the output JavaScript file, the highlighted code is the inlined helper functions:

```js title="index.js"
// [!code highlight:18]
function _class_call_check(instance, Constructor) {
  if (!(instance instanceof Constructor))
    throw new TypeError('Cannot call a class as a function');
}
function _defineProperties(target, props) {
  for (var i = 0; i < props.length; i++) {
    var descriptor = props[i];
    descriptor.enumerable = descriptor.enumerable || false;
    descriptor.configurable = true;
    if ('value' in descriptor) descriptor.writable = true;
    Object.defineProperty(target, descriptor.key, descriptor);
  }
}
function _create_class(Constructor, protoProps, staticProps) {
  if (protoProps) _defineProperties(Constructor.prototype, protoProps);
  if (staticProps) _defineProperties(Constructor, staticProps);
  return Constructor;
}
var src_FOO = /*#__PURE__*/ (function () {
  'use strict';
  function FOO() {
    _class_call_check(this, FOO);
  }
  _create_class(FOO, [
    {
      key: 'bar',
      get: function () {},
    },
  ]);
  return FOO;
})();
export { src_FOO as default };
```

When `externalHelpers` is enabled, the output JavaScript will import helper functions from the external module `@swc/helpers`.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      syntax: 'es5',
      externalHelpers: true, // [!code highlight]
    },
  ],
};
```

Below is the output JavaScript file, the highlighted code is importing helper functions:

```js title="index.js"
// [!code highlight:2]
import { _ } from '@swc/helpers/_/_class_call_check';
import { _ as _create_class_ } from '@swc/helpers/_/_create_class';
var src_FOO = /*#__PURE__*/ (function () {
  'use strict';
  function FOO() {
    _(this, FOO);
  }
  _create_class_(FOO, [
    {
      key: 'bar',
      get: function () {},
    },
  ]);
  return FOO;
})();
export { src_FOO as default };
```



---
url: /config/lib/footer.md
---

# lib.footer

- **Type:**

```ts
type Footer = {
  js?: string;
  css?: string;
  dts?: string;
};
```

- **Default:** `{}`

Inject content into the bottom of each JavaScript, CSS or declaration file.

## Object type

### footer.js

- **Type:** `string`
- **Default:** `undefined`

Inject content into the bottom of each JavaScript output file.

### footer.css

- **Type:** `string`
- **Default:** `undefined`

Inject content into the bottom of each CSS output file.

### footer.dts

- **Type:** `string`
- **Default:** `undefined`

Inject content into the bottom of each declaration output file.

## Notice

The footer content in JavaScript and CSS file is based on the [BannerPlugin](https://rspack.rs/plugins/webpack/banner-plugin) of Rspack. You should notice the following points:

- `raw: true` is enabled by default, so the footer content will be injected as a raw string instead of wrapping in a comment. So if you want to inject a comment, you should add `/*` and `*/` or other comment syntax by yourself.
- The `stage` option is set to the stage after the JavaScript and CSS files are optimized, thus preventing the footer content from being optimized away.

## Customize footer content

If the above default settings cannot meet your requirements, you can customize the footer content through `tools.rspack.plugins` to add a [BannerPlugin](https://rspack.rs/plugins/webpack/banner-plugin) instance with the corresponding options.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      // ...
      tools: {
        rspack: {
          plugins: [
            new rspack.BannerPlugin({
              footer: true,
              // ... options
            }),
          ],
        },
      },
    },
  ],
};
```

:::warning

The footer content in declaration files is handled differently from JavaScript and CSS files. It is written directly using the file system API, so setting `BannerPlugin` will not affect it.

:::



---
url: /config/lib/format.md
---

# lib.format

- **Type:** `'esm' | 'cjs' | 'umd' | 'mf' | 'iife'`
- **Default:** `'esm'`
- **CLI:** `--format <format>` (e.g. `--format umd`)

Specify the output format for the generated JavaScript output files.

For different output formats, Rslib uses the following default value of [output.library.type](https://rspack.rs/config/output#outputlibrarytype) provided by Rspack:

- `esm`：[modern-module](https://rspack.rs/config/output#type-modern-module)
- `cjs`：[commonjs-static](https://rspack.rs/config/output#type-commonjs-static)
- `umd`：[umd](https://rspack.rs/config/output#type-umd)
- `iife`: [module](https://rspack.rs/config/output#type-module) with [output.iife](https://rspack.rs/config/output#outputiife) enabled.

See [Output Format](/guide/basic/output-format.md) and [Module Federation](/guide/advanced/module-federation.md) for more details.

::: note

The `umd`, `mf` and `iife` formats only work when [bundle](/config/lib/bundle.md) is set to `true`.

:::



---
url: /config/lib/id.md
---

# lib.id

- **Type:** `string`
- **Default:** `undefined`

Specify the library ID. The ID identifies the library and is useful when using the `--lib` CLI option or the JavaScript API's `lib` option to build specific libraries with a meaningful `id`.

:::tip

Rslib uses Rsbuild's [environments](https://rsbuild.rs/guide/advanced/environments) feature to build multiple libraries in a single project under the hood. `lib.id` will be used as the key for the generated Rsbuild environment.

:::

## Default value

By default, Rslib automatically generates an ID for each library in the format `${format}${index}`. Here, `format` refers to the value specified in the current lib's [format](/config/lib/format.md), and `index` indicates the order of the library within all libraries of the same format. If there is only one library with the current format, the `index` will be empty. Otherwise, it will start from `0` and increment.

For example, the libraries in the `esm` format will start from `esm0`, followed by `esm1`, `esm2`, and so on. In contrast, `cjs` and `umd` formats do not include the `index` part since there is only one library for each format.

```ts title="rslib.config.ts"
export default {
  lib: [
    { format: 'esm' }, // id is `esm0`
    { format: 'cjs' }, // id is `cjs`
    { format: 'esm' }, // id is `esm1`
    { format: 'umd' }, // id is `umd`
    { format: 'esm' }, // id is `esm2`
  ],
};
```

## Customize ID

You can also specify a readable or meaningful ID of the library by setting the `id` field in the library configuration. The user-specified ID will take priority, while the rest will be used together to generate the default ID.

For example, `my-lib-a`, `my-lib-b`, and `my-lib-c` will be the IDs of the specified libraries, while the rest will be used to generate and apply the default ID.


```ts title="rslib.config.ts"
export default {
  lib: [
    { format: 'esm', id: 'my-lib-a' }, // ID is `my-lib-a`
    { format: 'cjs', id: 'my-lib-b' }, // ID is `my-lib-b`
    { format: 'esm' },                 // ID is `esm0`
    { format: 'umd', id: 'my-lib-c' }, // ID is `my-lib-c`
    { format: 'esm' },                 // ID is `esm1`
  ],
};
```


Then you could only build `my-lib-a` and `my-lib-b` by running the following command:

```bash
npx rslib build --lib my-lib-a --lib my-lib-b
```

:::note
The id of each library must be unique, otherwise it will cause an error.
:::



---
url: /config/lib/index.md
---

# Overview

- **Type:**

```ts
interface LibConfig extends EnvironmentConfig {
  autoExtension?: boolean;
  autoExternal?: AutoExternal;
  banner?: BannerAndFooter;
  bundle?: boolean;
  dts?: Dts;
  experiments?: { advancedEsm?: boolean };
  externalHelpers?: boolean;
  footer?: BannerAndFooter;
  format?: Format;
  id?: string;
  outBase?: string;
  redirect?: Redirect;
  shims?: Shims;
  syntax?: Syntax;
  umdName?: Rspack.LibraryName;
}

interface RslibConfig extends RsbuildConfig {
  lib: LibConfig[];
}
```

- **Default:** `undefined`

- **Required:** `true`

The `lib` configuration is an array of objects, each representing a distinct set of configurations. These include all Rsbuild configurations as well as Rslib-specific configurations, designed to generate different outputs.



---
url: /config/lib/out-base.md
---

# lib.outBase

- **Type:** `string`
- **Default Value:** `undefined`

:::info

`outBase` is a specific configuration for [bundleless mode](/guide/basic/output-structure.md#bundle--bundleless). This configuration does not take effect in bundle mode because all output files are bundled into a single file, so there's no need to determine the base output directory.

:::

When building a project where source files exist across multiple directories with bundleless mode, the output directory structure will be replicated relative to the `outBase` directory in the output directory. If no base output directory is specified, the [lowest common ancestor](https://en.wikipedia.org/wiki/Lowest_common_ancestor) of all input entry points is used by default.

Configuring `outBase` will change the path of the base output directory. `outBase` can be either a relative path from the current process directory or an absolute path.

For example, we have the following directory structure:

```txt
.
├── package.json
├── rslib.config.ts
└── src
    └── utils
        ├── bar
        │   └── index.ts
        ├── foo
        │   └── index.ts
        └── index.ts
```

If the output base directory is not specified, the lowest common ancestor of all input entry point paths, i.e. `./src/utils`, is used by default, and the final file output structure is:

```txt
dist
├── bar
│   └── index.js
├── foo
│   └── index.js
└── index.js
```

When `outBase` is configured as `./src`, the output directory structure is:

```txt
dist
└── utils
    ├── bar
    │   └── index.js
    ├── foo
    │   └── index.js
    └── index.js
```

::: tip

When the project needs to generate declaration files, to ensure that the generated declaration files and JS files maintain a consistent output directory structure, if you modify the `outBase` configuration, you need to make sure that the [rootDir](https://www.typescriptlang.org/tsconfig/rootDir.html) in `tsconfig.json` is set to the same path.

:::



---
url: /config/lib/redirect.md
---

# lib.redirect

:::info

`redirect` is the unique configuration for [bundleless mode](/guide/basic/output-structure.md#bundle--bundleless). It will not take effect in bundle mode where all output files are bundled into a single file, eliminating the need for import path redirection.

:::

- **Type:**

```ts
type JsRedirect = {
  path?: boolean;
  extension?: boolean;
};

type StyleRedirect = {
  path?: boolean;
  extension?: boolean;
};

type AssetRedirect = {
  path?: boolean;
  extension?: boolean;
};

type DtsRedirect = {
  path?: boolean;
  extension?: boolean;
};

type Redirect = {
  js?: JsRedirect;
  style?: StyleRedirect;
  asset?: AssetRedirect;
  dts?: DtsRedirect;
};
```

- **Default:**

```ts
const defaultRedirect = {
  js: {
    path: true,
    extension: true,
  },
  style: {
    path: true,
    extension: true,
  },
  asset: {
    path: true,
    extension: true,
  },
  dts: {
    path: true,
    extension: false,
  },
};
```

Configure the redirect for import paths in output files.

In bundleless mode, there are often needs such as using aliases or automatically appending suffixes for ESM outputs. The `redirect` configuration is designed to address these issues.

## redirect.js

Controls the redirect of the import paths of output JavaScript files.

- **Example:**

By default, when set `compilerOptions.paths` to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import path for the JavaScript output file will be redirected to the correct relative path and the corresponding file extension will be added:

```ts
import { foo } from '@/foo'; // source code of './src/bar.ts' ↓
import { foo } from './foo.mjs'; // expected output of './dist/bar.mjs'

import { foo } from '@/foo'; // source code of './src/utils/index.ts' ↓
import { foo } from '../foo.mjs'; // expected output of './dist/utils/index.mjs'
```

:::warning

When [output.externals](/config/rsbuild/output.md#outputexternals) is configured and a request is matched, neither `redirect.js.path` nor `redirect.js.extension` will take effect, and the final redirected request path will be entirely controlled by [output.externals](/config/rsbuild/output.md#outputexternals).

:::

### redirect.js.path

Whether to automatically redirect the import paths of JavaScript output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`, [resolve.alias](/config/rsbuild/resolve.md#resolvealias) and [resolve.aliasStrategy](/config/rsbuild/resolve.md#aliasstrategy) will take effect in the output file, and the import path of the output file will be redirected. For TypeScript projects, just configure [compilerOptions.paths](https://typescriptlang.org/tsconfig#paths) in the `tsconfig.json` file.

When set to `false`, the import path will not be effected by [resolve.alias](/config/rsbuild/resolve.md#resolvealias), [resolve.aliasStrategy](/config/rsbuild/resolve.md#aliasstrategy) and `tsconfig.json`.

- **Example:**

When set `compilerOptions.paths` to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import path for the JavaScript output file will be redirected to the correct relative path:

```ts
import { foo } from '@/foo'; // source code of './src/bar.ts' ↓
import { foo } from './foo'; // expected output of './dist/bar.js'

import { foo } from '@/foo'; // source code of './src/utils/index.ts' ↓
import { foo } from '../foo'; // expected output './dist/utils/index.js'
```

### redirect.js.extension

Whether to automatically redirect the file extension of import paths based on the JavaScript output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`, the file extension of import paths in JavaScript output files that can be resolved correctly will be automatically completed or replaced.

When set to `false`, import paths will retain their original file extensions.

:::note
The extension of the JavaScript output file is related to the [autoExtension](/config/lib/auto-extension.md#libautoextension) configuration.
:::

- **Example:**

For ESM outputs running in Node.js, the full extension to the module import path must be specified to load correctly. Rslib will automatically add corresponding file extensions based on the actual output JavaScript file.

```ts
import { foo } from './foo'; // source code of './src/bar.ts' ↓
import { foo } from './foo.mjs'; // expected output of './dist/bar.mjs'

import { foo } from './foo.ts'; // source code of './src/utils/index.ts' ↓
import { foo } from './foo.mjs'; // expected output './dist/utils/index.mjs'
```

## redirect.style

Controls the redirect of the import paths of output style files.

- **Example:**

By default, when `compilerOptions.paths` is set to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import paths of style output files will be redirected to the correct relative paths. Additionally, when importing [CSS Modules](/config/rsbuild/output.md#outputcssmodules), the file extension will be rewritten to the corresponding JavaScript output file extension.

```ts
import '@/foo.css'; // source code of './src/bar.ts' ↓
import './foo.css'; // expected output of './dist/bar.js'

import styles from '@/foo.module.less'; // source code of './src/baz.ts' ↓
import styles from './foo.module.mjs'; // expected output of './dist/baz.mjs'
```

### redirect.style.path

Whether to automatically redirect the import paths of style output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`, the relevant redirect rules are the same as [redirect.js.path](/config/lib/redirect.md#redirectjspath).

When set to `false`, the original import path will remain unchanged.

- **Example:**

When set `compilerOptions.paths` to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import path for the style output file will be redirected to the correct relative path.

When importing normal style files:

```ts
import '@/foo.css'; // source code of './src/bar.ts' ↓
import './foo.css'; // expected output of './dist/bar.js'

import '@/foo.css'; // source code of './src/utils/index.ts' ↓
import '../foo.css'; // expected output of './dist/utils/index.js'
```

When importing [CSS Modules](/config/rsbuild/output.md#outputcssmodules) files:

```ts
import styles from '@/foo.css'; // source code of './src/bar.ts' ↓
import styles from './foo.css'; // expected output of './dist/bar.js'

import styles from '@/foo.css'; // source code of './src/utils/index.ts' ↓
import styles from '../foo.css'; // expected output of './dist/utils/index.js'
```

### redirect.style.extension

Whether to automatically redirect the file extension of import paths based on the style output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`:

- When importing a normal style file, the path will be redirected to `.css`.
- When importing [CSS Modules](/config/rsbuild/output.md#outputcssmodules), the file extension will be redirected to the corresponding JavaScript output file extension.

When set to `false`, the file extension will remain unchanged from the original import path.

- **Example:**

When importing from a `.less` file:

```ts
import './index.less'; // source code ↓
import './index.css'; // expected output

import styles from './index.module.less'; // source code ↓
import styles from './index.module.mjs'; // expected output
```

## redirect.asset

Controls the redirect of the import paths of output asset files.

- **Example:**

By default, when `compilerOptions.paths` is set to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import paths of asset files will be redirected to the correct relative paths, and the file extensions will be rewritten to the corresponding JavaScript output file extensions.

```ts
import url from '@/assets/logo.svg'; // source code of './src/foo.ts' ↓
import url from './assets/logo.mjs'; // expected output of './dist/foo.mjs'
```

### redirect.asset.path

Whether to automatically redirect the import paths of asset output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`, the relevant redirect rules are the same as [redirect.js.path](/config/lib/redirect.md#redirectjspath).

When set to `false`, the original import path will remain unchanged.

- **Example:**

When set `compilerOptions.paths` to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import path for the asset file will be redirected to the correct relative path:

```ts
import url from '@/assets/logo.svg'; // source code of './src/foo.ts' ↓
import url from './assets/logo.svg'; // expected output of './dist/foo.js'
```

### redirect.asset.extension

Whether to automatically redirect the file extension of import paths based on the asset output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`, the file extension of imported asset files will be redirected to the corresponding JavaScript output file extension.

When set to `false`, the file extension will remain unchanged from the original import path.

- **Example:**

```ts
import url from './assets/logo.svg'; // source code of './src/foo.ts' ↓
import url from './assets/logo.mjs'; // expected output of './dist/foo.mjs'
```

::: note

The way to import static assets in a JavaScript file and the corresponding output structure, please see [Static assets](/guide/advanced/static-assets.md#import-assets-in-javascript-file).

:::

## redirect.dts

Controls the redirect of the import paths of output TypeScript declaration files.

- **Example:**

By default, when `compilerOptions.paths` is set to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import path in the declaration output file will be redirected to the correct relative path:

```ts
import { foo } from '@/foo'; // source code of './src/bar.ts' ↓
import { foo } from './foo'; // expected output of './dist/bar.d.ts'
```

### redirect.dts.path

Whether to automatically redirect the import paths of TypeScript declaration output files.

- **Type:** `boolean`
- **Default:** `true`

When set to `true`, Rslib will redirect the import path in the declaration output file to the corresponding relative path based on the [compilerOptions.paths](https://typescriptlang.org/tsconfig#paths) configured in `tsconfig.json`.

When set to `false`, the original import path will remain unchanged.

- **Example:**

When `compilerOptions.paths` is set to `{ "@/*": ["src/*"] }` in `tsconfig.json`, the import path in the declaration output file will be redirected to the correct relative path:

```ts
import { foo } from '@/foo'; // source code of './src/bar.ts' ↓
import { foo } from './foo'; // expected output of './dist/bar.d.ts'

import { foo } from '@/foo'; // source code of './src/utils/index.ts' ↓
import { foo } from '../foo'; // expected output './dist/utils/index.d.ts'
```

### redirect.dts.extension

Whether to automatically redirect the file extension of import paths based on the TypeScript declaration output files.

- **Type:** `boolean`
- **Default:** `false`

When set to `true`, the file extension of the import path in the declaration file will be automatically completed or replaced with the corresponding JavaScript file extension that can be resolved to the corresponding declaration file.

When set to `false`, import paths will retain their original file extensions.

:::note
The extension of the TypeScript declaration file is related to the [dts.autoExtension](/config/lib/dts.md#dtsautoextension) configuration.
:::

- **Example:**

When loading a module with `moduleResolution: 'nodenext'`, the import path needs to include the full file extension. Rslib will automatically add the corresponding file extension based on the actual JavaScript output file.

```ts
import { foo } from './foo'; // source code of './src/bar.ts' ↓
import { foo } from './foo.mjs'; // expected output of './dist/bar.d.mts'

import { foo } from './foo.ts'; // source code of './src/bar.ts' ↓
import { foo } from './foo.mjs'; // expected output of './dist/bar.d.mts'
```



---
url: /config/lib/shims.md
---

# lib.shims

- **Type:**

```ts
type Shims = {
  cjs?: {
    'import.meta.url'?: boolean;
    'import.meta.dirname'?: boolean;
    'import.meta.filename'?: boolean;
  };
  esm?: {
    __filename?: boolean;
    __dirname?: boolean;
    require?: boolean;
  };
};
```

- **Default:**

```js
const defaultShims = {
  cjs: {
    'import.meta.url': true,
    'import.meta.dirname': true,
    'import.meta.filename': true,
  },
  esm: {
    __filename: false,
    __dirname: false,
    require: false,
  },
};
```

Configure the [shims](https://developer.mozilla.org/en-US/docs/Glossary/Shim) for CommonJS and ESM output.

## shims.cjs

Set the fields to `true` to enable the corresponding shims for CommonJS output.

### shims.cjs\['import.meta.url']

Whether to inject shims for the `import.meta.url` in CommonJS output.

- **Default:** `true`

Options:

- `true`: when [format](/config/lib/format.md) is `cjs`, the `import.meta.url` in source code will be replaced with the URL of the current module.

  For example, given the following source code:

  ```js
  import { readFileSync } from 'fs';
  const buffer = readFileSync(new URL('./data.proto', import.meta.url));
  ```

  the CJS output will be transformed to:

  ```js
  const { readFileSync } = require('fs');
  const buffer = readFileSync(
    new URL(
      './data.proto',
      /*#__PURE__*/ (function () {
        return typeof document === 'undefined'
          ? new (module.require('url'.replace('', '')).URL)(
              'file:' + __filename,
            ).href
          : (document.currentScript && document.currentScript.src) ||
              new URL('main.js', document.baseURI).href;
      })(),
    ),
  );
  ```

- `false`: the `import.meta.url` will be left as is, which will cause a runtime error when running the output.

### shims.cjs\['import.meta.dirname']

Whether to inject shims for the `import.meta.dirname` in CommonJS output.

- **Default:** `true`

Options:

- `true`: when [format](/config/lib/format.md) is `cjs`, the `import.meta.dirname` in source code will be replaced with the `__dirname`.

  For example, given the following source code:

  ```js
  console.log(import.meta.dirname);
  ```

  the CJS output will be transformed to:

  ```js
  console.log(__dirname);
  ```

- `false`: the `import.meta.dirname` will be left as is, which will cause a runtime error when running the output.

### shims.cjs\['import.meta.filename']

Whether to inject shims for the `import.meta.filename` in CommonJS output.

- **Default:** `true`

Options:

- `true`: when [format](/config/lib/format.md) is `cjs`, the `import.meta.filename` in source code will be replaced with the `__filename`.

  For example, given the following source code:

  ```js
  console.log(import.meta.filename);
  ```

  the CJS output will be transformed to:

  ```js
  console.log(__filename);
  ```

- `false`: the `import.meta.filename` will be left as is, which will cause a runtime error when running the output.

## shims.esm

Set the fields to `true` to enable the corresponding shims for ESM output.

### shims.esm.\_\_filename

Whether to inject shims for the global `__filename` of CommonJS in ESM output.

- **Default:** `false`

Options:

- `true`: when [format](/config/lib/format.md) is `esm`, the `__filename` in source code will be replaced with the filename of the current module.

  For example, given the following source code:

  ```js
  console.log(__filename);
  ```

  the ESM output will be transformed to:

  ```js
  import { fileURLToPath as __webpack_fileURLToPath__ } from 'url';
  import { dirname as __webpack_dirname__ } from 'path';
  var src_dirname = __webpack_dirname__(
    __webpack_fileURLToPath__(import.meta.url),
  );
  var src_filename = __webpack_fileURLToPath__(import.meta.url);
  console.log(src_filename);
  ```

- `false`: the `__filename` will be left as is, which will cause a runtime error when running the output.

### shims.esm.\_\_dirname

Whether to inject shims for the global `__dirname` of CommonJS in ESM output.

- **Default:** `false`

Options:

- `true`: when [format](/config/lib/format.md) is `esm`, the `__dirname` in source code will be replaced with the directory name of the current module.

  For example, given the following source code:

  ```js
  console.log(__dirname);
  ```

  the ESM output will be transformed to:

  ```js
  import { fileURLToPath as __webpack_fileURLToPath__ } from 'url';
  import { dirname as __webpack_dirname__ } from 'path';
  var src_dirname = __webpack_dirname__(
    __webpack_fileURLToPath__(import.meta.url),
  );
  console.log(src_dirname);
  ```

- `false`: the `__dirname` will be left as is, which will cause a runtime error when running the output.

### shims.esm.require

Whether to inject shims for the global `require` of CommonJS in ESM output.

- **Default:** `false`

Options:

- `true`: when [format](/config/lib/format.md) is `esm`, there will be a `require` that is created by `createRequire` at the beginning of the output which can be accessed in source code like the global `require` like CommonJS.

  For example, given the following source code:

  ```js
  const someModule = require('./someModule');

  // dynamic require
  const dynamicRequiredModule = require(SOME_VALUE_IN_RUNTIME);
  // require.resolve
  const someModulePath = require.resolve('./someModule');
  // use require as a expression
  const lazyFn = (module, requireFn) => {};
  lazyFn('./other.js', require);
  ```

  the ESM output will be transformed to:

  ```js
  import __rslib_shim_module__ from 'node:module';
  const require = /*#__PURE__*/ __rslib_shim_module__.createRequire(
    import.meta.url,
  );
  // dynamic require
  require(SOME_VALUE_IN_RUNTIME);
  // require.resolve
  require.resolve('./someModule');
  // use require as a expression
  const lazyFn = (module, requireFn) => {};
  lazyFn('./other.js', require);
  ```

- `false`: the `require` will be left as is, which will cause a runtime error when running the output.



---
url: /config/lib/syntax.md
---

# lib.syntax

- **Type:**

```ts
type EcmaScriptVersion =
  | 'es5'
  | 'es6'
  | 'es2015'
  | 'es2016'
  | 'es2017'
  | 'es2018'
  | 'es2019'
  | 'es2020'
  | 'es2021'
  | 'es2022'
  | 'es2023'
  | 'es2024'
  | 'esnext';

type Syntax = EcmaScriptVersion | string[];
```

- **Default:** `'esnext'`
- **CLI:** `--syntax <value>` (repeatable, e.g. `--syntax es2018` or `--syntax="node 14" --syntax="Chrome 103"`)

Configure the syntax to which JavaScript and CSS will be downgraded.

See [Output Compatibility - Syntax Downgrade](/guide/advanced/output-compatibility.md) for more details.

## Set ECMAScript version

You can set the ECMAScript version directly, such as `es2015`, `es2022`, etc.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      syntax: 'es2015',
    },
  ],
};
```

## Set browserslist query

You can also set the [Browserslist query](https://browsersl.ist/), such as `last 2 versions`, `> 1%`, `node >= 16`, `chrome >= 80`, etc.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      syntax: ['last 2 versions', '> 1%'],
    },
  ],
};
```

## Mix ECMAScript version and browserslist query

You can also mix ECMAScript version and Browserslist query, such as `es2015` and `node 20`. Rslib will turn ECMAScript Version into Browserslist query, and then merge them together.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      syntax: ['es2015', 'node 20'],
    },
  ],
};
```



---
url: /config/lib/umd-name.md
---

# lib.umdName

- **Type:** `string | string[] | { amd?: string, commonjs?: string, root?: string | string[] }`
- **Default:** `undefined`

The export name of the [UMD](/guide/basic/output-format.md#umd) bundle.

:::tip

The module name of the UMD bundle must not conflict with the global variable name.

:::

## Example

- Mount the UMD bundle to `global.MyLibrary`.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'umd',
      umdName: 'MyLibrary', // [!code highlight]
    },
  ],
};
```

- Mount the UMD bundle to `global.MyLibrary.Utils`.

```ts title="rslib.config.ts"
export default {
  lib: [
    {
      format: 'umd',
      umdName: ['MyLibrary', 'Utils'], // [!code highlight]
    },
  ],
};
```



---
url: /config/rsbuild/index.md
---

# Overview

Rslib inherits its configuration from Rsbuild, so you can also configure the [![config](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)config](https://rsbuild.rs/config) options from Rsbuild. This chapter introduces some common configuration items and explains how to use them in Rslib.
- [logLevel](/config/rsbuild/log-level.md): Specify the log level.
- [resolve](/config/rsbuild/resolve.md): Options for module resolution.
- [source](/config/rsbuild/source.md): Options for input source code.
- [output](/config/rsbuild/output.md): Options for build outputs.
- [tools](/config/rsbuild/tools.md): Options for low-level tools.
- [performance](/config/rsbuild/performance.md): Options for performance.
- [plugins](/config/rsbuild/plugins.md): Configure Rsbuild plugins.

:::tip
To learn more about Rslib configurations, check out [Configure Rslib](/guide/basic/configure-rslib.md).
:::



---
url: /config/rsbuild/log-level.md
---

# logLevel [![logLevel](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)logLevel](https://rsbuild.rs/config/log-level)
- **Type:** `'info' | 'warn' | 'error' | 'silent'`
- **Default:** `'info'`

Specify the log level, the default value is `info`.



---
url: /config/rsbuild/output.md
---

# output

Options for build outputs.

## output.assetPrefix [![output.assetPrefix](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.assetPrefix](https://rsbuild.rs/config/output/asset-prefix)
Use this option to set the URL prefix for static assets, such as setting it to a CDN URL.

In Rslib, the default value for this option depends on [format](/config/lib/format.md):

- When `format` is `cjs` or `esm`, the default value is `"auto"`.
- When `format` is `mf` or `umd`, the default value is `"/"`.

When `output.assetPrefix` is set to `"auto"`, Rslib defaults to setting [importMode](https://rspack.rs/config/module#modulegeneratorassetimportmode) to `"preserve"`, which preserves the `import` or `require` statements for static assets in JavaScript files. Additionally, the static asset references in CSS files remain as relative paths, see [Static assets](/guide/advanced/static-assets.md) for more details.

When `output.assetPrefix` is set to a specific path, the static asset import statements in JavaScript files will no longer be preserved and will be replaced with URLs prefixed by that path. Additionally, the static asset paths in CSS files will be substituted with paths that include this prefix.

## output.charset [![output.charset](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.charset](https://rsbuild.rs/config/output/charset)
The `charset` config allows you to specify the [character encoding](https://developer.mozilla.org/en-US/docs/Glossary/Character_encoding) for output files to ensure they are displayed correctly in different environments.

## output.cleanDistPath [![output.cleanDistPath](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.cleanDistPath](https://rsbuild.rs/config/output/clean-dist-path)
- **CLI:** `--clean` / `--no-clean`

Whether to clean up all files under the output directory before the build starts (the output directory defaults to `dist`).

## output.copy [![output.copy](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.copy](https://rsbuild.rs/config/output/copy)
Copies the specified file or directory to the dist directory, implemented based on [rspack.CopyRspackPlugin](https://rspack.rs/plugins/rspack/copy-rspack-plugin).

## output.cssModules [![output.cssModules](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.cssModules](https://rsbuild.rs/config/output/css-modules)
For custom CSS Modules configuration.

## output.dataUriLimit [![output.dataUriLimit](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.dataUriLimit](https://rsbuild.rs/config/output/data-uri-limit)
Set the size threshold to inline static assets such as images and fonts.

When [format](/config/lib/format.md) is set to `cjs` or `esm`, Rslib defaults to setting `output.dataUriLimit` to `0`, without inlining any static assets, so that build tools on the application side can handle and optimize them.

## output.distPath [![output.distPath](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.distPath](https://rsbuild.rs/config/output/dist-path)
- **CLI:** `--dist-path <dir>` (e.g. `--dist-path output`)

Set the directory of the dist files. Rsbuild will output files to the corresponding subdirectory according to the file type.

By default, Rslib sets `output.distPath` to:

```ts
const defaultDistPath = {
  root: 'dist',
  js: './',
  jsAsync: './',
  css: './',
  cssAsync: './',
  svg: 'static/svg',
  font: 'static/font',
  wasm: 'static/wasm',
  image: 'static/image',
  media: 'static/media',
  assets: 'static/assets',
};
```



## output.emitCss [![output.emitCss](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.emitCss](https://rsbuild.rs/config/output/emit-css)
Whether to emit CSS to the output bundles.

## output.externals [![output.externals](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.externals](https://rsbuild.rs/config/output/externals)
- **CLI:** `--externals <pkg>` (repeatable, e.g. `--externals react --externals react-dom`)

At build time, prevent some `import` dependencies from being packed into bundles in your code, and instead fetch them externally at runtime.

In bundle mode, Rslib will automatically add the dependencies listed in the `dependencies`, `optionalDependencies`, and `peerDependencies` fields of `package.json` to `output.externals`. See [lib.autoExternal](/config/lib/auto-external.md) for more information.

:::note
It is important to note that `output.externals` differs from [resolve.alias](/config/rsbuild/resolve.md#resolvealias). Check out [resolve.alias](/config/rsbuild/resolve.md#resolvealias) documentation for more information.
:::

## output.filenameHash [![output.filenameHash](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.filenameHash](https://rsbuild.rs/config/output/filename-hash)
Whether to add a hash value to the filename after the production build.

Rslib sets `output.filenameHash` to `false` by default.

::: info Filename hash

By default, Rslib does not add a hash value in the middle of filenames.

To enable this behavior, you can set `output.filenameHash` to `true`.

You can also specify different filenames for different types of files by configuring `output.filename`.

:::

## output.filename [![output.filename](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.filename](https://rsbuild.rs/config/output/filename)
Sets the filename of dist files.

By default, Rslib will modify the JavaScript output file extension by setting `output.filename.js` according to [format](/config/lib/format.md), see [autoExtension](/config/lib/auto-extension.md) for more details.

## output.injectStyles [![output.injectStyles](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.injectStyles](https://rsbuild.rs/config/output/inject-styles)
Whether to inject styles into DOM.

## output.inlineScripts [![output.inlineScripts](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.inlineScripts](https://rsbuild.rs/config/output/inline-scripts)
Whether to inline output scripts files (.js files) into HTML with `<script>` tags.

## output.inlineStyles [![output.inlineStyles](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.inlineStyles](https://rsbuild.rs/config/output/inline-styles)
Whether to inline output style files (.css files) into HTML with `<style>` tags.

## output.legalComments [![output.legalComments](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.legalComments](https://rsbuild.rs/config/output/legal-comments)
Configure how to handle the legal comment.

## output.manifest [![output.manifest](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.manifest](https://rsbuild.rs/config/output/manifest)
Whether to generate a manifest file that contains information of all assets, and the mapping relationship between [entry module](https://rsbuild.rs/config/source/entry) and assets.

## output.minify [![output.minify](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.minify](https://rsbuild.rs/config/output/minify)
- **CLI:** `--minify` / `--no-minify`

Configure whether to enable code minification, or to configure minimizer options.

When `output.minify` is not specified, Rslib will use a sane default value.

- When format is `esm` or `cjs`, only dead code elimination and unused code elimination will be performed. The default value is:

```ts
export default defineConfig({
  output: {
    minify: {
      js: true,
      css: false,
      jsOptions: {
        minimizerOptions: {
          mangle: false,
          minify: false,
          compress: {
            defaults: false,
            directives: false,
            unused: true,
            dead_code: true,
            toplevel: true,
          },
          format: {
            comments: 'some',
            preserve_annotations: true,
          },
        },
      },
    },
  },
});
```

- When format is `umd`, the default value is the same as above, only dead code elimination and unused code elimination will be performed, which is usually used to generate UMD output for development. If you need to generate UMD output for production with the smallest possible bundle size, you can set `output.minify` to true:

```ts
export default defineConfig({
  output: {
    minify: true,
  },
});
```

- When format is `mf`, since MF assets are loaded over the network, which means they will not be compressed by the application project. Therefore, they need to be minified in Rslib. The default value is:

```ts
export default defineConfig({
  output: {
    minify: {
      js: true,
      css: false,
      jsOptions: {
        minimizerOptions: {
          mangle: false,
          // Enable minification
          minify: true,
          compress: {
            defaults: false,
            directives: false,
            unused: true,
            dead_code: true,
            // Avoid remoteEntry's global variable being tree-shaken
            toplevel: false,
          },
          format: {
            comments: 'some',
            preserve_annotations: true,
          },
        },
      },
    },
  },
});
```

::: note

It should be noted that the `output.minify` option you configured will completely override the above default configuration.

:::

## output.overrideBrowserslist [![output.overrideBrowserslist](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.overrideBrowserslist](https://rsbuild.rs/config/output/override-browserslist)
Specifies the range of target browsers that the project is compatible with.

Rslib will generate `output.overrideBrowserslist` based on [syntax](/config/lib/syntax.md), see [ESX\_TO\_BROWSERSLIST](https://github.com/web-infra-dev/rslib/blob/8d65f3728d60254bcf1a8e24d72902ad79dae959/packages/core/src/utils/syntax.ts#L42-L153) to get the mapping value.

## output.polyfill [![output.polyfill](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.polyfill](https://rsbuild.rs/config/output/polyfill)
Through the `output.polyfill` option, you can control the injection mode of the polyfills.

:::warning
Rsbuild's `output.polyfill` injects polyfills into the global scope, which can unexpectedly modify global variables for library consumers. For a non-global polyfill solution for browsers, please refer to [Polyfill - Browser](/guide/advanced/output-compatibility.md#browser).
:::

## output.sourceMap [![output.sourceMap](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.sourceMap](https://rsbuild.rs/config/output/source-map)
Used to set whether to generate source map files, and which format of source map to generate.

## output.target [![output.target](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)output.target](https://rsbuild.rs/config/output/target)
- **CLI:** `--target <target>` (e.g. `--target web`)

Setting the build target of Rsbuild.

Rslib sets `output.target` to `node` by default.

:::info
Check out the [Solution](/guide/solution/index.md) to learn more about the build target.
:::



---
url: /config/rsbuild/performance.md
---

# performance

Options for performance.

## performance.buildCache [![performance.buildCache](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)performance.buildCache](https://rsbuild.rs/config/performance/build-cache)
To enable or configure persistent build cache.

Rslib enable persistent build cache by default in v0.18.0.

## performance.printFileSize [![performance.printFileSize](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)performance.printFileSize](https://rsbuild.rs/config/performance/print-file-size)
Whether to print the file sizes after build.

## performance.removeConsole [![performance.removeConsole](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)performance.removeConsole](https://rsbuild.rs/config/performance/remove-console)
Whether to remove `console.[methodName]` in build.



---
url: /config/rsbuild/plugins.md
---

# plugins [![plugins](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)plugins](https://rsbuild.rs/config/plugins)
`plugins` is used to register Rsbuild plugins.

Rslib and Rsbuild share the same plugin system, so you can use Rsbuild plugins in Rslib.

::: note

Currently, some plugins have not been adapted to the [bundleless](/guide/basic/output-structure.md#bundle--bundleless) mode. For example, the Svelte plugin can only be used in the bundle mode.

:::

## Using plugins

You can register Rsbuild plugins in `rslib.config.*` using the `plugins` option, see [Rsbuild - plugins](https://rsbuild.rs/config/plugins).

```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  plugins: [pluginReact()],
});
```

## Official plugins

The following are official plugins that can be used in Rsbuild, and applicable to Rslib.

### For React

Plugins available for React:

- [React Plugin](https://rsbuild.rs/plugins/list/plugin-react): Provides support for React.
- [SVGR Plugin](https://rsbuild.rs/plugins/list/plugin-svgr): Support convert SVG to React components.
- [Styled Components Plugin](https://github.com/rsbuild-contrib/rsbuild-plugin-styled-components): Provide compile-time support for styled-components.

### For Vue

Plugins available for Vue:

- [Vue Plugin](https://github.com/rstackjs/rsbuild-plugin-unplugin-vue): Based on [unplugin-vue](https://github.com/unplugin/unplugin-vue), provides support for Vue 3 SFC (Single File Components).
- [Vue Plugin](https://rsbuild.rs/plugins/list/plugin-vue): Based on [vue-loader](https://github.com/vuejs/vue-loader), provides support for Vue 3 SFC (Single File Components) (Recommend using the implementation based on [unplugin-vue](https://github.com/unplugin/unplugin-vue), as vue-loader is no longer maintained).
- [Vue JSX Plugin](https://github.com/rstackjs/rsbuild-plugin-vue-jsx): Provides support for Vue 3 JSX / TSX syntax.
- [Vue2 Plugin](https://github.com/rstackjs/rsbuild-plugin-vue2): Provides support for Vue 2 SFC (Single File Components).
- [Vue2 JSX Plugin](https://github.com/rstackjs/rsbuild-plugin-vue2-jsx): Provides support for Vue 2 JSX / TSX syntax.

### For Preact

Plugins available for Preact:

- [Preact Plugin](https://rsbuild.rs/plugins/list/plugin-preact): Provides support for Preact.

### For Svelte

Plugins available for Svelte:

- [Svelte Plugin](https://rsbuild.rs/plugins/list/plugin-svelte): Provides support for Svelte components (`.svelte` files).

### For Solid

Plugins available for Solid:

- [Solid Plugin](https://rsbuild.rs/plugins/list/plugin-solid): Provides support for Solid.

### Common

The following are common framework-agnostic plugins:

- [Babel Plugin](https://rsbuild.rs/plugins/list/plugin-babel): Provides support for Babel transpilation capabilities.
- [Sass Plugin](https://rsbuild.rs/plugins/list/plugin-sass): Use Sass as the CSS preprocessor.
- [Less Plugin](https://rsbuild.rs/plugins/list/plugin-less): Use Less as the CSS preprocessor.
- [Stylus Plugin](https://rsbuild.rs/plugins/list/plugin-stylus): Use Stylus as the CSS preprocessor.
- [ESLint Plugin](https://github.com/rstackjs/rsbuild-plugin-eslint): Run ESLint checks during the compilation.
- [Type Check Plugin](https://github.com/rstackjs/rsbuild-plugin-type-check): Run TypeScript type checker on a separate process.
- [publint Plugin](https://github.com/rstackjs/rsbuild-plugin-publint): Run [`publint`](https://github.com/bluwy/publint) to lint npm packages after the build.
- [Are The Types Wrong Plugin](https://github.com/rstackjs/rsbuild-plugin-arethetypeswrong): Run [`arethetypeswrong`](https://github.com/arethetypeswrong/arethetypeswrong.github.io) to check TypeScript types of npm packages after the build.
- [Image Compress Plugin](https://github.com/rstackjs/rsbuild-plugin-image-compress): Compress the image assets.
- [MDX Plugin](https://github.com/rstackjs/rsbuild-plugin-mdx): Provide support for MDX.
- [Node Polyfill Plugin](https://github.com/rstackjs/rsbuild-plugin-node-polyfill): Used to inject polyfills of Node core modules in the browser side.
- [Source Build Plugin](https://github.com/rstackjs/rsbuild-plugin-source-build): This plugin is designed for the monorepo scenario. It supports referencing source code from other subdirectories and performs build and hot update.
- [Check Syntax Plugin](https://github.com/rstackjs/rsbuild-plugin-check-syntax): Check the syntax compatibility of output files and determine if there are any advanced syntaxes that could cause compatibility issues.
- [CSS Minimizer Plugin](https://github.com/rstackjs/rsbuild-plugin-css-minimizer): Used to customize CSS minimizer, switch to [cssnano](https://github.com/cssnano/cssnano) or other tools for CSS compression.
- [Typed CSS Modules Plugin](https://github.com/rstackjs/rsbuild-plugin-typed-css-modules): Generate TypeScript declaration file for CSS Modules.
- [Pug Plugin](https://github.com/rstackjs/rsbuild-plugin-pug): Provides support for the Pug template engine.
- [Rem Plugin](https://github.com/rstackjs/rsbuild-plugin-rem): Implements the rem adaptive layout for mobile pages.
- [UMD Plugin](https://github.com/rstackjs/rsbuild-plugin-umd): Generate outputs in UMD format.
- [YAML Plugin](https://github.com/rstackjs/rsbuild-plugin-yaml): Import YAML files and convert them into JavaScript objects.
- [TOML Plugin](https://github.com/rstackjs/rsbuild-plugin-toml): Import TOML files and convert them into JavaScript objects.

:::tip
You can find the source code of all official plugins in [web-infra-dev/rsbuild](https://github.com/web-infra-dev/rsbuild) and [rstackjs](https://github.com/rstackjs).
:::

## Community plugins

You can check out the Rsbuild plugins provided by the community at [awesome-rstack - Rsbuild Plugins](https://github.com/rstackjs/awesome-rstack?tab=readme-ov-file#rsbuild-plugins).

You can also discover more Rsbuild plugins on npm by searching for the keyword [rsbuild-plugin](https://www.npmjs.com/search?q=rsbuild-plugin\&ranking=popularity).



---
url: /config/rsbuild/resolve.md
---

# resolve

Options for module resolution.

## resolve.aliasStrategy [![resolve.aliasStrategy](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)resolve.aliasStrategy](https://rsbuild.rs/config/resolve/alias-strategy)
Set the strategy for path alias resolution, to control the priority relationship between the paths option in `tsconfig.json` and the [resolve.alias](/config/rsbuild/resolve.md#resolvealias) option.

## resolve.alias [![resolve.alias](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)resolve.alias](https://rsbuild.rs/config/resolve/alias)
Set the alias for the module path, which is used to simplify the import path or redirect the module reference, similar to the [resolve.alias](https://rspack.rs/config/resolve#resolvealias) config of Rspack.

For TypeScript projects, you only need to configure [compilerOptions.paths](https://www.typescriptlang.org/tsconfig/#paths) in the `tsconfig.json` file. Rslib will automatically recognize it, so there is no need to configure the `resolve.alias` option separately.

It is worth noting that in bundle mode, both `resolve.alias` and [output.externals](/config/rsbuild/output.md#outputexternals) can be used to set aliases, but they differ in the following ways:

- `resolve.alias` is used to replace the target module with another module, which will be bundled into the output.

  For example, if you want to replace `lodash` with `lodash-es` when bundling a package, you can configure it as follows:

  ```ts title="rslib.config.ts"
  export default {
    // ...
    resolve: {
      alias: {
        lodash: 'lodash-es',
      },
    },
  };
  ```

  Now, all `lodash` imports in the source code will be mapped to `lodash-es` and bundled into the output.

- `output.externals` is used to handle alias mapping for externalized modules. Externalized modules are not included in the bundle; instead, they are imported from external sources at runtime.

  For example, if you want to replace externalized modules `react` and `react-dom` with `preact/compat` in the bundle, you can configure it as follows:

  ```ts title="rslib.config.ts"
  export default {
    // ...
    output: {
      externals: {
        react: 'preact/compat',
        'react-dom': 'preact/compat',
      },
    },
  };
  ```

  Now, the code `import { useState } from 'react'` will be replaced with `import { useState } from 'preact/compat'`.

::: note
In bundleless mode, since there is no bundling concept, all modules will be externalized. Rslib will automatically transform the modules resolved to the [outBase](/config/lib/out-base.md) directory based on the mappings configured in `resolve.alias` or [compilerOptions.paths](https://www.typescriptlang.org/tsconfig/#paths) in `tsconfig.json`.
:::

## resolve.conditionNames [![resolve.conditionNames](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)resolve.conditionNames](https://rsbuild.rs/config/resolve/condition-names)
Specifies the condition names used to match entry points in the [exports field](https://nodejs.org/api/packages.html#packages_exports) of a package.

## resolve.dedupe [![resolve.dedupe](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)resolve.dedupe](https://rsbuild.rs/config/resolve/dedupe)
Force Rsbuild to resolve the specified packages from project root, which is useful for deduplicating packages and reducing the bundle size.

## resolve.extensions [![resolve.extensions](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)resolve.extensions](https://rsbuild.rs/config/resolve/extensions)
Automatically resolve file extensions when importing modules. This means you can import files without explicitly writing their extensions.

## resolve.mainFields [![resolve.mainFields](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)resolve.mainFields](https://rsbuild.rs/config/resolve/main-fields)
Controls the priority of fields in a package.json used to locate a package's entry file. It is the ordered list of package.json fields Rspack will try when resolving an npm package's entry point.



---
url: /config/rsbuild/source.md
---

# source

Options for input source code.

## source.assetsInclude [![source.include](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)source.include](https://rsbuild.rs/config/source/assets-include)
Include additional files that should be treated as static assets.

## source.decorators [![source.decorators](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)source.decorators](https://rsbuild.rs/config/source/decorators)
Used to configure the decorators syntax.

If [experimentalDecorators](https://www.typescriptlang.org/tsconfig/#experimentalDecorators) is enabled in `tsconfig.json`, Rslib will set `source.decorators.version` to `legacy` by default.

## source.define [![source.define](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)source.define](https://rsbuild.rs/config/source/define)
Replaces variables in your code with other values or expressions at compile time. This can be useful for injecting env variables and other information to the code during build time.

## source.entry [![source.entry](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)source.entry](https://rsbuild.rs/config/source/entry)
- **CLI:** `--entry <path>` (repeatable, e.g., `--entry index=src/index.ts` or `--entry src/index.ts`)

  The CLI argument supports two formats:

  1. `key=value`: Explicitly specify the entry name, e.g., `--entry main=src/main.ts`.
  2. `value`: Only specify the path, in which case the basename of the file (without extension) will be automatically used as the entry name. For example, `--entry src/index.ts` will generate an entry named `index`. If there are name conflicts, numeric suffixes (starting from 0) will be added to all conflicting entries, e.g., `index0`, `index1`.

Used to set the entry modules for building.

In Rslib, the default value is:

- bundle mode:

```ts
const defaultEntry = {
  // default support for other suffixes such as ts, tsx, jsx, mjs, cjs
  index: 'src/index.js',
};
```

- bundleless mode:

```ts
const defaultEntry = {
  index: 'src/**',
};
```

:::info
Check out the [lib.bundle](/config/lib/bundle.md#set-entry) to learn more about how to set entry for bundle and bundleless project.
:::

## source.exclude [![source.exclude](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)source.exclude](https://rsbuild.rs/config/source/exclude)
Exclude JavaScript or TypeScript files that do not need to be transformed by [SWC](https://rsbuild.rs/guide/configuration/swc).

::: note

Files configured in `source.exclude` will not be transformed by SWC, but the referenced files will still be bundled into the outputs.

If you want certain files not to be bundled into the outputs, you can use the following methods:

- **bundle mode**: Use Rspack's [IgnorePlugin](https://rspack.rs/plugins/webpack/ignore-plugin).
- **bundleless mode**: Use `source.entry` to configure the corresponding glob expression, refer to [Set entry](/config/lib/bundle.md#bundle-false).

:::

## source.include [![source.include](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)source.include](https://rsbuild.rs/config/source/include)
Specify additional JavaScript files that need to be compiled.



## source.transformImport [![source.transformImport](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)source.transformImport](https://rsbuild.rs/config/source/transform-import)
Transform the import path, which can be used to modularly import the subpath of third-party packages. The functionality is similar to [babel-plugin-import](https://npmjs.com/package/babel-plugin-import).

## source.tsconfigPath [![source.tsconfigPath](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)source.tsconfigPath](https://rsbuild.rs/config/source/tsconfig-path)
- **CLI:** `--tsconfig <path>` (e.g. `--tsconfig tsconfig.build.json`)

Configure a custom `tsconfig.json` file path to use, can be a relative or absolute path.

The `tsconfig.json` configuration file affects the following behavior of Rslib:

- The `paths` field is used to configure [Path alias](/config/rsbuild/resolve.md#resolvealias).
- The `experimentalDecorators` field is used to configure [Decorators version](/config/rsbuild/source.md#sourcedecorators).
- Used to configure the effective scope, rules, and output directory during [TypeScript declaration file generation](/config/lib/dts.md).



---
url: /config/rsbuild/tools.md
---

# tools

Options for low-level tools.

## tools.bundlerChain [![tools.bundlerChain](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)tools.bundlerChain](https://rsbuild.rs/config/tools/bundler-chain)
[rspack-chain](https://github.com/rstackjs/rspack-chain) is a utility library for configuring Rspack. By using `rspack-chain`, you can more easily modify and extend Rspack configurations.



## tools.cssLoader [![tools.cssLoader](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)tools.cssLoader](https://rsbuild.rs/config/tools/css-loader)
Rsbuild uses [css-loader](https://github.com/webpack-contrib/css-loader) by default to handle CSS resources. You can modify the options of css-loader through `tools.cssLoader`.



## tools.lightningcssLoader [![tools.lightningcssLoader](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)tools.lightningcssLoader](https://rsbuild.rs/config/tools/lightningcss-loader)
You can set the options for [builtin:lightningcss-loader](https://rspack.rs/guide/features/builtin-lightningcss-loader) through `tools.lightningcssLoader`.

## tools.postcss [![tools.postcss](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)tools.postcss](https://rsbuild.rs/config/tools/postcss)
Rsbuild integrates PostCSS by default, you can configure [postcss-loader](https://github.com/webpack-contrib/postcss-loader) through `tools.postcss`.

## tools.rspack [![tools.rspack](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)tools.rspack](https://rsbuild.rs/config/tools/rspack)
`tools.rspack` is used to configure [Rspack](https://rspack.rs/config/index).

## tools.styleLoader [![tools.styleLoader](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)tools.styleLoader](https://rsbuild.rs/config/tools/style-loader)
The config of [style-loader](https://github.com/webpack-contrib/style-loader) can be set through `tools.styleLoader`.

## tools.swc [![tools.swc](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)tools.swc](https://rsbuild.rs/config/tools/swc)
You can set the options of [builtin:swc-loader](https://rspack.rs/guide/features/builtin-swc-loader) through `tools.swc`.



---
url: /api/javascript-api/core.md
---

# Rslib core

This chapter introduces some of the core methods provided by Rslib.

## createRslib

Create an [Rslib instance](/api/javascript-api/instance.md).

- **Type:**

```ts
function createRslib(options?: CreateRslibOptions): Promise<RslibInstance>;
```

- **Example:**

```ts
import { createRslib } from '@rslib/core';

const rslib = await createRslib({
  config: {
    // Rslib configuration
  },
});
```

### Options

The first parameter of `createRslib` is an `options` object with the following properties:

```ts
type CreateRslibOptions = {
  cwd?: string;
  config?: RslibConfig | (() => Promise<RslibConfig>);
  loadEnv?: boolean | LoadEnvOptions;
};
```

- `cwd`: The root path of the current build, defaults to `process.cwd()`.
- `config`: Rslib configuration object. Refer to [Configuration overview](/config/index.md) for all available configuration options.
- `loadEnv`: Whether to call the [loadEnv](/api/javascript-api/core.md#loadenv) method to load environment variables and define them as global variables via [source.define](/config/rsbuild/source.md#sourcedefine).

### Load configuration async

`config` can also be an async function for dynamically loading Rslib configuration and performing custom operations.

```ts
import { createRslib, loadConfig } from '@rslib/core';

const rslib = await createRslib({
  config: async () => {
    const { content } = await loadConfig();
    someFunctionToUpdateConfig(content);
    return content;
  },
});
```

### Load environment variables

The `loadEnv` option in `createRslib` calls the [loadEnv](/api/javascript-api/core.md#loadenv) method to load environment variables:

```ts
const rslib = await createRslib({
  loadEnv: true,
});
```

Setting `loadEnv: true` automatically completes these steps:

1. Call the `loadEnv` method to load environment variables.
2. Add [source.define](/config/rsbuild/source.md#sourcedefine) configuration, defining the `publicVars` returned by `loadEnv` as global variables.
3. Watch the `.env` file for changes, restart build or restart the dev server when the file changes, and invalidate the build cache.
4. Automatically call the `cleanup` method returned by `loadEnv` when closing the build or dev server.

You can also pass in the options of the [loadEnv](/api/javascript-api/core.md#loadenv) method, for example:

```ts
const rslib = await createRslib({
  loadEnv: {
    prefixes: ['PUBLIC_', 'REACT_COMPS_'],
  },
});
```

## loadConfig

Load Rslib configuration file.

- **Type:**

```ts
function loadConfig(params?: {
  // Default is process.cwd()
  cwd?: string;
  // Specify the configuration file (relative or absolute path)
  path?: string;
  meta?: Record<string, unknown>;
  envMode?: string;
  loader?: 'auto' | 'jiti' | 'native';
}): Promise<{
  content: RslibConfig;
  filePath: string | null;
}>;
```

- **Example:**

```ts
import { loadConfig } from '@rslib/core';

// load `rslib.config.*` file by default
const { content } = await loadConfig();

console.log(content); // -> Rslib config object

const rslib = await createRslib({
  config: content,
});
```

If the Rslib config file does not exist in the cwd directory, the return value of the loadConfig method is `{ content: {}, filePath: null }`.

### Specify the configuration file

Use the `path` option to load the `my-config.ts` configuration file:

```ts
import { join } from 'node:path';
import { loadConfig } from '@rslib/core';

const { content } = await loadConfig({
  path: join(__dirname, 'my-config.ts'),
});
```

### Passing meta object

Load the configuration file and pass in a custom meta object:

```ts
import { join } from 'node:path';
import { loadConfig } from '@rslib/core';

const { content } = await loadConfig({
  meta: {
    foo: 'bar',
  },
});
```

In the `defineConfig` configuration function, you can access the `foo` variable through the `meta` object:

```ts title="rslib.config.ts"
export default defineConfig(({ meta }) => {
  console.log(meta.foo); // bar
  return config;
});
```

## loadEnv

Load the [.env](https://rsbuild.rs/guide/advanced/env-vars#env-file) file and return all environment variables starting with the specified prefixes.

The usage is the same as Rsbuild, see [loadEnv -- Rsbuild](https://rsbuild.rs/api/javascript-api/core#loadenv) for details.

:::tip

- Rslib CLI will automatically call the `loadEnv()` method. If you are using the Rslib CLI, you can set the `mode` parameter through the `--env-mode` option.
- The `loadEnv` option in [createRslib](#createrslib) will help you call the `loadEnv()` method and handle related operations.

:::

## mergeRslibConfig

Used to merge multiple Rslib configuration objects.

The `mergeRslibConfig` function takes multiple configuration objects as parameters. It deep merges each configuration object, automatically combining multiple function values into an array of sequentially executed functions, and returns a merged configuration object.

- **Type:**

```ts
function mergeRslibConfig(
  ...configs: (RslibConfigWithOptionalLib | undefined)[]
): RslibConfigWithOptionalLib;
```

### Basic example

```ts
import { mergeRslibConfig } from '@rslib/core';

const config1 = {
  lib: [
    {
      format: 'esm',
    },
  ],
  output: {
    target: 'node',
  },
};
const config2 = {
  output: {
    target: 'web',
  },
};

const mergedConfig = mergeRslibConfig(config1, config2);

console.log(mergedConfig);
// {
//   lib: [
//     {
//       format: 'esm',
//     },
//   ],
//   output: {
//     target: 'web',
//   },
// }
```

### Merge rules

For each item in the [lib](/config/lib.md) object array, the merge is processed based on the [id](/config/lib/id.md) field:

- Objects with the same `id` are deeply merged
- Objects without `id` will be appended to the end of the result array
- Objects with `id` are sorted in order of first occurrence

Other configuration fields follow the same merge rules as [mergeRsbuildConfig](https://rsbuild.rs/api/javascript-api/core#merge-rules).

```ts
import { mergeRslibConfig } from '@rslib/core';

const config1: RslibConfig = {
  lib: [
    {
      format: 'iife',
    },
    {
      id: 'esm',
      format: 'esm',
      syntax: 'es2020',
      resolve: {
        alias: {
          A: 'a',
        },
      },
      output: {
        externals: ['pkg1'],
      },
    },
    {
      id: 'cjs',
      format: 'cjs',
    },
  ],
};

const config2: RslibConfig = {
  lib: [
    {
      id: 'esm',
      syntax: 'es2021',
      output: {
        externals: ['pkg2'],
      },
      resolve: {
        alias: {
          B: 'b',
        },
      },
    },
    {
      format: 'umd',
    },
  ],
};

const mergedConfig = mergeRslibConfig(config1, config2);

console.log(mergedConfig);
// {
//   lib: [
//     {
//       format: 'esm',
//       id: 'esm',
//       output: {
//         externals: ['pkg1', 'pkg2'],
//       },
//       resolve: {
//         alias: {
//           A: 'a',
//           B: 'b',
//         },
//       },
//       syntax: 'es2021',
//     },
//     {
//       format: 'cjs',
//       id: 'cjs',
//     },
//     {
//       format: 'iife',
//     },
//     {
//       format: 'umd',
//     },
//   ],
// }
```

## rspack

If you need to access the API or plugins exported by [@rspack/core](https://npmjs.com/package/@rspack/core), you can directly import the `rspack` object from `@rslib/core` without installing the `@rspack/core` package separately.

- **Type:** `Rspack`
- **Example:**

```ts
// the same as `import { rspack } from '@rspack/core'`
import { rspack } from '@rslib/core';

console.log(rspack.rspackVersion); // a.b.c
console.log(rspack.util.createHash);
console.log(rspack.BannerPlugin);
```

:::tip

- Refer to [Rspack plugins](https://rspack.rs/plugins/) and [Rspack JavaScript API](https://rspack.rs/api/javascript-api/) to learn more about the available Rspack APIs.
- It's not recommended to manually install the `@rspack/core` package, as it may conflict with the version that Rslib depends on.

:::

## rsbuild

If you need to access the API exported by [@rsbuild/core](https://npmjs.com/package/@rsbuild/core), you can directly import the `rsbuild` object from `@rslib/core` without installing the `@rsbuild/core` package separately.

- **Example:**

```ts
import { rsbuild } from '@rslib/core';

console.log(rsbuild.version);
```

:::tip

Refer to [Rsbuild core](https://rsbuild.rs/api/javascript-api/core) for available Rsbuild APIs.

:::

## version

The version of `@rslib/core` currently in use.

- **Type:** `string`
- **Example:**

```ts
import { version } from '@rslib/core';

console.log(version); // 0.19.0
```



---
url: /api/javascript-api/instance.md
---

# Rslib instance

This section describes all the properties and methods on the Rslib instance object.

## rslib.build

Runs a production build, generating production outputs and writing them to the output directory.

- **Type:**

```ts
type BuildOptions = {
  /**
   * Specify library id
   */
  lib?: string[];
  /**
   * Whether to watch for file changes and rebuild.
   *
   * @default false
   */
  watch?: boolean;
};

function Build(options?: BuildOptions): Promise<{
  /**
   * Rspack's [stats](https://rspack.rs/api/javascript-api/stats) object.
   */
  stats?: Rspack.Stats | Rspack.MultiStats;
  /**
   * Close the build and call the `onCloseBuild` hook.
   * In watch mode, this method will stop watching.
   */
  close: () => Promise<void>;
}>;
```

- **Example:**

```ts
// Example 1: run build
await rslib.build();

// Example 2: run build of a specified library id
await rslib.build({
  lib: ['esm'],
});

// Example 3: build and get all assets
const { stats } = await rslib.build();

if (stats) {
  const { assets } = stats.toJson({
    // exclude unused fields to improve performance
    all: false,
    assets: true,
  });
  console.log(assets);
}
```

### Run specified library

You can specify the library to build using the `lib` option. If this option is not specified, all libraries will be built.

> See [lib.id](/config/lib/id.md) to learn how to get or set the ID of the library.

```ts
await rslib.build({
  lib: ['cjs', 'esm'],
});
```

### Watch file changes

To watch file changes and re-build, set the `watch` option to `true`.

```ts
await rslib.build({
  watch: true,
});
```

### Close build

`rslib.build()` returns a `close()` method that stops the build process.

In watch mode, calling the `close()` method will stop watching:

```ts
const buildResult = await rslib.build({
  watch: true,
});
await buildResult.close();
```

In non-watch mode, also call the `close()` method to end the build, which triggers the [onCloseBuild](https://rsbuild.rs/plugins/dev/hooks#onclosebuild) hook of Rsbuild for cleanup operations.

```ts
const buildResult = await rslib.build();
await buildResult.close();
```

### Stats object

In non-watch mode, `rslib.build()` returns an Rspack [stats](https://rspack.rs/api/javascript-api/stats) object.

For example, use the `stats.toJson()` method to get asset information:

```ts
const result = await rslib.build();
const { stats } = result;

if (stats) {
  const { assets } = stats.toJson({
    // exclude unused fields to improve performance
    all: false,
    assets: true,
  });
  console.log(assets);
}
```

## rslib.startMFDevServer

Start the dev server for the [Module Federation](/guide/advanced/module-federation.md) format library. This method will:

1. Start a dev server to serve your application
2. Watch for file changes and trigger recompilation

- **Type:**

```ts
type StartMFDevServerOptions = {
  /**
   * Specify library id
   */
  lib?: string[];
};

type StartServerResult = {
  /**
   * The URLs that server is listening on.
   */
  urls: string[];
  /**
   * The actual port used by the server.
   */
  port: number;
  server: {
    /**
     * Close the server.
     * In development mode, this will call the `onCloseDevServer` hook.
     */
    close: () => Promise<void>;
  };
};

function startMFDevServer(
  options?: StartMFDevServerOptions,
): Promise<StartServerResult>;
```

- **Example:**

Start dev server:

```ts
// Start dev server
await rslib.startMFDevServer();

// Start dev server of a specified library id
await rslib.startMFDevServer({
  lib: ['entry1'],
});
```

`startMFDevServer` returns these parameters:

- `urls`: URLs to access dev server.
- `port`: The actual listening port number.
- `server`: Server instance object.

```ts
const { port } = await rslib.startMFDevServer();
console.log(port); // 3000
```

### Run specified library

You can specify the library to start dev server using the `lib` option.

> See [lib.id](/config/lib/id.md) to learn how to get or set the ID of the library.

```ts
await rslib.startMFDevServer({
  lib: ['entry1'],
});
```

### Close server

Call the `close()` method to close the dev server, trigger the [onCloseDevServer](https://rsbuild.rs/plugins/dev/hooks#onclosedevserver) hook of Rsbuild, and perform cleanup operations.

```ts
const { server } = await rslib.startMFDevServer();
await server.close();
```

## rslib.inspectConfig

Inspects and debugs Rslib's internal configurations. It provides access to:

- The resolved Rslib configuration
- The resolved Rsbuild configuration
- The environment-specific Rsbuild configurations
- The generated Rspack configurations

The method serializes these configurations to strings and optionally writes them to disk for inspection.

- **Type:**

```ts
type InspectConfigOptions = {
  /**
   * Specify library id
   */
  lib?: string[];
  /**
   * Inspect the config in the specified mode.
   * Available options: 'development' or 'production'.
   * @default 'production'
   */
  mode?: RsbuildMode;
  /**
   * Enables verbose mode to display the complete function
   * content in the configuration.
   * @default false
   */
  verbose?: boolean;
  /**
   * Specify the output path for inspection results.
   * @default 'output.distPath.root'
   */
  outputPath?: string;
  /**
   * Whether to write the inspection results to disk.
   * @default false
   */
  writeToDisk?: boolean;
};

function inspectConfig(options?: InspectConfigOptions): Promise<{
  rslibConfig: string;
  rsbuildConfig: string;
  bundlerConfigs: string[];
  environmentConfigs: string[];
  origin: {
    rsbuildConfig: RsbuildConfig;
    environmentConfigs: Record<string, EnvironmentConfig>;
    bundlerConfigs: Rspack.Configuration[];
  };
}>;
```

:::tip

To view the configurations during the build process, use [debug mode](/guide/basic/configure-rslib.md#debug-mode), or obtain them through Rsbuild hooks such as [onBeforeBuild](https://rsbuild.rs/api/javascript-api/instance#rsbuildonbeforebuild), [onBeforeCreateCompiler](https://rsbuild.rs/api/javascript-api/instance#rsbuildonbeforecreatecompiler) in Rsbuild plugins.

:::

- **Example:**

Get the content of configs in string format:

```ts
const { rslibConfig, rsbuildConfig, bundlerConfigs } =
  await rslib.inspectConfig();

console.log(rslibConfig, rsbuildConfig, bundlerConfigs);
```

Write the config content to disk:

```ts
await rslib.inspectConfig({
  writeToDisk: true,
});
```

可以通过 `lib` 参数指定需要查看配置的库 id。如果不指定该参数，则会输出所有配置。

### Run specified library

You can specify the library to inspect configurations using the `lib` option. If this option is not specified, all libraries will be inspected.

> See [lib.id](/config/lib/id.md) to learn how to get or set the ID of the library.

```ts
await rslib.inspectConfig({
  lib: ['cjs', 'esm'],
});
```

### Output path

You can set the output path using `outputPath`. The default value is [output.distPath.root](/config/rsbuild/output.md#outputdistpath).

If `outputPath` is a relative path, it will be concatenated relative to the value of `output.distPath.root`. You can also set `outputPath` to an absolute path, in which case the files will be written directly to that path. For example:

```ts
import path from 'node:path';

await rslib.inspectConfig({
  writeToDisk: true,
  outputPath: path.join(__dirname, 'custom-dir'),
});
```

## rslib.getRslibConfig

Get the Rslib config.

- **Type:**

```ts
function getRslibConfig(): Readonly<RslibConfig>;
```

- **Example:**

```ts
import { createRslib } from '@rslib/core';

const rslib = await createRslib();
const config = rslib.getRslibConfig();
console.log(config.lib);
```

## rslib.onAfterCreateRsbuild

Called after the internal Rsbuild instance is created. You can access or call the properties and methods of the Rsbuild instance through this method.

- **Type:**

```ts
type OnAfterCreateRsbuildFn = (params: {
  rsbuild: RsbuildInstance;
}) => void | Promise<void>;

function onAfterCreateRsbuild(callback: OnAfterCreateRsbuildFn): void;
```

- **Example:**

```ts
const rslib = await createRslib();

rslib.onAfterCreateRsbuild(({ rsbuild }) => {
  rsbuild.onAfterBuild(() => {
    console.log('build done');
  });
});

await rslib.build();
```

All properties and methods on the Rsbuild instance object can be viewed in the [Rsbuild instance](https://rsbuild.rs/api/javascript-api/instance) document.



---
url: /api/javascript-api/types.md
---

# Rslib types

This section describes some of the type definitions provided by the Rslib.

## RslibInstance

The type of Rslib instance, corresponding to the return value of the [createRslib](/api/javascript-api/core.md#createrslib) method.

```ts twoslash
import type { RslibInstance } from '@rslib/core';

let rslib: RslibInstance;
```

## RslibConfig

The type of Rslib configuration.

```ts twoslash
import type { RslibConfig } from '@rslib/core';

const config: RslibConfig = {
  lib: [
    {
      format: 'esm',
    },
  ],
};
```

You can also import the type definitions of each field in the Rslib config:

```ts twoslash
import type {
  AutoExternal,
  BannerAndFooter,
  Dts,
  Format,
  LibConfig,
  Redirect,
  Shims,
  Syntax,
} from '@rslib/core';
```

## RsbuildPlugin

Defines the structure and behavior of an Rsbuild plugin.

Rsbuild plugins provide a standardized way to extend build functionality through lifecycle hooks and configuration modifications.

```ts twoslash
import type { RsbuildPlugin } from '@rslib/core';

const myPlugin: RsbuildPlugin = {
  name: 'my-plugin',
  setup() {},
};
```

## CreateRslibOptions

The param type of [createRslib](/api/javascript-api/core.md#createrslib) method.

```ts twoslash
import type { CreateRslibOptions } from '@rslib/core';
```

## BuildOptions

The param type of [rslib.build](/api/javascript-api/instance.md#rslibbuild) method.

```ts twoslash
import type { BuildOptions } from '@rslib/core';
```

## StartMFDevServerOptions

The param type of [rslib.startMFDevServer](/api/javascript-api/instance.md#rslibstartmfdevserver) method.

```ts twoslash
import type { StartMFDevServerOptions } from '@rslib/core';
```

## InspectConfigOptions

The param type of [rslib.inspectConfig](/api/javascript-api/instance.md#rslibinspectconfig) method.

```ts twoslash
import type { InspectConfigOptions } from '@rslib/core';
```

## Rspack

Includes all types exported by `@rspack/core`, such as `Rspack.Configuration`.

```ts twoslash
import type { Rspack } from '@rslib/core';

const rspackConfig: Rspack.Configuration = {};
```

## Rsbuild

Includes all types exported by `@rsbuild/core`, such as `Rsbuild.ToolsConfig`.

See [@rsbuild/core - src/index.ts](https://github.com/web-infra-dev/rsbuild/blob/main/packages/core/src/index.ts) for all exported types of Rsbuild.

```ts twoslash
import type { Rsbuild } from '@rslib/core';

const rsbuildConfig: Rsbuild.ToolsConfig = {};
```

## Others

See [@rslib/core - src/index.ts](https://github.com/web-infra-dev/rslib/blob/main/packages/core/src/index.ts) for all exported types.



---
url: /api/start/index.md
---

# JavaScript API

Rslib provides a comprehensive JavaScript API for developers to directly use Rslib's capabilities in JavaScript or TypeScript code.

Rslib's JavaScript API can be used in Node.js, Deno, or Bun.

:::tip Version requirements
v0.19.0 and above.
:::

## Getting started

This basic example demonstrates how to use the Rslib JavaScript API.

### 1. Install Rslib

Install the `@rslib/core` package:


```sh [npm]
npm add @rslib/core -D
```

```sh [yarn]
yarn add @rslib/core -D
```

```sh [pnpm]
pnpm add @rslib/core -D
```

```sh [bun]
bun add @rslib/core -D
```

```sh [deno]
deno add npm:@rslib/core -D
```

### 2. Create an Rslib instance

Call the [createRslib](/api/javascript-api/core.md#createrslib) method to create an Rslib instance:

```ts
import { createRslib } from '@rslib/core';

const rslib = await createRslib();
```

The `createRslib` method accepts various options. Learn more in the [API - createRslib](/api/javascript-api/core.md#createrslib) documentation.

### 3. Call Rslib instance methods

The Rslib instance provides several methods for different scenarios.

For example, when building the output, use the [rslib.build](/api/javascript-api/instance.md#rslibbuild) method which will build production outputs:

```ts
await rslib.build();
```

:::tip

For more information about Rslib instance methods, see the [Rslib instance](/api/javascript-api/instance.md) documentation.

:::

These three steps cover the basic usage of Rslib. Next, you can customize the build process with Rslib configurations and [Rsbuild plugins](https://rsbuild.rs/plugins/dev/).

## Export formats

Rslib only supports ES Modules formats:

```js title="index.mjs"
import { createRslib } from '@rslib/core';
```



---
url: /blog/index.md
---

# Rslib blogs

Check here for the latest articles and release announcements about Rslib.

## [Rslib: Build library with Rspack](/blog/introducing-rslib.md)

> May 14, 2025

We are excited to introduce Rslib — **a library development tool based on Rspack**. Developed by ByteDance Web Infra Team, Rslib helps developers create JavaScript libraries and UI component libraries in a simple and intuitive way while enjoying the ultimate development experience brought by [Rspack](https://rspack.rs/) and [Rsbuild](https://rsbuild.rs/).



---
url: /blog/introducing-rslib.md
---

_May 14, 2025_

# Rslib: Build library with Rspack

![banner](https://assets.rspack.rs/rslib/rslib-banner.png)

We are excited to introduce Rslib — **a library development tool based on Rspack**. Developed by ByteDance Web Infra Team, Rslib helps developers create JavaScript libraries and UI component libraries in a simple and intuitive way while enjoying the ultimate development experience brought by [Rspack](https://rspack.rs/) and [Rsbuild](https://rsbuild.rs/).

> Repo：[https://github.com/web-infra-dev/rslib](https://github.com/web-infra-dev/rslib)

## Why Rslib

In the past, webpack was mainly used for bundling web applications. When developing JavaScript libraries, developers typically introduced excellent bundlers like esbuild or Rollup, which could output high-quality ESM and CJS output to better meet JavaScript library bundling needs.

Within ByteDance, our development teams have created over 10,000 JavaScript libraries. During this process, we observed that the coexistence of multiple bundlers has led to ecosystem fragmentation. Additionally, in more complex library development scenarios, there are still many needs that haven't been well addressed, such as:

- **Configuration Fragmentation**: Library build configurations differ significantly from application development, requiring developers to learn different configuration rules and methods.
- **Limited Ecosystem Reuse**: Desire to reuse webpack plugins or loaders accumulated in the ecosystem.
- **Insufficient Extensibility**: Need for rich build lifecycle hooks to meet custom build requirements.
- **High Cost of Multi-format Output**: Libraries need to be bundled into multiple formats like ESM, CJS, UMD, and Module Federation, requiring repeated configuration with different tools.
- **Weak Non-JS Resource Handling**: Lack of standardized processing solutions for style schemes and static assets.
- **Missing Declaration File Support**: Need to bundle d.ts files of dependencies during build.

Facing these pain points, we hope the ideal library development tool would:

- **Easy to Configure:** Provide out-of-the-box configurations covering most scenarios, with plugin mechanisms for advanced feature extensions that work right after installation.
- **Comprehensive Features:** Support not only JavaScript / TypeScript transformation and multi-format output but also provide comprehensive style and resource processing solutions like web application building.
- **Shared Ecosystem:** Unify library building with application building configurations, reuse Rspack's prosperous community, and promote unified toolchain ecosystem development.
- **Performance First:** The underlying bundler is implemented in Rust, offering excellent build performance and improving developer experience.

Therefore, we created Rslib. **Based on the well-designed configurations and plugins of [Rsbuild](https://rsbuild.rs)'s, it empowers library developers to take advantage of the extensive knowledge and ecosystem of webpack and Rspack, providing comprehensive library development features.**

We hope Rslib can provide more powerful features for library developers and become an important part of the Rspack ecosystem, continuously promoting the development of unified toolchains based on Rspack.

![Rslib in Rstack ecosystem](https://assets.rspack.rs/others/assets/rslib/rslib-in-rstack.png)
The location of Rslib in the Rstack ecosystem



## Comprehensive library development features

Rslib provides a comprehensive library building solution that covers most current library building scenario needs:

- **Out-of-the-Box Configuration**

  Rslib provides out-of-the-box library building configurations. With minimal adjustments, it can meet most library building requirements. Moreover, for more advanced integration needs, in most cases, you only need to install the corresponding Rsbuild plugin to complete the setup, avoiding complicated configuration processes.

  Rslib's configuration extends from Rsbuild, allowing developers to continue using Rsbuild's configuration and ecosystem, maintaining consistent mental models between application and library development, and reusing build configuration-related code. This is particularly important in large monorepo projects that need to maintain multiple build configurations.

- **Multi-Format Output Support**

  Rslib supports bundling libraries into various module system formats, including ESM (ES modules), CJS (CommonJS), UMD (Universal Module Definition), and Module Federation. With just one build tool and one configuration file, it can handle all building scenarios, particularly suitable for library development scenarios requiring cross-project and cross-framework reuse. Additionally, through optimizing Rspack's ESM format build output, Rslib can now produce clean, standard ESM output.

  For TypeScript declaration files (d.ts), besides supporting d.ts file generation and related post-processing based on TypeScript Compiler API, it also supports bundling d.ts files using [@microsoft/api-extractor](https://www.npmjs.com/package/@microsoft/api-extractor), suitable for handling complex dependency scenarios.

  <img src="https://assets.rspack.rs/others/assets/rslib/multiple-formats-config.png" alt="Multiple formats in one configuration file" width="400" style={{ display: 'block', margin: '0 auto' }} />

  <ImageAlt>
    Multiple formats in one configuration file
  </ImageAlt>

  <img src="https://assets.rspack.rs/others/assets/rslib/simple-esm-output.png" alt="Clean ESM output" width="400" style={{ display: 'block', margin: '0 auto' }} />

  <ImageAlt>
    Clean ESM output
  </ImageAlt>

- **Bundle & Bundleless**

  Rslib supports both bundle and bundleless build modes during build process. For bundleless scenarios, it also supports [output path redirection](/config/lib/redirect.md) feature, solving common issues with alias replacement in JavaScript and d.ts output paths, as well as strict path reference requirements in ESM.

  <img src="https://assets.rspack.rs/rslib/rslib-bundleless-mode.png" alt="bundleless output structure" width="760" style={{ display: 'block', margin: '0 auto' }} />

  <ImageAlt>
    bundleless output structure
  </ImageAlt>

- **Style Solutions**

  Style building has always been a challenge in UI component library development. Compared to using Less loader, Sass loader, and PostCSS loader in application building, users often need to manually use the native tools of corresponding style solutions when building library output.

  Leveraging Rsbuild's plugin system and ecosystem, Rslib can directly reuse solutions for Sass, Less, Stylus, CSS Modules, and Tailwind CSS. Whether in bundle or bundleless scenarios, users can process styles just like building web application, directly through configuration or installing corresponding plugins.

  <img src="https://assets.rspack.rs/others/assets/rslib/multiple-styles-config.png" alt="Support multiple style solutions" width="760" style={{ display: 'block', margin: '0 auto' }} />

  <ImageAlt>
    Support multiple style solutions
  </ImageAlt>

- **Web Resource Handling**

  Rslib supports referencing static and inline assets like images, fonts, audio, and video in code, as well as static assets in CSS. After installing the appropriate plugins, users can also process SVG files through SVGR, while supporting JSON, TOML, and YAML formats. This feature provides great convenience when building UI component libraries containing resources.

- **Framework Agnostic**

  Rslib is a framework-agnostic library building solution, supporting Node.js and various UI component library builds. Different DSL UI frameworks only need to integrate corresponding plugins (including React, Preact, Vue, Solid, etc.) to complete underlying build configuration for development.

## Unlocking Rspack ecosystem possibilities

Beyond common JavaScript library development solutions, based on Rspack and the Rsbuild ecosystem, Rslib provides developers with more advanced features:

- **Module Federation**

  Rslib provides first-class support for [Module Federation](/guide/advanced/module-federation.md). Users only need to install the corresponding Rsbuild plugin to start debugging Module Federation and build MF format output. Users can publish libraries as remote modules to remote servers while building, or directly use remote modules.

- **Leverage Rsbuild Features**

  Rslib can reuse most of Rsbuild's configurations, supporting advanced features including but not limited to: [import path transformation](https://rsbuild.rs/config/source/transform-import), [inline styles](https://rsbuild.rs/config/output/inline-styles), [polyfill](https://rsbuild.rs/config/output/polyfill), and will continue to benefit from more features provided by Rsbuild's iterations in the future.

- **Share Rspack and Rsbuild Ecosystem**

  Based on the Rspack and Rsbuild ecosystem, Rslib can reuse a series of ecosystem features, including but not limited to:

  - Use [Storybook](https://storybook.rsbuild.rs/guide/integrations/rslib.html) to directly read Rslib's configuration files for UI component library development debugging.
  - Use [Rsdoctor](https://rsdoctor.rs/) for build performance and output analysis.
  - Use [Node.js polyfill](https://github.com/rstackjs/rsbuild-plugin-node-polyfill) plugin to develop cross-runtime libraries.
  - Use [ESLint plugin](https://github.com/rstackjs/rsbuild-plugin-eslint) for ESLint validation during development.
  - Use [publint plugin](https://github.com/rstackjs/rsbuild-plugin-publint) to check if the library's package.json is configured correctly.

  <img src="https://assets.rspack.rs/others/assets/rslib/publint-screenshot.png" alt="Use publint to check package.json" width="760" style={{ display: 'block', margin: '0 auto' }} />

  <ImageAlt>
    Use publint to check package.json
  </ImageAlt>

  > For more plugin information, please refer to [Rsbuild Plugin Overview](https://rsbuild.rs/plugins/list/).

## Current status and version evolution

Currently, Rspack / Rsbuild / Rspress and other projects in the Rstack toolchain are using Rslib for building, with tens of thousands of weekly downloads, serving multiple businesses within ByteDance, and is also the [recommended solution](https://module-federation.io/guide/basic/rsbuild.html#rslib-module) for Module Federation modules.

Rslib is currently in the 0.x stage and we plan to release v1.0 after achieving the following key goals:

- Stabilize the final configuration and API design
- Optimize the quality of the build output
- Support bundleless mode for Vue, Solid and more frameworks

You can track the progress by checking v1.0 [Milestone](https://github.com/web-infra-dev/rslib/milestone/1) on GitHub.

## Start using Rslib

We provide the scaffold tool [create-rslib](/guide/start/quick-start.md) for quickly creating Rslib projects. This scaffold supports creating Node.js / React library projects and supporting development tools. Additionally, we provide [migration documentation](/guide/migration/tsup.md) to help users migrate from other build tools to Rslib. You can experience developing React component libraries with Rslib in this [CodeSandbox](https://codesandbox.io/p/devbox/rslib-demo-react-ts-7mqjsd).

We believe that a unified toolchain based on Rspack will provide developers with more possibilities. Looking forward to your feedback and contributions to help us build a more complete frontend toolchain ecosystem together.



---
url: /index.md
---

body:not(.notTopArrived) .rp-nav {background: transparent !important; border-bottom: none !important;}.rp-nav {background: color-mix(in srgb,var(--rp-c-bg) 60%,transparent);backdrop-filter: blur(25px);-webkit-backdrop-filter: blur(25px);}![background](https://assets.rspack.rs/rspack/assets/landingpage-background-compressed.png)![logo](https://assets.rspack.rs/rslib/rslib-logo.svg)# Rslib

Rsbuild-based Library Development Tool

Create JavaScript libraries in a simple and intuitive way

Quick start[GitHubGitHub](https://github.com/web-infra-dev/rslib)# Rstack

A unified JavaScript toolchain centered on Rspack, with high performance and consistent architecture

[![Rspack](https://assets.rspack.rs/rspack/rspack-logo.svg)RspackA high performance JavaScript bundler written in Rust, with webpack-compatible API

rspack.rs](https://rspack.rs)[![Rsbuild](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)RsbuildAn Rspack-based build tool that provides out-of-the-box setup

rsbuild.rs](https://rsbuild.rs)[![Rslib](https://assets.rspack.rs/rslib/rslib-logo.svg)RslibA Rsbuild-based library development tool for creating libraries and UI components

rslib.rs](https://rslib.rs)[![Rspress](https://assets.rspack.rs/rspress/rspress-logo-480x480.png)RspressAn Rsbuild-based static site generator for creating documentation sites

rspress.rs](https://rspress.rs)[![Rsdoctor](https://assets.rspack.rs/rsdoctor/rsdoctor-logo-480x480.png)RsdoctorA one-stop build analyzer that makes the build process transparent

rsdoctor.rs](https://rsdoctor.rs)[![Rstest](https://assets.rspack.rs/rstest/rstest-logo.svg)RstestA testing framework that provides first-class support for Rspack ecosystem

rstest.rs](https://rstest.rs/)[![Rslint](https://assets.rspack.rs/rslint/rslint-logo.svg)RslintA high-performance JavaScript and TypeScript linter based on typescript-go

rslint.rs](https://rslint.rs/)Rslib is free and open source software released under the MIT license.

© 2024-present ByteDance Inc.