# Rsbuild

> * **Type:**`'prefer-tsconfig' | 'prefer-alias'`

---

# Source: https://rsbuild.dev/config/resolve/alias-strategy.md

# resolve.aliasStrategy

* **Type:** `'prefer-tsconfig' | 'prefer-alias'`
* **Default:** `'prefer-tsconfig'`
* **Version:** `>=1.1.7`

Set the strategy for path alias resolution, to control the priority relationship between the `paths` option in `tsconfig.json` and the [resolve.alias](/config/resolve/alias.md) option of Rsbuild.

:::tip
See [Path aliases](/guide/advanced/alias.md) for the differences between the `paths` option in `tsconfig.json` and the `resolve.alias` option of Rsbuild.
:::

## prefer-tsconfig

By default, `resolve.aliasStrategy` is set to `'prefer-tsconfig'`. In this case, both the `paths` option in `tsconfig.json` and the `alias` option in the bundler will take effect, but the `paths` option in tsconfig has a higher priority.

For example, if the following configurations are set at the same time:

* tsconfig paths:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "paths": {
      "@common/*": ["./src/common-1/*"]
    }
  }
}
```

* `resolve.alias`:

```ts title="rsbuild.config.ts"
export default {
  resolve: {
    alias: {
      '@common': './src/common-2',
      '@utils': './src/utils',
    },
  },
};
```

Since the tsconfig paths have a higher priority, the following will happen:

* `@common` will use the value defined in tsconfig paths, pointing to `./src/common-1`
* `@utils` will use the value defined in `resolve.alias`, pointing to `./src/utils`

## prefer-alias

If the value of `resolve.aliasStrategy` is set to `prefer-alias`, the `paths` option in `tsconfig.json` will only be used to provide TypeScript type definitions and will not affect the bundling result. In this case, the bundler will only read the `alias` option as the path alias.

```ts title="rsbuild.config.ts"
export default {
  resolve: {
    aliasStrategy: 'prefer-alias',
  },
};
```

For example, if the following configurations are set at the same time:

* tsconfig paths:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "paths": {
      "@common/*": ["./src/common-1/*"],
      "@utils/*": ["./src/utils/*"]
    }
  }
}
```

* `resolve.alias`:

```ts title="rsbuild.config.ts"
export default {
  resolve: {
    alias: {
      '@common': './src/common-2',
    },
  },
};
```

Since the tsconfig paths are only used to provide types, only the `@common` alias will be effective, pointing to the `./src/common-2` directory.

In most cases, you do not need to use `prefer-alias`, but you can consider using it if you need to dynamically generate some alias configurations. For example, generating the `alias` option based on environment variables:

```ts title="rsbuild.config.ts"
export default {
  resolve: {
    alias: {
      '@common':
        process.env.NODE_ENV === 'production'
          ? './src/common-prod'
          : './src/common-dev',
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/resolve/alias.md

# Source: https://rsbuild.dev/guide/advanced/alias.md

# Path aliases

Path aliases allow developers to define aliases for modules, making it easier to reference them in code. This can be useful when you want to use a short, easy-to-remember name for a module instead of a long, complex path.

For example, if you frequently reference the `src/common/request.ts` module in your project, you can define an alias for it as `@request` and then use `import request from '@request'` in your code instead of writing the full relative path every time. This also allows you to move the module to a different location without needing to update all the import statements in your code.

```ts title="src/index.ts"
import request from '@request'; // resolve to `src/common/request.ts`
```

In Rsbuild, there are several ways to set up path aliases:

* Use the [`paths` field](#typescript-paths-field) in tsconfig.json or jsconfig.json.
* Use the [`imports` field](#nodejs-imports-field) in package.json.
* Use Rsbuild's [resolve.alias](#alias-configuration) configuration.

## TypeScript `paths` field

You can configure aliases through the `paths` configuration in [tsconfig.json](https://typescriptlang.org/docs/handbook/tsconfig-json.html), which is the recommended approach in TypeScript projects as it also resolves the TS type issues related to path aliases.

For example:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "paths": {
      "@common/*": ["./src/common/*"]
    }
  }
}
```

After configuring, if you reference `@common/Foo.tsx` in your code, it will be mapped to the `<project>/src/common/Foo.tsx` path.

:::tip
You can refer to the [TypeScript - paths](https://typescriptlang.org/tsconfig#paths) documentation for more details.
:::

### jsconfig.json

In non-TypeScript projects, if you need to set path aliases through the `paths` field in [jsconfig.json](https://code.visualstudio.com/docs/languages/jsconfig), you can use the [source.tsconfigPath](/config/source/tsconfig-path.md) option to set it.

After adding the following configuration, Rsbuild will recognize the `paths` field in `jsconfig.json`.

```js title="rsbuild.config.mjs"
export default {
  source: {
    tsconfigPath: './jsconfig.json',
  },
};
```

## Node.js `imports` field

You can also use the Node.js [`imports` field](https://nodejs.org/api/packages.html#imports) to define aliases with the `#` prefix. This works out of the box and does not require additional Rsbuild configuration.

```json title="package.json"
{
  "type": "module",
  "imports": {
    "#app/*": "./src/*"
  }
}
```

```js title="src/index.js"
import { message } from '#app/foo';
```

For TypeScript projects, enable [`resolvePackageJsonImports`](https://www.typescriptlang.org/tsconfig/#resolvePackageJsonImports) so the TypeScript language service and compiler can understand these aliases.

## Alias configuration

Rsbuild provides the [resolve.alias](/config/resolve/alias.md) configuration option, which corresponds to the webpack/Rspack native [resolve.alias](https://rspack.rs/config/resolve#resolvealias) configuration. You can configure this option using an object or a function.

### Use cases

Since the `paths` configuration in `tsconfig.json` is written in a static JSON file, it lacks dynamism.

The `resolve.alias` configuration can address this limitation by allowing you to dynamically set the `resolve.alias` using JavaScript code, such as based on environment variables.

### Object usage

You can configure `resolve.alias` using an object, where the relative paths will be automatically resolved to absolute paths.

For example:

```js
export default {
  resolve: {
    alias: {
      '@common': './src/common',
    },
  },
};
```

After configuring, if you reference `@common/Foo.tsx` in your code, it will be mapped to the `<project>/src/common/Foo.tsx` path.

### Function usage

You can also configure `resolve.alias` as a function, which receives the built-in `alias` object and allows you to modify it.

For example:

```js
export default {
  resolve: {
    alias: (alias) => {
      alias['@common'] = './src/common';
      return alias;
    },
  },
};
```

### Priority

The `paths` configuration in `tsconfig.json` takes precedence over the `resolve.alias` configuration. When a path matches the rules defined in both `paths` and `resolve.alias`, the value defined in `paths` will be used.

You can adjust the priority of these two options using [resolve.aliasStrategy](/config/resolve/alias-strategy.md).

---

# Source: https://rsbuild.dev/config/html/app-icon.md

# html.appIcon

* **Type:**

```ts
type AppIconItem = {
  src: string;
  size: number;
  target?: 'apple-touch-icon' | 'web-app-manifest';
  purpose?: 'any' | 'maskable' | 'monochrome' | string;
};

type AppIcon = {
  name?: string;
  icons: AppIconItem[];
  filename?: string;
};
```

* **Default:** `undefined`

Set the web application icons to display when added to the home screen of a mobile device:

* Generate the web app manifest file and its `icons` field.
* Generate the [apple-touch-icon](https://webhint.io/docs/user-guide/hints/hint-apple-touch-icons/) and `manifest` tags in the HTML file.

:::tip

Refer to the following documents for more information:

* [MDN - Web app manifests](https://developer.mozilla.org/en-US/docs/Web/Manifest)
* [How to Favicon: Six files that fit most needs](https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs)

:::

## Example

For display on different devices, you will need to prepare several icons of different sizes.

The most commonly used icon sizes are `192x192` and `512x512`, and you can customize the icon sizes and quantities to suit your needs.

```ts title="rsbuild.config.ts"
export default {
  html: {
    appIcon: {
      name: 'My Website',
      icons: [
        { src: './src/assets/icon-192.png', size: 192 },
        { src: './src/assets/icon-512.png', size: 512 },
      ],
    },
  },
};
```

After compilation, the following tags will be automatically generated in the HTML:

```html
<link rel="manifest" href="/manifest.webmanifest" />
<link
  rel="apple-touch-icon"
  sizes="180x180"
  href="/static/image/icon-192.png"
/>
```

Here, `manifest.webmanifest` is a JSON file that contains information about the application's name, icons, and other details.

```json
{
  "name": "My Website",
  "icons": [
    {
      "src": "/static/image/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/static/image/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}
```

:::tip Icon size
For Chromium, you must provide at least a 192x192 pixel icon and a 512x512 pixel icon. If only those two icon sizes are provided, Chrome automatically scales the icons to fit the device. If you'd prefer to scale your own icons, and adjust them for pixel-perfection, provide icons in increments of `48dp`.
:::

## name

* **Type:** `string`
* **Default:** `undefined`

The name of the application that will be displayed when it is added to the home screen of the mobile device. If not set, the `manifest.webmanifest` file will not be generated.

> For more details, see [Web app manifests - name](https://developer.mozilla.org/en-US/docs/Web/Manifest/name).

## icons

* **Type:** `AppIconItem[]`
* **Default:** `undefined`

The list of icons:

* `src` is the path of the icon, which can be a URL, an absolute file path, or a relative path to the project [root](/config/root.md).
* `size` is the size of the icon in pixels.
* `target` refers to the intended target for the icon, which can be either `apple-touch-icon` or `web-app-manifest`. If `target` is not set, by default, the manifest file will include all icons, while the `apple-touch-icon` tags will only include icons smaller than `200x200`.
* `purpose` is a case-sensitive keyword string that specifies one or more contexts in which the icon can be used by the browser or operating system. This field is only effective when the `target` is `'web-app-manifest'`. See [MDN - purpose](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/icons#purpose) for more details.

### Example

`src` can be set to an absolute path:

```js
import path from 'node:path';

export default {
  html: {
    appIcon: {
      name: 'My Website',
      icons: [
        { src: path.resolve(__dirname, './assets/icon-192.png'), size: 192 },
        { src: path.resolve(__dirname, './assets/icon-512.png'), size: 512 },
      ],
    },
  },
};
```

Use `target` to specify the target for the icon:

```ts title="rsbuild.config.ts"
export default {
  html: {
    appIcon: {
      name: 'My Website',
      icons: [
        {
          src: './src/assets/icon-180.png',
          size: 180,
          target: 'apple-touch-icon',
        },
        {
          src: './src/assets/icon-192.png',
          size: 192,
          target: 'web-app-manifest',
        },
        {
          src: './src/assets/icon-512.png',
          size: 512,
          target: 'web-app-manifest',
        },
      ],
    },
  },
};
```

### filename

* **Type:** `string`
* **Default:** `'manifest.webmanifest'`

The filename of the manifest file.

```ts title="rsbuild.config.ts"
export default {
  html: {
    appIcon: {
      filename: 'manifest.json',
    },
  },
};
```

## Version history

| Version | Changes                            |
| ------- | ---------------------------------- |
| v1.5.5  | Added support for `purpose` option |

---

# Source: https://rsbuild.dev/config/output/asset-prefix.md

# Source: https://rsbuild.dev/config/dev/asset-prefix.md

# dev.assetPrefix

* **Type:** `boolean | string | 'auto'`
* **Default:** [server.base](/config/server/base.md)

Set the URL prefix of static assets in [development mode](/config/mode.md).

`assetPrefix` affects most static asset URLs, including JavaScript files, CSS files, images, videos, etc. If it is set incorrectly, these resources may return 404 errors.

This config is only used in `development` mode. In `production` mode or `none` mode, use [output.assetPrefix](/config/output/asset-prefix.md) to configure the URL prefix.

## Default value

The default value of `dev.assetPrefix` is the same as [server.base](/config/server/base.md).

When `server.base` is `/foo`, `index.html` and other static assets can be accessed through `http://localhost:3000/foo/`.

When you customize `dev.assetPrefix`, keep its URL prefix consistent with `server.base` so assets stay accessible through the Rsbuild dev server. For example:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    assetPrefix: '/foo/bar/',
  },
  server: {
    base: '/foo',
  },
};
```

## Boolean type

If `assetPrefix` is set to `true`, the URL prefix will be `http://localhost:<port>/`:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    assetPrefix: true,
  },
};
```

The resource URL loaded in the browser is as follows:

```html
<script defer src="http://localhost:3000/static/js/main.js"></script>
```

If `assetPrefix` is set to `false` or not set, `/` is used as the default value.

## String type

When the value of `assetPrefix` is a `string` type, the string will be used as a prefix and automatically appended to the static resource URL.

* For example, set to a path relative to the root directory:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    assetPrefix: '/example/',
  },
};
```

The resource URL loaded in the browser is as follows:

```html
<script defer src="http://localhost:3000/example/static/js/index.js"></script>
```

* For example, set to a complete URL:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    assetPrefix: 'https://example.com/assets/',
  },
};
```

The resource URL loaded in the browser is as follows:

```html
<script defer src="https://example.com/assets/static/js/index.js"></script>
```

### Port placeholder

The port number that Rsbuild server listens on may change. For example, if the port is in use, Rsbuild will automatically increment the port number until it finds an available port.

To avoid `dev.assetPrefix` becoming invalid due to port changes, you can use one of the following methods:

* Enable [server.strictPort](/config/server/strict-port.md).
* Use the `<port>` placeholder to refer to the current port number. Rsbuild will replace the placeholder with the actual port number it is listening on.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    assetPrefix: 'http://localhost:<port>/',
  },
};
```

## Path types

The `assetPrefix` option accepts the following path types:

* **absolute path**: The most common choice, including specific server paths like `/assets/`.
* **'auto'**: Rspack will automatically calculate the path and generate relative paths based on file location.

:::tip
It's not recommended to set assetPrefix as a relative path, such as `'./assets/'`. This is because when assets are at different path depths, using relative paths may cause assets to load incorrectly.
:::

## Compare with `publicPath`

The functionality of `dev.assetPrefix` is basically the same as the [output.publicPath](https://rspack.rs/config/output#outputpublicpath) config in Rspack.

The differences from the native configuration are as follows:

* `dev.assetPrefix` only takes effect in development mode.
* `dev.assetPrefix` default value is the same as [server.base](/config/server/base.md).
* `dev.assetPrefix` automatically appends a trailing `/` by default.
* The value of `dev.assetPrefix` is written to the [process.env.ASSET\_PREFIX](/guide/advanced/env-vars.md#processenvasset_prefix) environment variable (can only be accessed in client code).

## Dynamic asset prefix

Use the `__webpack_public_path__` variable provided by Rspack to dynamically set the URL prefix of static assets in JavaScript code.

See [Rspack - Dynamically set publicPath](https://rspack.rs/guide/features/asset-base-path#dynamically-set-publicpath).

---

# Source: https://rsbuild.dev/config/source/assets-include.md

# source.assetsInclude

* **Type:** [Rspack.RuleSetCondition](https://rspack.rs/config/module-rules#condition)
* **Default:** `undefined`
* **Version:** `>= 1.0.18`

Include additional files that should be treated as static assets.

By default, Rsbuild treats common image, font, audio, and video files as static assets. Through the `source.assetsInclude` config, you can specify additional file types that should be treated as static assets. These added static assets are processed using the same rules as the built-in supported static assets, see [Static Assets](/guide/basic/static-assets.md).

The value of `source.assetsInclude` is the same as the `test` option in Rspack loader. It can be a regular expression, string, array, logical condition, etc. For more details, see [Rspack RuleSetCondition](https://rspack.rs/config/module-rules#condition).

## Example

* Treating `.json5` files as static assets:

```ts
export default defineConfig({
  source: {
    assetsInclude: /\.json5$/,
  },
});
```

* Treating multiple file types as static assets:

```ts
export default defineConfig({
  source: {
    assetsInclude: [/\.json5$/, /\.pdf$/],
  },
});
```

* Treating specific files as static assets:

```ts
import path from 'node:path';

export default defineConfig({
  source: {
    assetsInclude: path.resolve(__dirname, 'src/assets/foo.json5'),
  },
});
```

---

# Source: https://rsbuild.dev/config/server/base.md

# server.base

* **Type:** `string`
* **Default:** `/`
* **Version:** `>= 1.0.10`

`server.base` is used to configure the [base path](/guide/basic/server.md#base-path) of the server.

## Example

By default, the Rsbuild server's base path is `/`. You can access output files like `index.html` and assets in the [public folder](/guide/basic/static-assets.md#public-folder) through `http://localhost:3000/`.

If you want to access `index.html` through `http://localhost:3000/foo/`, you can change `server.base` to `/foo`.

```ts title="rsbuild.config.ts"
export default {
  server: {
    base: '/foo',
  },
};
```

## URL prefix of assets

[dev.assetPrefix](/config/dev/asset-prefix.md) and [output.assetPrefix](/config/output/asset-prefix.md) will read the value of `server.base` as the default value.

When `server.base` is `/foo`, the default resource URL loaded in the browser is as follows:

```html
<script defer src="/foo/static/js/index.js"></script>
```

Then, `index.html` and static assets can be accessed through `http://localhost:3000/foo/`.

If you do not want to use this default behavior, you can override it by explicitly setting `dev.assetPrefix` / `output.assetPrefix` :

```ts title="rsbuild.config.ts"
export default {
  dev: {
    assetPrefix: '/',
  },
  output: {
    assetPrefix: 'https://cdn.example.com/assets/',
  },
  server: {
    base: '/foo',
  },
};
```

---

# Source: https://rsbuild.dev/guide/advanced/browser-compatibility.md

# Browser compatibility

Rsbuild supports [modern browsers](/guide/advanced/browserslist.md#default-browserslist) by default and provides syntax and API downgrade capabilities to ensure compatibility with legacy browsers that support ES5 (such as IE11).

This chapter explains how to use Rsbuild's features to handle browser compatibility issues.

## Set browserslist

Before addressing compatibility issues, decide which browsers your project needs to support and add the corresponding browserslist config.

* If you haven't set browserslist yet, please read the [Browserslist](/guide/advanced/browserslist.md) chapter first.

* If you have set a browserslist, Rsbuild automatically compiles code to match that scope, downgrades JavaScript and CSS syntax, and injects required polyfills. In most cases, you can safely use modern ECMAScript features without worrying about compatibility.

After setting the browserslist, if you still encounter compatibility issues, continue reading to find solutions.

:::tip What is polyfill
A polyfill is code that provides newer features to older browsers that don't support them natively. It fills gaps in older implementations of web standards, letting developers use modern features without worrying about whether they'll work in legacy browsers. For example, if a browser doesn't support the `Array.prototype.flat()` method, a polyfill can add that functionality so code using `Array.prototype.flat()` still runs. Polyfills are commonly used to keep web applications working across a wide range of browsers, including older ones.
:::

## Background knowledge

Before you tackle compatibility issues, review the following background so you can address them effectively.

### Syntax downgrade and API downgrade

When you use higher-version syntax and APIs in your project, you need to downgrade two parts to make the compiled code run reliably in older browsers: syntax and APIs.

**Rsbuild downgrades syntax through transpilation and downgrades APIs through polyfill injection.**

> Syntax and APIs are not tightly coupled. Browser vendors ship syntax or APIs at different times based on specifications and their own priorities, so browsers released in the same period may not support the same syntax or APIs. In practice, syntax and APIs are handled separately.

### Syntax transpilation

**Syntax is a set of rules for how a programming language organizes code**. Code that doesn't follow these rules cannot be correctly recognized by the programming language's engine and therefore cannot run. In JavaScript, the following are examples of syntax rules:

* In `const foo = 1`, `const` means to declare an immutable constant.
* In `foo?.bar?.baz`, `?.` indicates optional chaining of access properties.
* In `async function () {}`, `async` means to declare an asynchronous function.

Because different browser parsers support different syntax, and older engines support even less, certain syntax can trigger errors when older browsers try to parse the AST.

For example, the following code will cause an error in IE or an older version of Node.js:

```js
const foo = {};
foo?.bar();
```

When this code runs in an older version of Node.js, the following error message appears:

```bash
SyntaxError: Unexpected token.
   at Object.exports.runInThisContext (vm.js:73:16)
   at Object.<anonymous> ([eval]-wrapper:6:22)
   at Module._compile (module.js:460:26)
   at evalScript (node.js:431:25)
   at startup (node.js:90:7)
   at node.js:814:3
```

The error makes it clear that this is a syntax issue, meaning older versions of the engine do not support this syntax.

**Syntax cannot be supported by polyfills or shims**. To run syntax that's not originally supported in an older browser, you need to transpile the code into syntax the older engine can support.

Transpile the above code into the following to run in older engines:

```js
var foo = {};
foo === null || foo === void 0 ? void 0 : foo.bar();
```

After transpilation, the syntax of the code has changed, and syntax the older engine cannot understand has been replaced with syntax it can understand, **but the meaning of the code itself hasn't changed**.

If the engine encounters unrecognized syntax when converting to AST, it will report a syntax error and abort execution. In this case, if your project doesn't use capabilities like SSR or SSG, the page will be blank and unusable.

If the code is successfully converted to AST, the engine will convert it into executable code and run it normally.

### API polyfill

JavaScript is an interpreted scripting language, unlike compiled languages like Rust. Rust checks function calls during compilation, but JavaScript doesn't know whether a function exists until it runs that line of code, so some errors only appear at runtime.

For example:

```js
var str = 'Hello world!';
console.log(str.notExistedMethod());
```

The above code uses valid syntax and can be converted to an AST during the first stage of engine runtime, but when it actually runs, the method `notExistedMethod` does not exist on `String.prototype`, so an error is reported:

```bash
Uncaught TypeError: str.notExistedMethod is not a function
   at <anonymous>:2:17
```

With ECMAScript iterations, new methods are added to built-in objects. For example, `String.prototype.replaceAll` was introduced in ES2021. The `replaceAll` method doesn't exist in `String.prototype` of most browser engines before 2021, so the following code works in the latest Chrome but not in earlier versions:

```js
'abc'.replaceAll('abc', 'xyz');
```

To address the lack of `replaceAll` in older browsers, we can extend the `String.prototype` object and add the `replaceAll` method to it. For example:

```js
// The implementation of this polyfill does not necessarily conform to the standard, it is only used as an example.
if (!String.prototype.replaceAll) {
  String.prototype.replaceAll = function (str, newStr) {
    // If a regex pattern
    if (
      Object.prototype.toString.call(str).toLowerCase() === '[object regexp]'
    ) {
      return this.replace(str, newStr);
    }
    // If a string
    return this.replace(new RegExp(str, 'g'), newStr);
  };
}
```

> This technique of providing implementations for legacy environments to align new APIs is called polyfill.

## Compilation scope

By default, Rsbuild uses [SWC](/guide/configuration/swc.md) to compile all JavaScript and TypeScript modules, excluding JavaScript modules in the `node_modules` directory.

This approach is designed to avoid impacting build performance when downgrading all third-party dependencies while also preventing potential issues from redundantly downgrading pre-compiled third-party dependencies.

### Source code

The source code of the current project will be downgraded by default, so you don't need to add additional config, just make sure that the browserslist config is set correctly.

### Third-party dependencies

When you find that a third-party dependency causes compatibility issues, you can add this dependency to Rsbuild's [source.include](/config/source/include.md) config. This makes Rsbuild perform extra compilation for that dependency.

Taking the npm package `query-string` as an example, you can add the following config:

```ts title="rsbuild.config.ts"
import path from 'node:path';

export default {
  source: {
    include: [/node_modules[\\/]query-string[\\/]/],
  },
};
```

See [source.include](/config/source/include.md) for detailed usage.

## Polyfills

Rsbuild compiles JavaScript code using SWC and supports injecting polyfills such as [core-js](https://github.com/zloirock/core-js) and [@swc/helpers](https://npmjs.com/package/@swc/helpers).

In different usage scenarios, you may need different polyfill solutions. Rsbuild provides [output.polyfill](/config/output/polyfill.md) config to switch between different polyfill modes.

### Default behavior

Rsbuild does not inject any polyfills by default:

```ts
export default {
  output: {
    polyfill: 'off',
  },
};
```

### Usage mode

When you enable usage mode, Rsbuild will analyze the source code in the project and determine which polyfills need to be injected.

For example, the code uses the `Map` object:

```js
var b = new Map();
```

After compilation, only the polyfills for `Map` will be injected into this file:

```js
import 'core-js/modules/es.map';
var b = new Map();
```

The advantage of this method is smaller injected polyfill size, which is suitable for projects with higher requirements on bundle size. The disadvantage is that polyfills may not be fully injected because third-party dependencies won't be compiled and downgraded by default, so the polyfills required by third-party dependencies won't be analyzed. If you need to analyze a third-party dependency, you also need to add it to [source.include](/config/source/include.md) config.

The config of usage mode is:

```ts
export default {
  output: {
    polyfill: 'usage',
  },
};
```

### Entry mode

When using entry mode, Rsbuild will analyze which `core-js` methods need to be injected according to the browserslist set for the current project and inject them into the entry file of each page. Polyfills injected this way are more comprehensive, eliminating concerns about polyfill issues in project source code and third-party dependencies. However, because some unused polyfill code is included, the bundle size may increase.

The config of entry mode is:

```ts
export default {
  output: {
    polyfill: 'entry',
  },
};
```

### UA polyfill

Cloudflare provides a [polyfill service](https://cdnjs.cloudflare.com/polyfill/) that automatically generates polyfill bundles based on the user's browser User-Agent.

You can use the [html.tags](/config/html/tags.md) config of Rsbuild to inject scripts. For example, to inject a `<script>` tag at the beginning of the `<head>` tag:

```ts
export default {
  html: {
    tags: [
      {
        tag: 'script',
        attrs: {
          defer: true,
          src: 'https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=default',
        },
        append: false,
      },
    ],
  },
};
```

### Missing polyfills

It should be noted that core-js cannot provide polyfills for all JavaScript APIs. Some APIs cannot be fully simulated through polyfills due to the complexity of their underlying implementation or performance considerations.

The most typical example is the `Proxy` object. Since `Proxy` requires engine-level support to implement object operation interception, its behavior cannot be fully simulated through pure JavaScript code, so core-js doesn't provide a polyfill for `Proxy`.

See [core-js - Missing polyfills](https://github.com/zloirock/core-js?tab=readme-ov-file#missing-polyfills) to understand which APIs core-js cannot provide polyfills for.

---

# Source: https://rsbuild.dev/config/dev/browser-logs.md

# dev.browserLogs

* **Type:**

```ts
type BrowserLogs =
  | boolean
  | {
      stackTrace?: 'summary' | 'full' | 'none';
    };
```

* **Default:** `{ stackTrace: 'summary' }`

Controls whether to forward browser runtime errors to the terminal.

When set to `true`, Rsbuild's client script listens for `window.error` events and unhandled Promise rejections in the browser, then sends these errors to the dev server. The server prints them in the terminal with a `[browser]` prefix, along with improved formatting and contextual information.

This feature is particularly useful when working with AI coding agents that can only read terminal output, helping them better understand runtime errors and assist in debugging.

## Example

For example, if you have the following code in your application:

```jsx title="src/App.jsx"
const App = () => {
  const item = undefined;
  return <div>{item.name}</div>;
};
```

The browser will throw an error, and Rsbuild will forward this error to the terminal:

```bash
error   [browser] Uncaught TypeError: Cannot read properties of undefined (reading 'name')
 at handleClick (src/App.jsx:3:0)
```

## Options

### stackTrace

* **Type:** `'summary' | 'full' | 'none'`
* **Default:** `'summary'`

Controls how the error stack trace is displayed in the terminal when forwarding browser errors.

* `'summary'` – Show only the first frame (e.g. `(src/App.jsx:3:0)`).
* `'full'` – Print the full stack trace with all frames.
* `'none'` – Hide stack traces.

For example, setting `stackTrace` to `'full'`:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    browserLogs: {
      stackTrace: 'full',
    },
  },
};
```

The full stack trace will be like:

```bash
error   [browser] Uncaught TypeError: Cannot read properties of undefined (reading 'name')
    at handleClick (src/App.jsx:6:0)
    at someFunction (src/App.jsx:12:0)
    at App (src/App.jsx:6:0)
    ...
```

## Disabling

Set `dev.browserLogs` to `false` to disable this behavior.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    browserLogs: false,
  },
};
```

## Version history

| Version | Changes                   |
| ------- | ------------------------- |
| v1.5.13 | Added this option         |
| v1.6.0  | Added `stackTrace` option |

---

# Source: https://rsbuild.dev/guide/advanced/browserslist.md

# Browserslist

Rsbuild supports using [Browserslist](https://browsersl.ist/) to specify which browsers should be supported in your web application.

## What is browserslist

Since different browsers support ECMAScript and CSS features differently, developers need to specify the correct browser range for web applications.

[Browserslist](https://browsersl.ist/) lets you specify which browsers your web application can run in. It provides a configuration for specifying browser ranges. Browserslist has become an industry standard, used by libraries such as SWC, Lightning CSS, Babel, ESLint, PostCSS, and webpack.

When you specify a browser range through Browserslist, Rsbuild compiles JavaScript and CSS code to match the specified syntax.

## Polyfill injection

If you enable [output.polyfill](/config/output/polyfill.md), Rsbuild will also inject the corresponding polyfill code based on browserslist. **When you only need to support more modern browsers, the build process will introduce less compatibility code and polyfills, reducing the bundle size.**

```ts title="rsbuild.config.ts"
export default {
  output: {
    polyfill: 'usage',
  },
};
```

For example, when you need to be compatible with IE11, Rsbuild will compile the code to ES5 and inject the polyfills required by IE11 through [core-js](https://github.com/zloirock/core-js).

> Please refer to [Browser compatibility](/guide/advanced/browser-compatibility.md) for more information.

## Default values

Rsbuild sets different default Browserslist values according to [output.target](/config/output/target.md). You can also explicitly set Browserslist in your project to make the compatibility scope clearer.

### Web target

If `output.target` is `web`, Rsbuild will use the following Browserslist by default:

```yaml title=".browserslistrc"
chrome >= 87
edge >= 88
firefox >= 78
safari >= 14
```

With this browser range, the build output will be compatible with browsers that support [native ES Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).

### Node target

If `output.target` is `node`, Rsbuild will default to outputting bundles that run on Node.js 16.0 or later.

```yaml title=".browserslistrc"
node >= 16
```

### Web Workers target

If `output.target` is `web-worker`, Rsbuild will default to using the following Browserslist (consistent with the `web` target):

```yaml title=".browserslistrc"
chrome >= 87
edge >= 88
firefox >= 78
safari >= 14
```

## Set browserslist

You can set the Browserslist value in the `package.json` or `.browserslistrc` file in the root directory of the current project.

### Example

Set via `browserslist` in `package.json`:

```json title="package.json"
{
  "browserslist": [
    "iOS >= 9",
    "Android >= 4.4",
    "last 2 versions",
    "> 0.2%",
    "not dead"
  ]
}
```

Set via a separate `.browserslistrc` file:

```yaml title=".browserslistrc"
iOS >= 9
Android >= 4.4
last 2 versions
> 0.2%
not dead
```

### Effective scope

By default, the `.browserslistrc` file only applies to browser-side bundles, including the `web` and `web-worker` target types.

When building multiple targets simultaneously, for example if the targets contain both `web` and `node`, only the `web` bundles will be affected by the `.browserslistrc` file. To make changes to the `node` bundles, you can use the `output.overrideBrowserslist` configuration below.

### Set by env

You can set different browserslist configurations based on `NODE_ENV` to specify different browser ranges for development and production.

For example, set values based on keys in the `package.json`:

```json title="package.json"
{
  "browserslist": {
    "production": [
      "chrome >= 87",
      "edge >= 88",
      "firefox >= 78",
      "safari >= 14"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}
```

Or in `.browserslistrc`:

```yaml title=".browserslistrc"
[production]
chrome >= 87
edge >= 88
firefox >= 78
safari >= 14

[development]
last 1 chrome version
last 1 firefox version
last 1 safari version
```

### Override via config

In addition to the standard usage above, Rsbuild also provides [output.overrideBrowserslist](/config/output/override-browserslist.md) config, which can also set the Browserslist value.

`overrideBrowserslist` can be set to an array with the same syntax as `browserslistrc`, but it has a higher priority than `browserslistrc`.

```ts title="rsbuild.config.ts"
export default {
  output: {
    overrideBrowserslist: [
      'iOS >= 9',
      'Android >= 4.4',
      'last 2 versions',
      '> 0.2%',
      'not dead',
    ],
  },
};
```

In most cases, we recommend using the `.browserslistrc` file rather than the `overrideBrowserslist` config. The `.browserslistrc` file is the standard config file, making it more general and recognizable by other libraries in the community.

## Commonly used browserslist

The following are some commonly used Browserslist configurations. Choose according to your project type.

### Desktop web application

For desktop web applications, if you need to be compatible with IE 11 browsers, you can set Browserslist to:

```yaml title=".browserslistrc"
> 0.5%
not dead
IE 11
```

The above Browserslist will compile the code to ES5. For the specific browser list, please check [browserslist.dev](https://browserslist.dev/?q=PiAwLjUlLCBub3QgZGVhZCwgSUUgMTE%3D).

If you don't need to be compatible with IE 11, you can adjust browserslist for more performant output, such as:

* Set to browsers that support native ES Modules (recommended):

```yaml title=".browserslistrc"
chrome >= 87
edge >= 88
firefox >= 78
safari >= 14
```

* Set to browsers that support ES6:

```yaml title=".browserslistrc"
chrome >= 51
edge >= 15
firefox >= 54
safari >= 10
ios_saf >= 10
```

### Mobile web application

For mobile web applications, mainly compatible with `iOS` and `Android` systems, we usually set browserslist as:

```yaml title=".browserslistrc"
iOS >= 9
Android >= 4.4
last 2 versions
> 0.2%
not dead
```

The above browserslist will compile the code to ES5, which is compatible with most mobile scenarios on the market. For the detailed browser list, please check [browserslist.dev](https://browserslist.dev/?q=aU9TID49IDksIEFuZHJvaWQgPj0gNC40LCBsYXN0IDIgdmVyc2lvbnMsID4gMC4yJSwgbm90IGRlYWQ%3D).

![](https://assets.rspack.rs/rsbuild/assets/browserslist-dev-example.png)

You can also choose to use ES6 or higher, which will make the page perform better. The corresponding Browserslist is as follows:

```yaml title=".browserslistrc"
iOS >= 10
Chrome >= 51
> 0.5%
not dead
not op_mini all
```

## Query browser support

When developing, we need to know the browser support for certain features or APIs. You can check on the [caniuse](https://caniuse.com/) website.

For example, to check browser support for `Promise`, just enter `Promise` in [caniuse](https://caniuse.com/), and you can see the following results:

![](https://assets.rspack.rs/rsbuild/assets/caniuse-promise-example.png)

As can be seen from the above table, `Promise` is natively supported in Chrome 33 and iOS 8, but not in IE 11.

---

# Source: https://rsbuild.dev/config/performance/build-cache.md

# performance.buildCache

* **Type:**

```ts
type BuildCacheConfig =
  | boolean
  | {
      cacheDirectory?: string;
      cacheDigest?: Array<string | undefined>;
      buildDependencies?: string[];
    };
```

* **Default:** `false`
* **Version:** `>= 1.2.5`

To enable or configure persistent build cache.

When enabled, Rspack will store the build snapshots in the cache directory. In subsequent builds, if the cache is hit, Rspack can reuse the cached results instead of rebuilding from scratch, which can reduce the build time.

:::tip

Rspack's persistent cache is [experimental](https://rspack.rs/config/experiments#experimentscache) and may change in the future.

:::

## Enable cache

Setting `performance.buildCache` to `true` will enable the persistent build cache:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    buildCache: true,
  },
};
```

Or only enable cache in development mode:

```ts title="rsbuild.config.ts"
const isDev = process.env.NODE_ENV === 'development';

export default {
  performance: {
    buildCache: isDev,
  },
};
```

## Options

### cacheDirectory

* **Type:** `string`
* **Default:** `node_modules/.cache`

Set the output directory of the cache files.

```ts title="rsbuild.config.ts"
import path from 'node:path';

export default {
  performance: {
    buildCache: {
      cacheDirectory: path.resolve(__dirname, 'node_modules/.my-cache'),
    },
  },
};
```

### cacheDigest

* **Type:** `Array<string | undefined>`
* **Default:** `undefined`

Add additional cache digests, the previous build cache will be invalidated when any value in the array changes.

`cacheDigest` allows you to add variables that affect the build result, for example `process.env.SOME_ENV`.

```ts title="rsbuild.config.ts"
export default defineConfig({
  performance: {
    buildCache: {
      cacheDigest: [process.env.SOME_ENV],
    },
  },
});
```

### buildDependencies

* **Type:** `string[]`

`buildDependencies` is an array of additional code dependencies for the build. Rspack will use a hash of each of these items and all dependencies to invalidate the filesystem cache.

Equivalent to Rspack's [cache.buildDependencies](https://rspack.rs/config/experiments#cachebuilddependencies) option.

#### Default value

Rsbuild will use the following configuration files as the default build dependencies:

* `package.json`
* `tsconfig.json`
* `.env`, `.env.*`
* `.browserslistrc`
* `tailwindcss.config.*`

Additionally:

* When using Rsbuild CLI, it will also automatically add the Rsbuild configuration file (`rsbuild.config.*`) to the build dependencies.
* When using Rsbuild's [loadConfig](/api/javascript-api/core.md#loadconfig) JS API, it will also automatically add the configuration file path to the build dependencies.

#### Example

When you add other build dependencies, Rsbuild merges these custom dependencies with the default dependencies and passes them to Rspack.

```ts title="rsbuild.config.ts"
export default {
  performance: {
    buildCache: {
      buildDependencies: [__filename],
    },
  },
};
```

---

# Source: https://rsbuild.dev/guide/optimization/build-performance.md

# Improve build performance

While Rsbuild optimizes build performance by default, performance issues can arise as your project grows.

This document provides optional optimization strategies to improve build performance.

## Performance profiling

Performance profiling helps identify bottlenecks in your project for targeted optimization.

See the [Build Performance Analysis](/guide/debug/build-profiling.md) section.

## General optimization

These general optimization methods speed up both development and production builds.

### Upgrade Rsbuild

Upgrading to the latest version of Rsbuild gives you access to the latest performance optimizations. See [Upgrade Rsbuild](/guide/upgrade/upgrade-rsbuild.md) for more details.

### Enable persistent cache

Rsbuild provides a [performance.buildCache](/config/performance/build-cache.md) configuration that significantly improves rebuild speed.

### Reduce module count

Optimizing the number of modules in your application reduces bundle size and improves build performance. See [Bundle Size Optimization](/guide/optimization/optimize-bundle.md) to learn optimization strategies.

### Optimize Tailwind CSS

When using Tailwind CSS v3, incorrectly configuring the `content` field in `tailwind.config.js` can lead to poor build and HMR performance.

See [Tailwind CSS v3 - Optimize build performance](/guide/styling/tailwindcss-v3.md#optimize-build-performance) for more details.

### Parallel Less compilation

If your project uses the [@rsbuild/plugin-less](/plugins/list/plugin-less.md) plugin with many Less files, try enabling parallel compilation to improve build performance.

See [Less Plugin - parallel](/plugins/list/plugin-less.md#parallel) for more details.

### Tool selection

While Rsbuild delivers excellent build performance out of the box, certain JavaScript-based tools can negatively impact performance, particularly in large projects.

* [@rsbuild/plugin-babel](/plugins/list/plugin-babel.md): This plugin uses Babel. We recommend using the more performant [SWC](/guide/configuration/swc.md) for code transformation instead.
* [@rsbuild/plugin-less](/plugins/list/plugin-less.md): The Less compiler has relatively poor performance. Consider using [@rsbuild/plugin-sass](/plugins/list/plugin-sass.md) or other performant CSS solutions instead.
* [terser-webpack-plugin](https://www.npmjs.com/package/terser-webpack-plugin): You can replace Terser with faster minimizers like Rsbuild's built-in [SWC](/guide/configuration/swc.md) minifier.

## Development optimization

These methods improve performance in development mode.

### Enable lazy compilation

Enabling lazy compilation significantly reduces the number of modules compiled during dev server startup, improving startup time.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    lazyCompilation: true,
  },
};
```

> See [dev.lazyCompilation](/config/dev/lazy-compilation.md) for more information.

### Enable native watcher

Enabling Rspack's [native watcher](https://rspack.rs/config/experiments#experimentsnativewatcher) improves HMR performance in development mode.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: {
      experiments: {
        nativeWatcher: true,
      },
    },
  },
};
```

### Source map format

To provide a good debugging experience, Rsbuild uses the `cheap-module-source-map` format in development mode by default. This is a high-quality source map format that comes with some performance overhead.

You can improve build speed by adjusting the source map format using [output.sourceMap](/config/output/source-map.md).

For example, to disable source maps:

```ts title="rsbuild.config.ts"
export default {
  output: {
    sourceMap: {
      js: false,
    },
  },
};
```

Or set the source map format to the fastest `eval` format in development mode:

```ts title="rsbuild.config.ts"
export default {
  output: {
    sourceMap: {
      js: process.env.NODE_ENV === 'development' ? 'eval' : false,
    },
  },
};
```

> For detailed differences between different source map formats, see [Rspack - devtool](https://rspack.rs/config/devtool).

### Browserslist for development

This strategy is similar to ["Adjust Browserslist"](/guide/optimization/optimize-bundle.md#adjust-browserslist), except you can set different browserslist configurations for development and production, reducing compilation overhead in development.

For example, you can add the following config to `.browserslistrc` to target only the latest browsers in development while supporting a broader range in production:

```yaml title=".browserslistrc"
[production]
chrome >= 87
edge >= 88
firefox >= 78
safari >= 14

[development]
last 1 chrome version
last 1 firefox version
last 1 safari version
```

Note that this can lead to differences in build output between development and production modes.

---

# Source: https://rsbuild.dev/guide/debug/build-profiling.md

# Build profiling

Running a performance analysis helps you identify bottlenecks in your project so you can optimize the right areas.

## Using Rsdoctor

Rsdoctor is a build analyzer that visualizes how long each loader and plugin takes to compile.

See [Use Rsdoctor](/guide/debug/rsdoctor.md) for more information.

## Node.js profiling

A build runs both JavaScript and Rust code and incurs communication overhead between them.

JavaScript overhead is usually higher than Rust overhead. Use Node.js profiling to understand where time is spent in JavaScript and pinpoint bottlenecks.

For example, to capture a [CPU profile](https://nodejs.org/docs/v20.17.0/api/cli.html#--cpu-prof), run the following commands from your project root:

```bash
# dev
node --cpu-prof ./node_modules/@rsbuild/core/bin/rsbuild.js dev

# build
node --cpu-prof ./node_modules/@rsbuild/core/bin/rsbuild.js build

# Set higher precision sampling interval
node --cpu-prof --cpu-prof-interval=100 ./node_modules/@rsbuild/core/bin/rsbuild.js build
```

These commands generate a `*.cpuprofile` file. You can use [speedscope](https://github.com/jlfwong/speedscope) to visualize it:

```bash
# Install speedscope
npm install -g speedscope

# View cpuprofile content
# Replace the name with the local file name
speedscope CPU.date.000000.00000.0.001.cpuprofile
```

## Rspack profiling

Set the `RSPACK_PROFILE` environment variable to capture an Rspack build performance profile.

```json title="package.json"
{
  "scripts": {
    "dev:profile": "RSPACK_PROFILE=OVERVIEW rsbuild dev",
    "build:profile": "RSPACK_PROFILE=OVERVIEW rsbuild 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": {
    "dev:profile": "cross-env RSPACK_PROFILE=OVERVIEW rsbuild dev",
    "build:profile": "cross-env RSPACK_PROFILE=OVERVIEW rsbuild build"
  },
  "devDependencies": {
    "cross-env": "^7.0.0"
  }
}
```

After the build finishes or the dev server stops, Rsbuild creates a `.rspack-profile-${timestamp}-${pid}` folder in the current directory. It contains a `rspack.pftrace` file (in versions before 1.4.0, the file name was `trace.json`) generated by Rspack using [tracing](https://github.com/tokio-rs/tracing). The file records the time spent in each phase and can be viewed with [ui.perfetto.dev](https://ui.perfetto.dev/).

:::tip

* When shutting down the dev server, press `CTRL + D` instead of `CTRL + C` so Rspack can finish recording performance data.
* The generated `trace.json` file can be large. Compress it into a zip file before sharing.
* For more information about Rspack profiling, refer to [Rspack - Tracing](https://rspack.rs/contribute/development/tracing).

:::

---

# Source: https://rsbuild.dev/config/performance/bundle-analyze.md

# performance.bundleAnalyze

* **Type:** `Object | undefined`
* **Default:** `undefined`

Used to enable the [webpack-bundle-analyzer](https://github.com/webpack/webpack-bundle-analyzer) plugin to analyze the size of the output.

:::tip
`performance.bundleAnalyze` has been deprecated and will be removed in Rsbuild 2.0. We recommend using [Rsdoctor](/guide/debug/rsdoctor.md) to analyze your bundle size instead.
:::

By default, Rsbuild does not enable `webpack-bundle-analyzer`. When this feature is enabled, the default configuration is as follows:

```js
const defaultConfig = {
  analyzerMode: 'static',
  openAnalyzer: false,
  // Distinguish by environment names, such as `web`, `node`, etc.
  reportFilename: `report-${environment}.html`,
};
```

## Enable bundle analyze

You have two ways to enable `webpack-bundle-analyzer` to analyze the size of the output files.

### Via environment variable

Add the environment variable `BUNDLE_ANALYZE=true`, for example:

```json title="package.json"
{
  "scripts": {
    "build:analyze": "BUNDLE_ANALYZE=true rsbuild build"
  }
}
```

As Windows does not support the above usage, you can also use [cross-env](https://npmjs.com/package/cross-env) to set environment variables. This ensures compatibility across different systems:

```json title="package.json"
{
  "scripts": {
    "build:analyze": "cross-env BUNDLE_ANALYZE=true rsbuild build"
  },
  "devDependencies": {
    "cross-env": "^7.0.0"
  }
}
```

### Via configuration

Configure `performance.bundleAnalyze` to enable it permanently:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    bundleAnalyze: {},
  },
};
```

### Analysis result

After enabling it, Rsbuild will generate an HTML file that analyzes the size of the output files, and print the following log in the terminal:

```bash
Webpack Bundle Analyzer saved report to /Project/my-project/dist/report-web.html
```

You can manually open the file in the browser and view the detail of the bundle size. When an area is larger, it indicates that its corresponding bundle size is larger.

![](https://assets.rspack.rs/rsbuild/assets/bundle-analyzer-example.png)

## Override default configuration

You can override the default configuration through `performance.bundleAnalyze`, such as enabling the server mode:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    bundleAnalyze: process.env.BUNDLE_ANALYZE
      ? {
          analyzerMode: 'server',
          openAnalyzer: true,
        }
      : {},
  },
};
```

## Size types

In the `webpack-bundle-analyzer` panel, you can control size types in the upper left corner (default is `Parsed`):

* `Stat`: The size obtained from the `stats` object of the bundler, which reflects the size of the code before minification.
* `Parsed`: The size of the file on the disk, which reflects the size of the code after minification.
* `Gzipped`: The file size requested in the browser reflects the size of the code after minification and gzip.

## Generate stats.json

By setting `generateStatsFile` to true, stats JSON file will be generated in bundle output directory.

```ts title="rsbuild.config.ts"
export default {
  performance: {
    bundleAnalyze: {
      generateStatsFile: true,
    },
  },
};
```

In the output directory, you will see `stats.json` and `report-web.html` files.

```
└── dist
    ├── stats.json
    └── report-web.html
```

If you do not need the `report-web.html`, you can set `analyzerMode` to `disabled`.

```ts title="rsbuild.config.ts"
export default {
  performance: {
    bundleAnalyze: {
      analyzerMode: 'disabled',
      generateStatsFile: true,
    },
  },
};
```

## Notes

1. Enabling the server mode will cause the `build` process to not exit normally.
2. Enabling `bundleAnalyzer` will reduce build speed. Therefore, this configuration should not be enabled during daily development, and it is recommended to enable it on demand through the `BUNDLE_ANALYZE` environment variable.
3. Since no code minification and other optimizations are performed in the `dev` phase, the real output size cannot be reflected, so it is recommended to analyze the output size in the `build` phase.
4. If the bundleAnalyzer is enabled during the `dev` phase, to ensure that webpack-bundle-analyzer can access the contents of static assets, Rsbuild will automatically enable the [dev.writeToDisk](/config/dev/write-to-disk.md) option.

---

# Source: https://rsbuild.dev/config/tools/bundler-chain.md

# tools.bundlerChain

* **Type:**

```ts
type BundlerChainFn = (
  chain: RspackChain,
  utils: ModifyBundlerChainUtils,
) => Promise<void> | void;
```

* **Default:** `undefined`

import RspackChain from '@en/shared/rspackChain.mdx';

<RspackChain />

You can use rspack-chain to modify the default Rspack config through `tools.bundlerChain`. Its value is a function that takes two arguments:

* The first argument is a `rspack-chain` instance, which you can use to modify the Rspack config.
* The second argument is an utils object, including `env`, `isProd`, `CHAIN_ID`, etc.

> `tools.bundlerChain` will be executed earlier than [tools.rspack](/config/tools/rspack.md), so it will be overridden by `tools.rspack`.

:::tip
The built-in Rspack config in Rsbuild may change with iterations, and these changes will not be reflected in semver. Therefore, your custom config may become invalid when you upgrade Rsbuild.
:::

## Examples

Please refer to: [RspackChain examples](/guide/configuration/rspack.md#use-bundler-chain).

## Utils

### env

* **Type:** `'development' | 'production' | 'test'`

The `env` parameter can be used to determine whether the current environment is development, production or test. For example:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    bundlerChain: (chain, { env }) => {
      if (env === 'development') {
        chain.devtool('cheap-module-eval-source-map');
      }
    },
  },
};
```

### isDev

* **Type:** `boolean`

A boolean value indicating whether this is a development build. Set to `true` when the [mode](/config/mode.md) is `development`.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    bundlerChain: (config, { isDev }) => {
      if (isDev) {
        config.devtool = 'eval-cheap-source-map';
      }
      return config;
    },
  },
};
```

### isProd

* **Type:** `boolean`

A boolean value indicating whether this is a production build. Set to `true` when the [mode](/config/mode.md) is `production`.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    bundlerChain: (chain, { isProd }) => {
      if (isProd) {
        chain.devtool('source-map');
      }
    },
  },
};
```

### target

* **Type:** `'web' | 'node' | 'web-worker'`

The current [build target](/config/output/target.md).

You can set different Rspack configurations for different build targets, for example:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    bundlerChain: (chain, { target }) => {
      if (target === 'node') {
        // ...
        return;
      }
    },
  },
};
```

### isServer

* **Type:** `boolean`

A boolean value indicating whether the [build target](/config/output/target.md) is `node`, equivalent to `target === 'node'`.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    bundlerChain: (chain, { isServer }) => {
      if (isServer) {
        // ...
      }
    },
  },
};
```

### isWebWorker

* **Type:** `boolean`

A boolean value indicating whether the [build target](/config/output/target.md) is `web-worker`, equivalent to `target === 'web-worker'`.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    bundlerChain: (chain, { isWebWorker }) => {
      if (isWebWorker) {
        // ...
      }
    },
  },
};
```

### rspack

* **Type:** `Rspack`

The Rspack instance, the same as `import { rspack } from '@rsbuild/core'`.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    bundlerChain: (chain, { rspack }) => {
      chain.plugin('extra-define').use(rspack.DefinePlugin, [
        {
          'process.env': {
            NODE_ENV: JSON.stringify(process.env.NODE_ENV),
          },
        },
      ]);
    },
  },
};
```

### environment

* **Type:** [EnvironmentContext](/api/javascript-api/environment-api.md#environment-context)

Context information for the current environment.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    bundlerChain: (chain, { environment }) => {
      console.log(environment);
    },
  },
};
```

### environments

* **Type:** `Record<string, EnvironmentContext>`

Context information for all environments.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    bundlerChain: (chain, { environments }) => {
      console.log(environments);
    },
  },
};
```

### HtmlPlugin

* **Type:** `typeof import('html-rspack-plugin')`

The default export of [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin).

```ts title="rsbuild.config.ts"
export default {
  tools: {
    bundlerChain: (chain, { HtmlPlugin }) => {
      console.log(HtmlPlugin);
    },
  },
};
```

## CHAIN\_ID

Some common chain IDs are predefined in the Rsbuild, and you can use these IDs to locate the built-in Rule or Plugin.

:::tip
Please note that some of these rules or plugins are not available by default. They will only be included in the Rspack or webpack configuration when you enable specific options or register certain plugins.

For example, the `RULE.STYLUS` rule exists only when the Stylus plugin is registered.
:::

### CHAIN\_ID.RULE

| ID            | Description                                                               |
| ------------- | ------------------------------------------------------------------------- |
| `RULE.JS`     | Rule for `js` and `ts`                                                    |
| `RULE.SVG`    | Rule for `svg`                                                            |
| `RULE.CSS`    | Rule for `css`                                                            |
| `RULE.LESS`   | Rule for `less`                                                           |
| `RULE.SASS`   | Rule for `sass`                                                           |
| `RULE.YAML`   | Rule for `yaml`                                                           |
| `RULE.WASM`   | Rule for `WASM`                                                           |
| `RULE.FONT`   | Rule for `font`                                                           |
| `RULE.IMAGE`  | Rule for `image`                                                          |
| `RULE.MEDIA`  | Rule for `media`                                                          |
| `RULE.VUE`    | Rule for `vue` (requires [Vue plugin](/plugins/list/plugin-vue.md))          |
| `RULE.SVELTE` | Rule for `svelte` (requires [Svelte plugin](/plugins/list/plugin-svelte.md)) |
| `RULE.STYLUS` | Rule for `stylus` (requires [Stylus plugin](/plugins/list/plugin-stylus.md)) |

### CHAIN\_ID.ONE\_OF

`ONE_OF.[ID]` can match a certain type of rule in the rule array.

| ID                  | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| `ONE_OF.SVG_URL`    | Rules for SVG, output as a separate file                           |
| `ONE_OF.SVG_INLINE` | Rules for SVG, inlined into bundles as data URIs                   |
| `ONE_OF.SVG_ASSETS` | Rules for SVG, automatic choice between data URI and separate file |

### CHAIN\_ID.USE

`USE.[ID]` can match a certain loader.

| ID            | Description                        |
| ------------- | ---------------------------------- |
| `USE.SWC`     | correspond to `builtin:swc-loader` |
| `USE.STYLE`   | correspond to `style-loader`       |
| `USE.POSTCSS` | correspond to `postcss-loader`     |

See [Custom loader](/guide/configuration/rspack.md#custom-loader) for more details.

### CHAIN\_ID.PLUGIN

`PLUGIN.[ID]` can match a certain Rspack or webpack plugin.

See [Custom plugin](/guide/configuration/rspack.md#custom-plugin) for more details.

### CHAIN\_ID.MINIMIZER

`MINIMIZER.[ID]` can match a certain minimizer.

| ID              | Description                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `MINIMIZER.JS`  | correspond to [SwcJsMinimizerRspackPlugin](https://rspack.rs/plugins/rspack/swc-js-minimizer-rspack-plugin)               |
| `MINIMIZER.CSS` | correspond to [LightningCssMinimizerRspackPlugin](https://rspack.rs/plugins/rspack/lightning-css-minimizer-rspack-plugin) |

---

# Source: https://rsbuild.dev/config/output/charset.md

# output.charset

* **Type:** `'ascii' | 'utf8'`
* **Default:** `'utf8'`

The `charset` config sets the [character encoding](https://developer.mozilla.org/en-US/docs/Glossary/Character_encoding) for output files, ensuring they display correctly across different environments.

## UTF8

By default, Rsbuild outputs files encoded in [UTF-8](https://developer.mozilla.org/en-US/docs/Glossary/UTF-8), the most common character encoding for web applications.

```ts title="rsbuild.config.ts"
export default {
  output: {
    charset: 'utf8', // This is the default
  },
};
```

When your web server returns resources, ensure it sends the correct [Content-Type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type) response header so browsers can parse them correctly.

## ASCII

To use [ASCII](https://developer.mozilla.org/en-US/docs/Glossary/ASCII) encoding for output files, configure it like this:

```ts title="rsbuild.config.ts"
export default {
  output: {
    charset: 'ascii',
  },
};
```

With ASCII encoding, all non-ASCII characters are escaped with backslashes, making files slightly larger and harder to read.

## Notes

The `charset` option only affects files compiled with [SWC](/guide/configuration/swc.md), which includes JavaScript and TypeScript files by default. HTML and CSS files are not affected by this option.

For HTML files, Rsbuild adds a `<meta charset="utf-8">` tag by default. You can change this using the [html.meta](/config/html/meta.md) option.

---

# Source: https://rsbuild.dev/config/performance/chunk-split.md

# performance.chunkSplit

* **Type:** `ChunkSplit`
* **Default:** `{ strategy: 'split-by-experience' }`

`performance.chunkSplit` configures the chunk splitting strategy. The type definition for `ChunkSplit`:

::: tip
See the [Code Splitting](/guide/optimization/code-splitting.md) guide for detailed usage.
:::

## chunkSplit.strategy

Rsbuild supports the following chunk splitting strategies:

* [split-by-experience](/guide/optimization/code-splitting.md#split-by-experience): an empirical splitting strategy, automatically splits some commonly used npm packages into chunks of moderate size.
* [split-by-module](/guide/optimization/code-splitting.md#split-by-module): split by npm package granularity, each npm package corresponds to a chunk.
* [split-by-size](/guide/optimization/code-splitting.md#split-by-size): automatically split according to module size.
* [all-in-one](/guide/optimization/code-splitting.md#all-in-one): bundle all codes into one chunk.
* [single-vendor](/guide/optimization/code-splitting.md#single-vendor): bundle all npm packages into a single chunk.
* [custom](/guide/optimization/code-splitting.md#custom-splitting-strategy): custom chunk splitting strategy.

## Type definition

The complete type definition for `performance.chunkSplit`:

```ts
type ForceSplitting = RegExp[] | Record<string, RegExp>;

interface BaseChunkSplit {
  strategy?:
    | 'split-by-module'
    | 'split-by-experience'
    | 'all-in-one'
    | 'single-vendor';
  override?: Rspack.OptimizationSplitChunksOptions;
  forceSplitting?: ForceSplitting;
}

interface SplitBySize extends BaseSplitRules {
  strategy: 'split-by-size';
  minSize?: number;
  maxSize?: number;
}

interface SplitCustom extends BaseSplitRules {
  strategy: 'custom';
  splitChunks?: SplitChunks;
}

type ChunkSplit = BaseChunkSplit | SplitBySize | SplitCustom;
```

### Default strategy

By default, Rsbuild uses the `split-by-experience` strategy. To use other chunk splitting strategies, specify them through the `strategy` option, for example:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    chunkSplit: {
      strategy: 'all-in-one',
    },
  },
};
```

## chunkSplit.minSize

* **Type:** `number`
* **Default:** `10000`

When `chunkSplit.strategy` is `split-by-size`, you can specify the minimum size of a chunk via `chunkSplit.minSize`. The unit is bytes, and the default value is `10000`. For example:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    chunkSplit: {
      strategy: 'split-by-size',
      minSize: 20000,
    },
  },
};
```

## chunkSplit.maxSize

* **Type:** `number`
* **Default:** `Number.POSITIVE_INFINITY`

When `chunkSplit.strategy` is `split-by-size`, you can specify the maximum size of a chunk via `chunkSplit.maxSize`. The unit is bytes, and the default value is `Number.POSITIVE_INFINITY`. For example:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    chunkSplit: {
      strategy: 'split-by-size',
      maxSize: 50000,
    },
  },
};
```

## chunkSplit.forceSplitting

* **Type:** `RegExp[] | Record<string, RegExp>`
* **Default:** `[]`

Via `chunkSplit.forceSplitting`, you can specify npm packages that should be forcibly split.

For example, split the `axios` library under node\_modules into `axios.js`:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    chunkSplit: {
      forceSplitting: {
        axios: /node_modules[\\/]axios/,
      },
    },
  },
};
```

This is an easier way than configuring Rspack's [splitChunks](https://rspack.rs/config/optimization#optimizationsplitchunks) directly.

:::tip
Chunks split using the `forceSplitting` configuration will be inserted into the HTML file as resources requested for the initial screen using `<script>` tags. Therefore, please split them appropriately based on the actual scenario to avoid excessive size of initial screen resources.
:::

## chunkSplit.splitChunks

When `chunkSplit.strategy` is `custom`, you can specify a custom Rspack chunk splitting configuration via `chunkSplit.splitChunks`. This configuration will be merged with the Rspack splitChunks config (the `cacheGroups` config will also be merged). For example:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    chunkSplit: {
      strategy: 'custom',
      splitChunks: {
        cacheGroups: {
          react: {
            test: /node_modules[\\/](react|react-dom)[\\/]/,
            name: 'react',
            chunks: 'all',
          },
        },
      },
    },
  },
};
```

## chunkSplit.override

When `chunkSplit.strategy` is `split-by-experience`, `split-by-module`, `split-by-size`, or `single-vendor`, you can specify a custom Rspack chunk splitting configuration via `chunkSplit.override`. This configuration will be merged with the Rspack splitChunks config (the `cacheGroups` config will also be merged). For example:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    chunkSplit: {
      override: {
        cacheGroups: {
          react: {
            test: /node_modules[\\/](react|react-dom)[\\/]/,
            name: 'react',
            chunks: 'all',
          },
        },
      },
    },
  },
};
```

## Targets

`performance.chunkSplit` only works when [output.target](/config/output/target.md) is `web`. This means that when `output.target` is `node` or `web-worker`, `performance.chunkSplit` will not take effect.

Typically, Node bundles do not need to be split to optimize loading performance. If you need to split Node bundles, you can use the [tools.rspack](/config/tools/rspack.md) configuration to set Rspack's [optimization.splitChunks](https://rspack.rs/plugins/webpack/split-chunks-plugin#optimizationsplitchunks) option:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: {
      optimization: {
        splitChunks: {
          // options
        },
      },
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/output/clean-dist-path.md

# output.cleanDistPath

* **Type:**

```ts
type CleanDistPath = boolean | 'auto' | CleanDistPathObject;
```

* **Default:** `'auto'`

Configure whether to clean all files in the output directory before the build starts. The output directory is the [output.distPath.root](/config/output/dist-path.md) directory.

## Default behavior

The default value of `output.cleanDistPath` is `'auto'`:

* In development mode, if [dev.writeToDisk](/config/dev/write-to-disk.md) is `false`, Rsbuild will not perform cleanup.
* In any mode, if [output.distPath.root](/config/output/dist-path.md) is an external directory or equals the project root directory, Rsbuild will not perform cleanup to avoid accidentally deleting files from other directories.

```ts title="rsbuild.config.ts"
export default {
  output: {
    distPath: {
      root: '../../some-dir',
    },
  },
};
```

## Forced switch

Set `cleanDistPath` to `true` to force enable it, or `false` to force disable it.

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

## Conditional

To clean files only in production mode and not in development mode, configure it as:

```ts title="rsbuild.config.ts"
export default {
  output: {
    cleanDistPath: process.env.NODE_ENV === 'production',
  },
};
```

## Options

`output.cleanDistPath` supports configuration as an object to achieve more granular control.

### enable

* **Type:** `boolean | 'auto'`
* **Default:** `'auto'`

Whether to clean up all files in the output directory before the build starts.

```ts title="rsbuild.config.ts"
export default {
  output: {
    // Equivalent to `cleanDistPath: true`
    cleanDistPath: {
      enable: true,
    },
  },
};
```

### keep

* **Type:** `RegExp[]`
* **Default:** `undefined`

Specify the files to keep in the output directory. If the file's absolute path matches the regular expression in `keep`, the file will not be removed.

For example, to keep the `dist/foo.json` file:

```ts title="rsbuild.config.ts"
export default {
  output: {
    cleanDistPath: {
      keep: [/dist\/foo.json/],
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/dev/cli-shortcuts.md

# dev.cliShortcuts

* **Type:**

```ts
type CliShortcuts =
  | boolean
  | {
      help?: boolean;
      custom?: (shortcuts: CliShortcut[]) => CliShortcut[];
    };
```

* **Default:** `true` when using Rsbuild CLI, `false` otherwise.
* **Version:** `>= 1.0.11`

Whether to enable CLI shortcuts.

## All shortcuts

Press `h + Enter` to show all shortcuts:

```
  Shortcuts:
  c + enter  clear console
  o + enter  open in browser
  q + enter  quit process
  r + enter  restart server
  u + enter  show urls
```

## Example

* Enable:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    cliShortcuts: true,
  },
};
```

* Disable:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    cliShortcuts: false,
  },
};
```

## Custom shortcuts

`custom` option can be used to custom shortcuts, the value is a function that receives the default shortcuts array and returns a new shortcuts array.

* Add custom shortcuts:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    cliShortcuts: {
      custom: (shortcuts) => {
        return [
          ...shortcuts,
          {
            key: 's',
            description: 'say hello',
            action: () => {
              console.log('hello world!');
            },
          },
        ];
      },
    },
  },
};
```

* Disable some shortcuts:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    cliShortcuts: {
      custom: (shortcuts) => {
        return shortcuts.filter((shortcut) => shortcut.key !== 'o');
      },
    },
  },
};
```

## Print help

`help` option can be used to control whether to print the help hint when the server is started, the default help hint is:

```bash
  ➜ press h + enter to show shortcuts
```

* Disable the help hint:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    cliShortcuts: {
      help: false,
    },
  },
};
```

* Print a custom help hint:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    cliShortcuts: {
      help: 'type "h + enter" to view available commands',
    },
  },
};
```

---

# Source: https://rsbuild.dev/guide/basic/cli.md

# CLI

Rsbuild includes a lightweight CLI with commands like [rsbuild dev](#rsbuild-dev) and [rsbuild build](#rsbuild-build).

## All commands

To view all available CLI commands, run this command in your project directory:

```bash
npx rsbuild -h
```

The output is shown below:

```
Usage:
  $ rsbuild [command] [options]

Commands:
  dev      Start the dev server
  build    Build the app for production
  preview  Preview the production build locally
  inspect  Inspect the Rspack and Rsbuild configurations
```

## Common flags

The Rsbuild CLI includes several common flags that work with all commands:

| Flag                       | Description                                                                                                                                |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `--base <base>`            | Set the base path of the server, see [server.base](/config/server/base.md)                                                                    |
| `-c, --config <config>`    | Set the configuration file (relative or absolute path), see [Specify config file](/guide/configuration/rsbuild.md#specify-config-file)        |
| `--config-loader <loader>` | Set the config file loader (`auto` | `jiti` | `native`), see [Specify config loader](/guide/configuration/rsbuild.md#specify-config-loader) |
| `--env-mode <mode>`        | Set the env mode to load the `.env.[mode]` file, see [Env mode](/guide/advanced/env-vars.md#env-mode)                                         |
| `--env-dir <dir>`          | Set the directory for loading `.env` files, see [Env directory](/guide/advanced/env-vars.md#env-directory)                                    |
| `--environment <name>`     | Set the environment name(s) to build, see [Build specified environment](/guide/advanced/environments.md#build-specified-environment)          |
| `-h, --help`               | Display help for command                                                                                                                   |
| `--log-level <level>`      | Set the log level (`info` | `warn` | `error` | `silent`), see [logLevel](/config/log-level.md)                                             |
| `-m, --mode <mode>`        | Set the build mode (`development` | `production` | `none`), see [mode](/config/mode.md)                                                     |
| `--no-env`                 | Disable loading of `.env` files                                                                                                            |
| `-r, --root <root>`        | Set the project root directory (absolute path or relative to [cwd](https://nodejs.org/api/process.html#processcwd))                        |

## rsbuild dev

The `rsbuild dev` command starts a local dev server and compiles source code for development.

```bash
Usage: rsbuild dev [options]

Options:
  -o, --open [url]      Open the page in browser on startup
  --port <port>         Set the port number for the server
  --host <host>         Set the host that the server listens to
```

Start the dev server by running `rsbuild` directly (equivalent to `rsbuild dev`):

```bash
npx rsbuild
```

### Opening page

The `--open` option opens a page automatically when the dev server starts (equivalent to setting [server.open](/config/server/open.md) to `true`).

```bash
rsbuild dev --open
```

The `--open` option also accepts a specific URL to open. For example:

```bash
rsbuild dev --open http://localhost:3000/foo
```

The `--open` option can also be abbreviated to `-o`:

```bash
rsbuild dev -o
```

:::tip
When using both [server.open](/config/server/open.md) and `--open`, the `--open` option takes precedence.
:::

## rsbuild build

The `rsbuild build` command builds production outputs in the `dist/` directory by default.

```bash
Usage: rsbuild build [options]

Options:
  -w, --watch           Enable watch mode to automatically rebuild on file changes
```

## rsbuild preview

The `rsbuild preview` command previews production build outputs locally. You must run `rsbuild build` first to generate the outputs.

```bash
Usage: rsbuild preview [options]

Options:
  -o, --open [url]      Open the page in browser on startup
  --port <port>         Set a port number for Rsbuild server to listen
  --host <host>         Set the host that the Rsbuild server listens to
```

:::tip
Use the preview command only for local previews. Do not use it in production, as it is not designed for production servers.
:::

## rsbuild inspect

The `rsbuild inspect` command displays the project's Rsbuild and Rspack configurations.

```bash
Usage: rsbuild inspect [options]

Options:
  --output <output>     Set the output path for inspection results (default: ".rsbuild")
  --verbose             Show complete function definitions in output
```

Running `npx rsbuild inspect` in the project root generates the following files in the `dist/.rsbuild` directory:

* `rsbuild.config.mjs`: Represents the Rsbuild configuration used during the build.
* `rspack.config.web.mjs`: Represents the Rspack configuration used during the build.

```bash
➜ npx rsbuild inspect

config inspection completed, generated files:

  - Rsbuild config: /project/dist/.rsbuild/rsbuild.config.mjs
  - Rspack config (web): /project/dist/.rsbuild/rspack.config.web.mjs
```

### Setting mode

By default, the inspect command outputs configuration for development mode. To output production mode configuration, add the `--mode production` option:

```bash
rsbuild inspect --mode production
```

### Verbose content

By default, the inspect command omits function bodies in the configuration object. To output complete function content, add the `--verbose` option:

```bash
rsbuild inspect --verbose
```

### Multiple targets

If the current project has multiple build targets (such as building both browser and Node.js bundles), multiple Rspack configuration files will be generated in the `dist/.rsbuild` directory.

```bash
➜ npx rsbuild inspect

config inspection completed, generated files:

  - Rsbuild config (web): /project/dist/.rsbuild/rsbuild.config.web.mjs
  - Rsbuild config (node): /project/dist/.rsbuild/rsbuild.config.node.mjs
  - Rspack config (web): /project/dist/.rsbuild/rspack.config.web.mjs
  - Rspack config (node): /project/dist/.rsbuild/rspack.config.node.mjs
```

---

# Source: https://rsbuild.dev/config/dev/client.md

# dev.client

Configure the client code injected by Rsbuild during the development process. This can be used to set the WebSocket URL for HMR.

* **Type:**

```ts
type Client = {
  // The protocol name for the WebSocket request
  protocol?: 'ws' | 'wss';
  // The path for the WebSocket request
  path?: string;
  // The port number for the WebSocket request
  port?: string | number;
  // The host for the WebSocket request
  host?: string;
  // The maximum number of reconnection attempts after a WebSocket request is disconnected.
  reconnect?: number;
  // Whether to display an error overlay in the browser when a compilation error occurs
  overlay?: boolean | { runtime?: boolean };
  // Controls the log level for client-side logging in the browser console
  logLevel?: 'info' | 'warn' | 'error' | 'silent';
};
```

* **Default:**

```js
const defaultConfig = {
  path: '/rsbuild-hmr',
  // By default it is set to "location.port"
  port: '',
  // By default it is set to "location.hostname"
  host: '',
  // By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
  protocol: undefined,
  reconnect: 100,
  overlay: true,
  // Inherits from root logLevel, defaults to 'info'
  logLevel: 'info',
};
```

## Configure WebSocket URL

By default, when you start the dev server and visit the `http://localhost:3000/`, a WebSocket request is made to `ws://localhost:3000/rsbuild-hmr`, establishing a connection between the page and the dev server.

In some development scenarios, you may need to adjust the WebSocket URL to ensure that the WebSocket request can connect correctly.

For example, if you are developing using a proxy tool, you may actually be accessing an online domain. In this case, you can manually configure `dev.client` to point the WebSocket URL to your local dev server. Below is an example where the WebSocket request URL is `ws://127.0.0.1:3000/rsbuild-hmr`:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    client: {
      protocol: 'ws',
      // Usually `127.0.0.1` is used to avoid cross-origin requests being blocked by the browser
      host: '127.0.0.1',
      port: 3000,
    },
  },
};
```

### Port placeholder

The port number that Rsbuild server listens on may change. For example, if the port is in use, Rsbuild will automatically increment the port number until it finds an available port.

To avoid `client.port` becoming invalid due to port changes, you can use one of the following methods:

* Enable [server.strictPort](/config/server/strict-port.md).
* Use the `<port>` placeholder to refer to the current port number. Rsbuild will replace the placeholder with the actual port number it is listening on.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    client: {
      port: '<port>',
    },
  },
};
```

## hot-update files

During the HMR process, the page will make GET requests to get hot-update files, including `*.hot-update.json` and `*.hot-update.js`. These files contain the necessary information for hot updates, such as the updated modules and their code.

Hot-update files are considered to be static assets. If you need to configure the URL for hot-update files, please use the [dev.assetPrefix](/config/dev/asset-prefix.md) option.

## Options

### overlay

* **Type:** `boolean`
* **Default:** `true`

The `dev.client.overlay` option allows you to choose whether or not to enable the error overlay feature.

By default, Rsbuild will display an error overlay in the browser when a compilation error occurs, providing error messages and stacks:

![error overlay](https://assets.rspack.rs/rsbuild/assets/rsbuild-error-overlay.png)

To disable the error overlay, set it to `false`:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    client: {
      overlay: false,
    },
  },
};
```

When `overlay` is configured as an object, it allows more fine-grained control over errors from different sources.

#### overlay.runtime

`overlay.runtime` controls whether runtime errors that occur in the browser are rendered in the overlay.

When this option is enabled, Rsbuild captures runtime errors during development, such as JavaScript execution errors and unhandled Promise rejections, and displays them in the error overlay.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    client: {
      overlay: {
        runtime: true,
      },
    },
  },
};
```

:::tip
The error overlay feature requires the current browser to support [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). If the browser does not support it, the overlay will not be displayed.
:::

### logLevel

* **Type:** `'info' | 'warn' | 'error' | 'silent'`
* **Default:** Inherits from root [logLevel](/config/log-level.md), defaults to `info`

The `dev.client.logLevel` option controls the log level for Rsbuild's client-side messages in the browser console.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    client: {
      logLevel: 'warn',
    },
  },
};
```

Optional values:

* `'info'` - Shows all messages (default).
* `'warn'` - Shows warnings and errors only.
* `'error'` - Shows only errors.
* `'silent'` - Suppresses all Rsbuild client logs.

### reconnect

* **Type:** `number`
* **Default:** `100`

Controls the maximum number of automatic reconnection attempts after the WebSocket connection is disconnected.

When the connection is lost, Rsbuild will retry the connection at increasing time intervals. Once the maximum number of attempts is reached, it will stop reconnecting. After a successful reconnection, HMR and related features will be restored automatically.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    client: {
      // Retry up to 3 times
      reconnect: 3,
    },
  },
};
```

Setting this value to `0` disables automatic reconnection. In this case, the connection can only be restored by manually refreshing the page.

## Version history

| Version | Changes                        |
| ------- | ------------------------------ |
| v1.6.13 | Added `logLevel` option        |
| v1.7.0  | Added `overlay.runtime` option |

---

# Source: https://rsbuild.dev/guide/optimization/code-splitting.md

# Code splitting

A good chunk splitting strategy is important for improving application load performance. It leverages browser caching to reduce requests and improve loading speed.

Several [chunk splitting strategies](/guide/optimization/code-splitting.md) are built into Rsbuild to meet the needs of most applications. You can also customize chunk splitting configuration for specific use cases.

> See [Rspack - Code Splitting](https://rspack.rs/guide/optimization/code-splitting) for more details.

## Strategies

> The chunk splitting configuration of Rsbuild is in [performance.chunkSplit](/config/performance/chunk-split.md).

Rsbuild supports the following chunk splitting strategies:

* `split-by-experience`: an empirical splitting strategy that automatically splits some commonly used npm packages into chunks of moderate size.
* `split-by-module`: split by npm package granularity, where each npm package corresponds to a chunk.
* `split-by-size`: automatically split based on module size.
* `all-in-one`: bundle all code into one chunk.
* `single-vendor`: bundle all npm packages into a single chunk.
* `custom`: custom chunk splitting strategy.

::: tip
When using strategies other than `all-in-one`, Rspack's default splitting rules will also take effect. For more details, see [Rspack - SplitChunksPlugin](https://rspack.rs/plugins/webpack/split-chunks-plugin#default-behavior).
:::

## split-by-experience

### Behavior

Rsbuild uses the `split-by-experience` strategy by default, an optimization strategy based on practical experience. When your application uses the following npm packages, they're automatically split into separate chunks:

* `lib-polyfill.js`: Contains `core-js`, `@swc/helpers`, `tslib`
* `lib-axios.js`: Contains `axios`
* `lib-react.js`: Provided by [@rsbuild/plugin-react](/plugins/list/plugin-react.md#splitchunks)
* `lib-vue.js`: Provided by [@rsbuild/plugin-vue](/plugins/list/plugin-vue.md#splitchunks)

This approach groups commonly used packages and splits them into individual chunks, improving browser caching efficiency.

### Config

```ts
export default {
  performance: {
    chunkSplit: {
      strategy: 'split-by-experience',
    },
  },
};
```

### Notes

If the npm packages mentioned above aren't installed or used, the corresponding chunks won't be generated.

## split-by-module

### Behavior

Split each npm package into a separate chunk.

::: warning
This strategy splits node\_modules with the finest granularity. Under HTTP/2, multiplexing can speed up resource loading. However, in non-HTTP/2 environments, use this strategy cautiously due to HTTP head-of-line blocking.
:::

### Config

```ts
export default {
  performance: {
    chunkSplit: {
      strategy: 'split-by-module',
    },
  },
};
```

### Notes

* This configuration splits node\_modules into many smaller chunks, resulting in many file requests.
* With HTTP/2, resource loading accelerates and cache hit rates improve due to multiplexing.
* Without HTTP/2, page loading performance may degrade due to HTTP head-of-line blocking. Use with caution.

## all-in-one

### Behavior

This strategy puts all source code and third-party dependencies in a single chunk.

### Config

```ts
export default {
  performance: {
    chunkSplit: {
      strategy: 'all-in-one',
    },
  },
};
```

### Notes

* This configuration bundles all generated JS code into a single file (except dynamically imported chunks).
* The single JS file may be very large, potentially reducing page loading performance.

To also bundle dynamically imported chunks into a single file, set the [output.asyncChunks](https://rspack.rs/config/output#outputasyncchunks) option in Rspack to `false`:

```js
export default defineConfig({
  performance: {
    chunkSplit: {
      strategy: 'all-in-one',
    },
  },
  tools: {
    rspack: {
      output: {
        asyncChunks: false,
      },
    },
  },
});
```

## single-vendor

### Behavior

This strategy puts third-party dependencies in one chunk and source code in another.

### Config

```ts
export default {
  performance: {
    chunkSplit: {
      strategy: 'single-vendor',
    },
  },
};
```

### Notes

The single vendor file may be very large, potentially reducing page loading performance.

## split-by-size

### Behavior

With this strategy, after setting `minSize` and `maxSize` to fixed values, Rsbuild will automatically split chunks without extra configuration.

### Config

```ts
export default {
  performance: {
    chunkSplit: {
      strategy: 'split-by-size',
      minSize: 30000,
      maxSize: 50000,
    },
  },
};
```

## Custom splitting strategy

Beyond the built-in strategies, you can customize the splitting strategy for specific needs. Custom strategies have two parts:

* Custom group
* Custom Rspack `splitChunks` config

You can combine these custom capabilities with built-in strategies: use built-in strategies for common packages and custom functions for other packages.

### Custom group

Rsbuild supports custom groups, which are more flexible than built-in strategies and simpler than writing Rspack's `splitChunks` config.

For example, split the `axios` library under node\_modules into `axios.js`:

```js
export default {
  performance: {
    chunkSplit: {
      forceSplitting: {
        axios: /node_modules[\\/]axios/,
      },
    },
  },
};
```

Using the `forceSplitting` config, you can easily split packages into chunks.

#### Notes

Chunks split using `forceSplitting` are inserted into the HTML file as initial resources using `<script>` tags. Split them appropriately based on your scenario to avoid excessive initial bundle size.

### Custom config

Beyond custom grouping, you can customize Rspack's `splitChunks` config using `override`. For example:

* Set `minSize` to 30,000 so modules smaller than 30,000 bytes will not be split.

```ts
export default {
  performance: {
    chunkSplit: {
      override: {
        chunks: 'all',
        minSize: 30000,
      },
    },
  },
};
```

* Bundle all CSS files into a single `styles.css`.

```ts
export default {
  performance: {
    chunkSplit: {
      override: {
        cacheGroups: {
          styles: {
            name: 'styles',
            minSize: 0,
            chunks: 'all',
            test: /\.(?:css|less|sass|scss|styl)$/,
            priority: 99,
          },
        },
      },
    },
  },
};
```

The `override` config will be merged with Rspack's `splitChunks` config. For specific config details, see [Rspack - splitChunks](https://rspack.rs/config/optimization#optimizationsplitchunks).

## Using dynamic import for code splitting

Beyond the `chunkSplit` configuration, [dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) is another important optimization technique that can effectively reduce initial bundle size.

:::tip About dynamic import
Dynamic import, introduced in ECMAScript 2020, allows you to load JavaScript modules dynamically. Rspack supports dynamic import by default, so you can use it directly in your code.
:::

When the bundler encounters `import()` syntax, it automatically splits the relevant code into a new chunk and loads it on-demand at runtime.

For example, if your project has a large module called `bigModule.ts` (which can also be a third-party dependency), you can use dynamic import to load it on-demand:

```js
// Somewhere in your code where you need to use bigModule
import('./bigModule.ts').then((bigModule) => {
  // Use bigModule here
});
```

When you run the build command, `bigModule.ts` will be automatically split into a new chunk and loaded on-demand at runtime.

---

# Source: https://rsbuild.dev/config/server/compress.md

# server.compress

* **Type:**

```ts
type Compress =
  | boolean
  | {
      filter?: (req: IncomingMessage, res: ServerResponse) => boolean;
    };
```

* **Default:** `true`

Configure whether to enable [gzip compression](https://developer.mozilla.org/en-US/docs/Glossary/gzip_compression) for static assets served by the dev server or preview server.

## Disable compression

To disable the gzip compression, set `compress` to `false`:

```ts title="rsbuild.config.ts"
export default {
  server: {
    compress: false,
  },
};
```

## Options

### filter

* **Type:** `(req: IncomingMessage, res: ServerResponse) => boolean`
* **Default:** `undefined`
* **Version:** `>= v1.4.4`

A function that determines whether a response should be compressed.

Returns `true` to compress the response, `false` to skip compression.

```ts title="rsbuild.config.ts"
export default {
  server: {
    compress: {
      filter: (req) => {
        if (req.url?.includes('/foo')) {
          return false;
        }
        return true;
      },
    },
  },
};
```

### level

* **Type:** `number`
* **Default:**
  * Dev server: `1` (zlib.constants.Z\_BEST\_SPEED)
  * Preview server: `6` (zlib.constants.Z\_DEFAULT\_COMPRESSION)
* **Version:** `>= v1.4.4`

Used to set the level of zlib compression applied to responses. A higher level will result in better compression, but will take longer to complete; a lower level will result in less compression, but will be much faster. This value is an integer in the range of 0 (no compression) to 9 (maximum compression).

Rsbuild dev server uses [zlib.constants.Z\_BEST\_SPEED](https://nodejs.org/api/zlib.html#constants) as the default compression level, which provides the best compression performance. The preview server sets `level` to [zlib.constants.Z\_DEFAULT\_COMPRESSION](https://nodejs.org/api/zlib.html#constants) by default.

```ts title="rsbuild.config.ts"
export default {
  server: {
    compress: {
      level: 6,
    },
  },
};
```

:::tip
In actual production environments, web servers like Nginx or Apache are commonly used, which may use different compression levels. Therefore, you might observe differences between the file sizes after gzip compression in your local environment compared to production.
:::

---

# Source: https://rsbuild.dev/config/resolve/condition-names.md

# resolve.conditionNames

* **Type:** `string[]`
* **Default:** Same as Rspack's [resolve.conditionNames](https://rspack.rs/config/resolve#resolveconditionnames)
* **Version:** `>= 1.5.7`

Specifies the condition names used to match entry points in the [`exports` field](https://nodejs.org/api/packages.html#packages_exports) of a package.

## Example

The value of `resolve.conditionNames` overrides the default value of Rsbuild:

```js title="rsbuild.config.ts"
export default {
  resolve: {
    conditionNames: ['require', 'node'],
  },
};
```

## Rspack config

`resolve.conditionNames` is provided by Rspack, see [Rspack - resolve.conditionNames](https://rspack.rs/config/resolve#resolveconditionnames).

You can also configure it using [tools.rspack](/config/tools/rspack.md):

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: {
      resolve: {
        conditionNames: ['custom'],
      },
    },
  },
};
```

The difference between them is how the configuration is merged.

`tools.rspack` merges the configuration arrays based on [webpack-merge](https://github.com/survivejs/webpack-merge), which means `tools.rspack.resolve.conditionNames` will merge with the default value of Rsbuild, rather than overriding it.

---

# Source: https://rsbuild.dev/config/output/copy.md

# output.copy

* **Type:** `Rspack.CopyRspackPluginOptions | Rspack.CopyRspackPluginOptions['patterns']`
* **Default:** `undefined`

Copies the specified file or directory to the dist directory, implemented based on [rspack.CopyRspackPlugin](https://rspack.rs/plugins/rspack/copy-rspack-plugin).

> Please refer to the configuration options here: [rspack.CopyRspackPlugin](https://rspack.rs/plugins/rspack/copy-rspack-plugin).

## Example

Copy files from `./src/assets` to the `./dist` directory:

```ts title="rsbuild.config.ts"
export default {
  output: {
    copy: [
      // `./src/assets/image.png` -> `./dist/image.png`
      { from: './src/assets' },
    ],
  },
};
```

Copy files from `./src/assets` to the `./dist/assets` directory:

```ts title="rsbuild.config.ts"
export default {
  output: {
    copy: [
      // `./src/assets/image.png` -> `./dist/assets/image.png`
      { from: './src/assets', to: 'assets' },
    ],
  },
};
```

When copying files from the public directory to the dist directory during a production build, the `public/someDir` directory will be ignored:

```ts title="rsbuild.config.ts"
export default {
  output: {
    copy: [{ from: './public', globOptions: { ignore: ['**/someDir/**'] } }],
  },
  server: {
    publicDir: {
      copyOnBuild: false,
    },
  },
};
```

---

# Source: https://rsbuild.dev/api/javascript-api/core.md

# Source: https://rsbuild.dev/plugins/dev/core.md

# Plugin API

This page explains the type definitions and usage of Rsbuild plugin APIs.

## RsbuildPlugin

`RsbuildPlugin` is the type of the plugin object. It includes the following properties:

* `name`: The name of the plugin, a unique identifier.
* `setup`: The setup function of the plugin, which can be async. This function runs once when the plugin is initialized. The plugin API provides context, utility functions, and lifecycle hooks. For a complete introduction to lifecycle hooks, see [Plugin hooks](/plugins/dev/hooks.md).
* `apply`: Conditionally apply the plugin during serve or build, see [Conditional application](#conditional-application).
* `enforce`: Specify the execution order of the plugin, see [enforce property](#enforce-property).
* `pre`: Declare the names of pre-plugins, which will be executed before the current plugin, see [Pre-Plugins](#pre-plugins).
* `post`: Declare the names of post-plugins, which will be executed after the current plugin, see [Post-Plugins](#post-plugins).
* `remove`: Declare the plugins that need to be removed, you can pass an array of plugin names, see [Removing plugins](#removing-plugins).

```ts
type RsbuildPlugin = {
  name: string;
  setup: (api: RsbuildPluginAPI) => Promise<void> | void;
  apply?: 'serve' | 'build' | Function;
  enforce?: 'pre' | 'post';
  pre?: string[];
  post?: string[];
  remove?: string[];
};
```

You can import this type from `@rsbuild/core`:

```ts title="pluginFoo.ts"
import type { RsbuildPlugin } from '@rsbuild/core';

export const pluginFoo = (): RsbuildPlugin => ({
  name: 'plugin-foo',

  setup(api) {
    api.onAfterBuild(() => {
      console.log('after build!');
    });
  },
});
```

### Conditional application

By default, plugins are applied for both the dev server and production builds. If you want a plugin to apply only in a specific scenario, you can use the `apply` property to specify when it should be activated:

* `serve`: Applies when running the dev or preview server.
* `build`: Applies when running a production build.

```ts
// This plugin only applies during serve
const pluginServe = () => ({
  name: 'plugin-serve',
  apply: 'serve',
  setup(api) {
    // ...
  },
});

// This plugin only applies during build
const pluginBuild = () => ({
  name: 'plugin-build',
  apply: 'build',
  setup(api) {
    // ...
  },
});
```

The `apply` property can also be a function that receives two parameters: `config` and `context`.

```ts
type RsbuildPluginApplyFn = (
  this: void,
  // The original Rsbuild configuration object (before plugin processing)
  config: RsbuildConfig,
  // Context object
  context: {
    // The current action type
    action: 'dev' | 'build' | 'preview';
  },
) => boolean;
```

The `apply` function returns `true` to apply the plugin or `false` to skip it.

```ts
const pluginBuild = () => ({
  name: 'plugin-build',
  apply(config, { action }) {
    return action === 'build' && config.output?.target === 'web';
  },
  setup(api) {
    // ...
  },
});
```

:::tip
The `apply` property was introduced in `@rsbuild/core` v1.4.8.
:::

### `enforce` property

By default, plugins are executed in the order they are added. Plugins can adjust their execution order by adding an `enforce` property:

* `pre`: Execute the plugin before other plugins
* `post`: Execute the plugin after other plugins

```js
const pluginFoo = () => ({
  name: 'plugin-foo',
  enforce: 'pre',
  setup(api) {
    // ...
  },
});

const pluginBar = () => ({
  name: 'plugin-bar',
  enforce: 'post',
  setup(api) {
    // ...
  },
});
```

This affects the order in which hooks are registered, but if a hook specifies an [order](/plugins/dev/hooks.md#callback-order) property, the `order` takes higher precedence.

:::tip
The `enforce` property was introduced in `@rsbuild/core` v1.4.9.
:::

### Pre-Plugins

By setting the `pre` property, you can force some specific plugins to execute before the current plugin. The `pre` property takes higher precedence than the `enforce` property.

For example, consider the following two plugins:

```ts
const pluginFoo = {
  name: 'plugin-foo',
};

const pluginBar = {
  name: 'plugin-bar',
  pre: ['plugin-foo'],
};
```

The Bar plugin is configured with the Foo plugin in its `pre` property, so the Foo plugin will always be executed before the Bar plugin.

### Post-Plugins

By setting the `post` property, you can force some specific plugins to execute after the current plugin. The `post` property takes higher precedence than the `enforce` property.

```ts
const pluginFoo = {
  name: 'plugin-foo',
};

const pluginBar = {
  name: 'plugin-bar',
  post: ['plugin-foo'],
};
```

The Bar plugin is configured with the Foo plugin in its `post` property, so the Foo plugin will always be executed after the Bar plugin.

### Removing plugins

You can remove other plugins within a plugin using the `remove` property.

```ts
const pluginFoo = {
  name: 'plugin-foo',
};

const pluginBar = {
  name: 'plugin-bar',
  remove: ['plugin-foo'],
};
```

For example, if you register both the Foo and Bar plugins mentioned above, the Foo plugin will not take effect because the Bar plugin declares the removal of the Foo plugin.

If the current plugin is registered as a [specific environment plugin](/guide/advanced/environments.md#add-plugins-for-specified-environment), you can only remove plugins in that environment; global plugins remain in place.

## api.context

`api.context` is a read-only object that provides some context information.

The content of `api.context` is exactly the same as `rsbuild.context`, please refer to [rsbuild.context](/api/javascript-api/instance.md#rsbuildcontext).

* **Example:**

```ts
const pluginFoo = () => ({
  setup(api) {
    console.log(api.context.distPath);
  },
});
```

## api.getRsbuildConfig

import GetRsbuildConfig from '@en/shared/getRsbuildConfig.mdx';

<GetRsbuildConfig />

* **Example:**

```ts
const pluginFoo = () => ({
  setup(api) {
    const config = api.getRsbuildConfig();
    console.log(config.html?.title);
  },
});
```

## api.getNormalizedConfig

import GetNormalizedConfig from '@en/shared/getNormalizedConfig.mdx';

<GetNormalizedConfig />

* **Example:**

```ts
const pluginFoo = () => ({
  setup(api) {
    api.onBeforeBuild(({ bundlerConfigs }) => {
      const config = api.getNormalizedConfig();
      console.log(config.html.title);
    });
  },
});
```

## api.logger

A logger instance used to output log information in a unified format. Use this instead of `console.log` to maintain consistent logging with Rsbuild.

Equivalent to `import { logger } from '@rsbuild/core'`.

* **Version:** `>= 1.4.0`
* **Example:**

```ts
const pluginLogging = () => ({
  setup(api) {
    api.logger.info('This is an info message');
    api.logger.warn('This is a warning message');
    api.logger.error('This is an error message');
  },
});
```

> `api.logger` is based on [rslog](https://github.com/rstackjs/rslog), see [logger](/api/javascript-api/core.md#logger) for more details.

## api.isPluginExists

import IsPluginExists from '@en/shared/isPluginExists.mdx';

<IsPluginExists />

* **Example:**

```ts
export default () => ({
  setup(api) {
    console.log(api.isPluginExists('plugin-foo'));
  },
});
```

Or check if a plugin exists in a specified environment:

```ts
export default () => ({
  setup(api) {
    console.log(api.isPluginExists('plugin-foo', { environment: 'web' }));
  },
});
```

## api.transform

A simplified wrapper around [Rspack loaders](https://rspack.rs/guide/features/loader), `api.transform` lets you easily transform the code of specific modules during the build process.

You can match files by module path, query, or other conditions, and apply custom transformations to their contents.

* **Type:**

```ts
function Transform(
  descriptor: TransformDescriptor,
  handler: TransformHandler,
): void;
```

`api.transform` accepts two params:

* `descriptor`: an object describing the module's matching conditions.
* `handler`: a transformation function that takes the current module code and returns the transformed code.

### Example

For example, match modules with the `.pug` extension and transform them to JavaScript code:

```js
import pug from 'pug';

const pluginPug = () => ({
  name: 'my-pug-plugin',
  setup(api) {
    api.transform({ test: /\.pug$/ }, ({ code }) => {
      const templateCode = pug.compileClient(code, {});
      return `${templateCode}; module.exports = template;`;
    });
  },
});
```

### Descriptor param

The `descriptor` param is an object describing the module's matching conditions.

* **Type:**

```ts
type TransformDescriptor = {
  test?: RuleSetCondition;
  targets?: RsbuildTarget[];
  environments?: string[];
  resourceQuery?: RuleSetCondition;
  raw?: boolean;
  layer?: string;
  issuer?: RuleSetCondition;
  issuerLayer?: string;
  with?: Record<string, RuleSetCondition>;
  mimetype?: RuleSetCondition;
  order?: 'pre' | 'post' | 'default';
};
```

The `descriptor` param supports the following matching conditions:

* `test`: matches module's path (without query), the same as Rspack's [rules\[\].test](https://rspack.rs/config/module-rules#rulestest).

```js
api.transform({ test: /\.md$/ }, ({ code }) => {
  // ...
});
```

* `targets`: matches the Rsbuild [output.target](/config/output/target.md), and applies the current transform function only to the matched targets.

```js
api.transform({ test: /\.md$/, targets: ['web'] }, ({ code }) => {
  // ...
});
```

* `environments`: matches the Rsbuild [environment](/guide/advanced/environments.md) name, and applies the current transform function only to the matched environments.

```js
api.transform({ test: /\.md$/, environments: ['web'] }, ({ code }) => {
  // ...
});
```

* `resourceQuery`: matches module's query, the same as Rspack's [rules\[\].resourceQuery](https://rspack.rs/config/module-rules#rulesresourcequery).

```js
// match raw query: "foo.ext?raw"
api.transform({ resourceQuery: /^\?raw$/ }, ({ code }) => {
  // ...
});
```

* `raw`: if raw is `true`, the transform handler will receive the Buffer type code instead of the string type.

```js
api.transform({ test: /\.node$/, raw: true }, ({ code }) => {
  // ...
});
```

* `layer`: marks the layer of the matching module, can be used to group a group of modules into one layer, the same as Rspack's [rules\[\].layer](https://rspack.rs/config/module-rules#ruleslayer).

```js
api.transform({ test: /\.md$/, layer: 'foo' }, ({ code }) => {
  // ...
});
```

* `issuerLayer`: matches the layer of the module that issues the current module, the same as Rspack's [rules\[\].issuerLayer](https://rspack.rs/config/module-rules#rulesissuerlayer).

```js
api.transform({ test: /\.md$/, issuerLayer: 'foo' }, ({ code }) => {
  // ...
});
```

* `issuer`: matches the absolute path of the module that issues the current module, the same as Rspack's [rules\[\].issuer](https://rspack.rs/config/module-rules#rulesissuer).

```js
api.transform({ test: /\.md$/, issuer: /\.js$/ }, ({ code }) => {
  // ...
});
```

* `with`: matches [import attributes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import/with), the same as Rspack's [rules\[\].with](https://rspack.rs/config/module-rules#ruleswith).

```js
api.transform({ test: /\.md$/, with: { type: 'url' } }, ({ code }) => {
  // ...
});
```

* `mimetype`: Matches modules based on MIME type instead of file extension. It's primarily useful for data URI module (like `data:text/javascript,...`), the same as Rspack's [rules\[\].mimetype](https://rspack.rs/config/module-rules#rulesmimetype).

```js
api.transform({ mimetype: 'text/javascript' }, ({ code }) => {
  // ...
});
```

* `enforce`: Specifies the execution order of the transform function, the same as Rspack's [rules\[\].enforce](https://rspack.rs/config/module-rules#rulesenforce).
  * When `enforce` is `pre`, the transform function will be executed before other transform functions (or Rspack loaders).
  * When `enforce` is `post`, the transform function will be executed after other transform functions (or Rspack loaders).

```js
api.transform({ test: /\.md$/, enforce: 'pre' }, ({ code }) => {
  // ...
});
```

### Handler param

The handler param is a transformation function that takes the current module code and returns the transformed code.

* **Type:**

```ts
type TransformContext = {
  code: string;
  context: string | null;
  resource: string;
  resourcePath: string;
  resourceQuery: string;
  environment: EnvironmentContext;
  addDependency: (file: string) => void;
  addMissingDependency: (file: string) => void;
  addContextDependency: (context: string) => void;
  emitFile: Rspack.LoaderContext['emitFile'];
  importModule: Rspack.LoaderContext['importModule'];
  resolve: Rspack.LoaderContext['resolve'];
};

type TransformResult =
  | string
  | Buffer
  | {
      code: string | Buffer;
      map?: string | Rspack.sources.RawSourceMap | null;
    };

type TransformHandler = (
  context: TransformContext,
) => MaybePromise<TransformResult>;
```

The `handler` function provides the following params:

* `code`: The code of the module.
* `context`: The directory path of the currently processed module. The same as Rspack loader's [this.context](https://rspack.rs/api/loader-api/context#thiscontext).
* `resolve`: Resolve a module specifier. The same as Rspack loader's [this.resolve](https://rspack.rs/api/loader-api/context#thisresolve).
* `resource`: The absolute path of the module, including the query. The same as Rspack loader's [this.resource](https://rspack.rs/api/loader-api/context#thisresource).
* `resourcePath`: The absolute path of the module, without the query. The same as Rspack loader's [this.resourcePath](https://rspack.rs/api/loader-api/context#thisresourcepath).
* `resourceQuery`: The query of the module. The same as Rspack loader's [this.resourceQuery](https://rspack.rs/api/loader-api/context#thisresourcequery).
* `environment`: The [environment context](/api/javascript-api/environment-api.md#environment-context) for current build.
* `addDependency`: Add an additional file as the dependency. The file will be watched and changes to the file will trigger rebuild. The same as Rspack loader's [this.addDependency](https://rspack.rs/api/loader-api/context#thisadddependency).
* `addMissingDependency`: Add an non-existing file as the dependency. The file will be watched and changes to the file will trigger rebuild. The same as Rspack loader's [this.addMissingDependency](https://rspack.rs/api/loader-api/context#thisaddmissingdependency).
* `addContextDependency`: Add an additional directory as the dependency. The directory will be watched and changes to the directory will trigger rebuild. The same as Rspack loader's [this.addContextDependency](https://rspack.rs/api/loader-api/context#thisaddcontextdependency).
* `emitFile`: Emits a file to the build output. The same as Rspack loader's [this.emitFile](https://rspack.rs/api/loader-api/context#thisemitfile).
* `importModule`: Compile and execute a module at the build time. The same as Rspack loader's [this.importModule](https://rspack.rs/api/loader-api/context#thisimportmodule).

For example:

```js
api.transform(
  { test: /\.md$/ },
  ({ code, resource, resourcePath, resourceQuery }) => {
    console.log(code); // -> some code
    console.log(resource); // -> '/home/user/project/src/template.pug?foo=123'
    console.log(resourcePath); // -> '/home/user/project/src/template.pug'
    console.log(resourceQuery); // -> '?foo=123'
  },
);
```

### Difference with loader

`api.transform` can be thought of as a lightweight implementation of Rspack loader. It provides a simple and easy to use API and automatically calls Rspack loader at the backend to transform the code.

In Rsbuild plugins, you can quickly implement code transformation functions using `api.transform`, which can handle the majority of common scenarios without having to learn how to write an Rspack loader.

Note that for some complex code transformation scenarios, `api.transform` may not be sufficient. In such situations, you can implement it using the Rspack loader.

### Source maps

You can return a source map in the `transform` function, and Rsbuild will automatically merge the returned source map with source maps generated by other Rspack loaders or `transform` hooks, ensuring that the final source map correctly maps back to the original source code.

```js
api.transform({ test: /\.js$/ }, async ({ code }) => {
  const { transformedCode, sourceMap } = await someTransformFunction(code);
  return {
    code: transformedCode,
    map: sourceMap,
  };
});
```

## api.resolve

Intercept and modify module request information before module resolution begins. The same as Rspack's [normalModuleFactory.hooks.resolve](https://rspack.rs/api/plugin-api/normal-module-factory-hooks#resolve) hook.

* **Version:** `>= 1.0.17`
* **Type:**

```ts
function ResolveHook(handler: ResolveHandler): void;
```

### Example

* Modify the request of `a.js` file：

```js
api.resolve(({ resolveData }) => {
  if (resolveData.request === './a.js') {
    resolveData.request = './b.js';
  }
});
```

### Handler param

The `handler` parameter is a callback function that receives a module require information and allows you to modify it.

* **Type:**

```ts
type ResolveHandler = (context: {
  resolveData: Rspack.ResolveData;
  compiler: Rspack.Compiler;
  compilation: Rspack.Compilation;
  environment: EnvironmentContext;
}) => Promise<void> | void;
```

The `handler` function provides the following parameters:

* `resolveData`: Module request information. For details, please refer to [Rspack - resolve hook](https://rspack.rs/api/plugin-api/normal-module-factory-hooks#resolve).
* `compiler`: The Compiler object of Rspack.
* `compilation`: The Compilation object of Rspack.
* `environment`: The environment context of the current build.

## api.processAssets

Modify assets before emitting, the same as Rspack's [compilation.hooks.processAssets](https://rspack.rs/api/plugin-api/compilation-hooks#processassets) hook.

* **Version:** `>= 1.0.0`
* **Type:**

```ts
function processAssets(
  descriptor: ProcessAssetsDescriptor,
  handler: ProcessAssetsHandler,
): void;
```

`api.processAssets` accepts two params:

* `descriptor`: an object to describes the stage and matching conditions that trigger `processAssets`.
* `handler`: A callback function that receives the assets object and allows you to modify it.

### Example

* Emit a new asset in the `additional` stage:

```js
api.processAssets(
  { stage: 'additional' },
  ({ assets, sources, compilation }) => {
    const source = new sources.RawSource('This is a new asset!');
    compilation.emitAsset('new-asset.txt', source);
  },
);
```

* Updating an existing asset:

```js
api.processAssets(
  { stage: 'additions' },
  ({ assets, sources, compilation }) => {
    const asset = assets['foo.js'];
    if (!asset) {
      return;
    }

    const oldContent = asset.source();
    const newContent = oldContent + '\nconsole.log("hello world!")';
    const source = new sources.RawSource(newContent);

    compilation.updateAsset(assetName, source);
  },
);
```

* Removing an asset:

```js
api.processAssets({ stage: 'optimize' }, ({ assets, compilation }) => {
  const assetName = 'unwanted-script.js';
  if (assets[assetName]) {
    compilation.deleteAsset(assetName);
  }
});
```

### Descriptor param

The descriptor parameter is an object to describes the stage and matching conditions that trigger `processAssets`.

* **Type:**

```ts
type ProcessAssetsDescriptor = {
  stage: ProcessAssetsStage;
  targets?: RsbuildTarget[];
  environments?: string[];
};
```

The `descriptor` param supports the following properties:

* `stage`: Rspack internally divides `processAssets` into multiple stages (refer to [process assets stages](#process-assets-stages)). You can choose the appropriate stage based on the operations you need to perform.

```js
api.processAssets({ stage: 'additional' }, ({ assets }) => {
  // ...
});
```

* `targets`: Matches the Rsbuild [output.target](/config/output/target.md), and applies the current processAssets function only to the matched targets.

```js
api.processAssets({ stage: 'additional', targets: ['web'] }, ({ assets }) => {
  // ...
});
```

* `environments`: matches the Rsbuild [environment](/guide/advanced/environments.md) name, and applies the current processAssets function only to the matched environments.

```js
api.processAssets(
  { stage: 'additional', environments: ['web'] },
  ({ assets }) => {
    // ...
  },
);
```

### Handler param

The `handler` parameter is a callback function that receives an assets object and allows you to modify it.

* **Type:**

```ts
type ProcessAssetsHandler = (context: {
  assets: Record<string, Rspack.sources.Source>;
  compiler: Rspack.Compiler;
  compilation: Rspack.Compilation;
  environment: EnvironmentContext;
  sources: RspackSources;
}) => Promise<void> | void;
```

The `handler` function provides the following parameters:

* `assets`: An object where key is the asset's pathname, and the value is data of the asset represented by the [Source](https://github.com/webpack/webpack-sources#source).
* `compiler`: The Compiler object of Rspack.
* `compilation`: The Compilation object of Rspack.
* `environment`: The [environment context](/api/javascript-api/environment-api.md#environment-context) of the current build.
* `sources`: The [Rspack Sources](https://github.com/webpack/webpack-sources#source) object, which contains multiple classes which represent a Source.

### Process assets stages

Here's the list of supported stages. Rspack will execute these stages sequentially from top to bottom. Please select the appropriate stage based on the operation you need to perform.

* `additional` — add additional assets to the compilation.
* `pre-process` — basic preprocessing of the assets.
* `derived` — derive new assets from the existing assets.
* `additions` — add additional sections to the existing assets, e.g., banner or initialization code.
* `optimize` — optimize existing assets in a general way.
* `optimize-count` — optimize the count of existing assets, e.g., by merging them.
* `optimize-compatibility` — optimize the compatibility of existing assets, e.g., add polyfills or vendor prefixes.
* `optimize-size` — optimize the size of existing assets, e.g., by minimizing or omitting whitespace.
* `dev-tooling` — add development tooling to the assets, e.g., by extracting a source map.
* `optimize-inline` — optimize the numbers of existing assets by inlining assets into other assets.
* `summarize` — summarize the list of existing assets.
* `optimize-hash` — optimize the hashes of the assets, e.g., by generating real hashes of the asset content.
* `optimize-transfer` — optimize the transfer of existing assets, e.g., by preparing a compressed (gzip) file as separate asset.
* `analyse` — analyze the existing assets.
* `report` — creating assets for the reporting purposes.

## api.expose

Used for plugin communication.

`api.expose` can explicitly expose some properties or methods of the current plugin, and other plugins can get these APIs through `api.useExposed`.

* **Type:**

```ts
/**
 * @param id Unique identifier, using Symbol can avoid naming conflicts
 * @param api Properties or methods to be exposed, it is recommended to use object format
 */
function expose<T = any>(id: string | symbol, api: T): void;
```

* **Example:**

```ts
const pluginParent = () => ({
  name: 'plugin-parent',
  setup(api) {
    api.expose('plugin-parent', {
      value: 1,
      double: (val: number) => val * 2,
    });
  },
});
```

:::tip
If `api.expose` is called multiple times with the same `id`, the latter call will overwrite the previously exposed API.
:::

## api.useExposed

Used for plugin communication.

`api.useExposed` can get the properties or methods exposed by other plugins.

* **Type:**

```ts
/**
 * @param id Unique identifier
 * @returns The properties or methods obtained
 */
function useExposed<T = any>(id: string | symbol): T | undefined;
```

* **Example:**

```ts
const pluginChild = () => ({
  name: 'plugin-child',
  pre: ['plugin-parent'],
  setup(api) {
    const parentApi = api.useExposed('plugin-parent');
    if (parentApi) {
      console.log(parentApi.value); // -> 1
      console.log(parentApi.double(1)); // -> 2
    }
  },
});
```

### Identifiers

You can use Symbol as a unique identifier to avoid potential naming conflicts:

```ts
// pluginParent.ts
export const PARENT_API_ID = Symbol('plugin-parent');

const pluginParent = () => ({
  name: 'plugin-parent',
  setup(api) {
    api.expose(PARENT_API_ID, {
      // some api
    });
  },
});

// pluginChild.ts
import { PARENT_API_ID } from './pluginParent';

const pluginChild = () => ({
  name: 'plugin-child',
  setup(api) {
    const parentApi = api.useExposed(PARENT_API_ID);
    if (parentApi) {
      console.log(parentApi);
    }
  },
});
```

### Type declaration

You can declare types through the generics of the function:

```ts
// pluginParent.ts
export type ParentAPI = {
  // ...
};

// pluginChild.ts
import type { ParentAPI } from './pluginParent';

const pluginChild = () => ({
  name: 'plugin-child',
  setup(api) {
    const parentApi = api.useExposed<ParentAPI>(PARENT_API_ID);
    if (parentApi) {
      console.log(parentApi);
    }
  },
});
```

### Execution order

When communicating between plugins, you need to be aware of the order in which the plugins are executed.

For example, in the above example, if `pluginParent` is not registered, or registers after `pluginChild`, then `api.useExposed('plugin-parent')` will return an `undefined`.

You can use the `pre`, `post` options of the plugin object, and the `order` option of the plugin hook to ensure the order is correct.

---

# Source: https://rsbuild.dev/config/server/cors.md

# server.cors

* **Type:** `boolean | import('cors').CorsOptions`
* **Default:**

```ts
const defaultAllowedOrigins =
  /^https?:\/\/(?:(?:[^:]+\.)?localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/;

const defaultOptions = {
  // Default allowed:
  // - localhost
  // - 127.0.0.1
  // - [::1]
  origin: defaultAllowedOrigins,
};
```

* **Version:** `>= 1.1.11`

Configure [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) options for the dev server or preview server, based on the [cors](https://github.com/expressjs/cors) middleware.

* `object`：Enable CORS with the specified options.
* `true`：Enable CORS with default options (allow all origins, not recommended).
* `false`：Disable CORS.

:::warning
Using `cors: true` or `cors.origin: '*'` exposes your dev server to all origins and can compromise your source code security. We recommend using the [origin](#origin) option to specify an allowlist of trusted origins instead.
:::

## Example

* Enable CORS for a specific origin:

```ts title="rsbuild.config.ts"
export default {
  server: {
    cors: {
      // Configures the `Access-Control-Allow-Origin` CORS response header
      origin: 'https://example.com',
    },
  },
};
```

* Keep the default origin config of Rsbuild and add additional origins:

```ts title="rsbuild.config.ts"
// `defaultAllowedOrigins` is the default origin value of Rsbuild
import { defaultAllowedOrigins } from '@rsbuild/core';

export default {
  server: {
    cors: {
      origin: [defaultAllowedOrigins, 'https://example.com'],
    },
  },
};
```

* Only enable CORS for the dev server:

```ts title="rsbuild.config.ts"
const isDev = process.env.NODE_ENV === 'development';

export default {
  server: {
    cors: isDev ? { origin: 'https://example.com' } : false,
  },
};
```

* Disable CORS:

```ts title="rsbuild.config.ts"
export default {
  server: {
    cors: false,
  },
};
```

* Enable CORS for all origins (not recommended):

```ts title="rsbuild.config.ts"
export default {
  server: {
    // Equivalent to `{ origin: '*' }`
    cors: true,
  },
};
```

## Options

The `cors` option can be an object, which is the same as the [cors](https://github.com/expressjs/cors) middleware options.

The default configuration is the equivalent of:

```js
const defaultOptions = {
  origin: '*',
  methods: 'GET,HEAD,PUT,PATCH,POST,DELETE',
  preflightContinue: false,
  optionsSuccessStatus: 204,
};
```

### origin

* **Type:**

```ts
type StaticOrigin =
  | boolean
  | string
  | RegExp
  | Array<boolean | string | RegExp>;

type CustomOrigin = (
  requestOrigin: string | undefined,
  callback: (err: Error | null, origin?: StaticOrigin) => void,
) => void;

type Origin = StaticOrigin | CustomOrigin;
```

The `origin` option is used to configure the `Access-Control-Allow-Origin` header:

```ts title="rsbuild.config.ts"
export default {
  server: {
    cors: {
      origin: 'https://example.com',
    },
  },
};
```

Specify multiple allowed origins using an array:

```ts title="rsbuild.config.ts"
export default {
  server: {
    cors: {
      origin: [
        /^https?:\/\/(?:(?:[^:]+\.)?localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/,
        'https://example.com',
      ],
    },
  },
};
```

Use a regular expression to allow all matching origins:

```ts title="rsbuild.config.ts"
export default {
  server: {
    cors: {
      origin: /\.example\.com$/,
    },
  },
};
```

Setting `origin` to a function allows you to dynamically determine the allowed origin, the function receives two parameters:

* `origin`：The origin of the incoming request, `undefined` if no origin is present.
* `callback`：A function to set the allowed origin.

```ts title="rsbuild.config.ts"
export default {
  server: {
    cors: {
      origin: (origin, callback) => {
        // loadMyOrigins is an example call to load a list of origins
        loadMyOrigins((error, origins) => {
          callback(error, origins);
        });
      },
    },
  },
};
```

---

# Source: https://rsbuild.dev/guide/migration/cra.md

# Create React App

This chapter introduces how to migrate a [Create React App](https://github.com/facebook/create-react-app) (CRA) or [CRACO](https://craco.js.org/) project to Rsbuild.

:::tip CRA eject
If your project has already run the CRA `eject` command, then most of the content in this document will no longer be applicable.

After ejecting a CRA project, it becomes more like a project directly using webpack, so you can refer to the [webpack migration guide](/guide/migration/webpack.md).

:::

## Installing dependencies

First, you need to replace the npm dependencies of CRA with Rsbuild's dependencies.

import { PackageManagerTabs } from '@theme';

* Remove CRA dependencies:

<PackageManagerTabs command="remove react-scripts" />

> For projects using CRACO, you can also remove the @craco/craco dependency.

* Install Rsbuild dependencies:

<PackageManagerTabs command="add @rsbuild/core @rsbuild/plugin-react -D" />

## Updating npm scripts

Next, you need to update the npm scripts in package.json to Rsbuild's CLI commands.

```json title="package.json"
{
  "scripts": {
    "start": "react-scripts start", // [!code --]
    "build": "react-scripts build", // [!code --]
    "eject": "react-scripts eject", // [!code --]
    "start": "rsbuild dev", // [!code ++]
    "build": "rsbuild build", // [!code ++]
    "preview": "rsbuild preview" // [!code ++]
  }
}
```

:::tip
Rsbuild doesn't include built-in testing frameworks, so it does not provide a command to replace `react-scripts test`. You can directly use testing frameworks such as [Rstest](https://github.com/web-infra-dev/rstest), Jest or Vitest. Check the [Testing](/guide/advanced/testing.md) section for more details.
:::

## Creating configuration file

Create a Rsbuild configuration file `rsbuild.config.ts` in the same directory as package.json and add the following content:

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

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

## HTML template

CRA uses the `public/index.html` file as the default HTML template. In Rsbuild, you can specify the HTML template through [html.template](/config/html/template.md):

```ts title="rsbuild.config.ts"
export default defineConfig({
  html: {
    template: './public/index.html',
  },
});
```

In the HTML template, if you are using the `%PUBLIC_URL%` variable from CRA, replace it with Rsbuild's [assetPrefix variable](/config/html/template-parameters.md) and use a forward slash for concatenation:

```html
<!-- [!code --] -->
<link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
<!-- [!code ++] -->
<link rel="icon" href="<%= assetPrefix %>/favicon.ico" />
```

This completes the basic migration from CRA to Rsbuild. You can now run the `npm run start` command to try starting the dev server.

## Output directory

By default, CRA outputs to the `build` directory, while Rsbuild's default output directory is `dist`.

You can configure Rsbuild's [output.distPath.root](/config/output/dist-path.md) option to change the directory to `build`, in line with CRA:

```ts title="rsbuild.config.ts"
export default {
  output: {
    distPath: {
      root: 'build',
    },
  },
};
```

> For more details, please refer to the [Output Files](/guide/basic/output-files.md) section.

## Using CSS preprocessors

Rsbuild supports CSS preprocessors such as Sass and Less through plugins. Please refer to:

* [Sass Plugin](/plugins/list/plugin-sass.md)
* [Less Plugin](/plugins/list/plugin-less.md)
* [Stylus Plugin](/plugins/list/plugin-stylus.md)

## Using SVGR

If you are using the "SVG to React Component" feature of CRA (i.e., [SVGR](https://react-svgr.com/)), you also need to install the SVGR plugin for Rsbuild.

For example, if you are using the following usage:

```jsx
import { ReactComponent as Logo } from './logo.svg';

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

You only need to install and register `@rsbuild/plugin-svgr`:

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

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

Please refer to the [SVGR plugin](/plugins/list/plugin-svgr.md) documentation to learn how to use SVGR in Rsbuild.

## Config migration

Here is the corresponding Rsbuild configuration for [CRA configuration](https://create-react-app.dev/docs/advanced-configuration/):

| CRA                     | Rsbuild                                                                                         |
| ----------------------- | ----------------------------------------------------------------------------------------------- |
| HOST                    | [server.host](/config/server/host.md)                                                              |
| PORT                    | [server.port](/config/server/port.md)                                                              |
| HTTPS                   | [server.https](/config/server/https.md)                                                            |
| WDS\_SOCKET\_HOST         | [dev.client.host](/config/dev/client.md)                                                           |
| WDS\_SOCKET\_PATH         | [dev.client.path](/config/dev/client.md)                                                           |
| WDS\_SOCKET\_PORT         | [dev.client.port](/config/dev/client.md)                                                           |
| PUBLIC\_URL              | [dev.assetPrefix](/config/dev/asset-prefix.md) / [output.assetPrefix](/config/output/asset-prefix.md) |
| BUILD\_PATH              | [output.distPath](/config/output/dist-path.md)                                                     |
| GENERATE\_SOURCEMAP      | [output.sourceMap](/config/output/source-map.md)                                                   |
| IMAGE\_INLINE\_SIZE\_LIMIT | [output.dataUriLimit](/config/output/data-uri-limit.md)                                            |
| FAST\_REFRESH            | [dev.hmr](/config/dev/hmr.md)                                                                      |
| TSC\_COMPILE\_ON\_ERROR    | [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check)             |

Notes:

* The above table does not cover all configurations of CRA, feel free to add more.

## Compile node\_modules

By default, CRA uses Babel to compile dependencies in node\_modules, but Rsbuild does not, to avoid the performance overhead and potential compilation errors caused by secondary compilation.

To handle syntax compatibility issues caused by dependencies in node\_modules, you can use the [source.include](/config/source/include.md#compile-node_modules) config to compile node\_modules.

```ts title="rsbuild.config.ts"
export default {
  source: {
    // Compile all JS files and exclude core-js
    include: [{ not: /[\\/]core-js[\\/]/ }],
  },
};
```

## Environment variables

CRA injects environment variables starting with `REACT_APP_` into the client code by default, while Rsbuild injects environment variables starting with `PUBLIC_` by default (see [public variables](/guide/advanced/env-vars.md#public-variables)).

To be compatible with CRA's behavior, you can manually call Rsbuild's [loadEnv](/api/javascript-api/core.md#loadenv) method to read environment variables starting with `REACT_APP_`, and inject them into the client code through the [source.define](/config/source/define.md) config.

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

const { publicVars } = loadEnv({ prefixes: ['REACT_APP_'] });

export default defineConfig({
  source: {
    define: publicVars,
  },
});
```

Note that CRA allows access to the full `process.env` object in the code and also allows destructuring of `process.env`. However, Rsbuild does not define the `process.env` object due to bundle size and security concerns.

```ts title="src/index.js"
// In CRA, you can access it like this
const { PUBLIC_URL } = process.env;
console.log(PUBLIC_URL);
console.log(process.env);
```

In Rsbuild, you can use the [source.define](/config/source/define.md) config to set `process.env` and read the `rawPublicVars` returned by the `loadEnv` method to allow the above usage:

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

const { publicVars, rawPublicVars } = loadEnv({ prefixes: ['REACT_APP_'] });

export default defineConfig({
  source: {
    define: {
      ...publicVars,
      'process.env': JSON.stringify(rawPublicVars),
    },
  },
});
```

## Import unknown assets

In CRA, if you import an asset that the build tool cannot recognize, CRA will by default output the file to the `build/static/media` directory, for example, the `document.pdf` file:

```js title="index.js"
import document from './document.pdf';
```

In Rsbuild, when you import unrecognized assets, Rsbuild will output error logs:

```
You may need an appropriate loader to handle this file type.
```

To resolve this error, you can use the following methods:

* Configure a suitable loader to handle this type of asset via [tools.rspack](/config/tools/rspack.md).
* Configure [asset modules](https://rspack.rs/guide/features/asset-module) rule to handle this type of asset via [tools.rspack](/config/tools/rspack.md).

For example, you can add the following asset modules config to get the same output result as CRA:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: {
      module: {
        rules: [
          {
            // Match .png asset
            // You can change this regular expression to match different types of files
            test: /\.png$/,
            type: 'asset/resource',
            generator: {
              filename: 'static/media/[name].[hash][ext]',
            },
          },
        ],
      },
    },
  },
};
```

## Remove react-app-polyfill

CRA provides [react-app-polyfill](https://npmjs.com/package/react-app-polyfill) to manually inject polyfill code.

In the Rsbuild project, you can remove the dependency and code related to react-app-polyfill, as Rsbuild will automatically read the browserslist config and allow you to enable polyfill injection through the [output.polyfill](/config/output/polyfill.md) config.

1. Remove the `react-app-polyfill` reference:

```ts title="src/index.js"
import 'react-app-polyfill/ie11'; // [!code --]
import 'react-app-polyfill/stable'; // [!code --]
```

2. Configure [output.polyfill](/config/output/polyfill.md):

```ts title="rsbuild.config.ts"
export default {
  output: {
    polyfill: 'usage',
  },
};
```

> Read [Browser compatibility](/guide/advanced/browser-compatibility.md) to understand how Rsbuild handles polyfills.

## Setup ESLint

CRA uses ESLint to lint the code by default. Rsbuild does not include linting by default, but you can add a separate npm script to run ESLint in `package.json`.

First, install [eslint](https://eslint.org/) and [eslint-config-react-app](https://npmjs.com/package/eslint-config-react-app), you need to install ESLint v8 to keep consistent with CRA:

<PackageManagerTabs command="add eslint@8 eslint-config-react-app -D" />

Then, add the `lint` command in `package.json`, and confirm that the project contains an `eslintConfig` configuration or an independent ESLint configuration file:

```json title="package.json"
{
  "scripts": {
    "lint": "eslint src"
  },
  "eslintConfig": {
    "extends": ["react-app", "react-app/jest"]
  }
}
```

Then, you can use the `npm run lint` command to run ESLint.

### Run ESLint during the build

In addition to adding the `lint` command in `package.json`, you can also add the [@rsbuild/plugin-eslint](https://github.com/rstackjs/rsbuild-plugin-eslint) plugin to maintain the same behavior as CRA.

`@rsbuild/plugin-eslint` allows you to run ESLint during the build process.

```ts title="rsbuild.config.ts"
import { pluginEslint } from '@rsbuild/plugin-eslint';

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

After registering the plugin, ESLint will run automatically during development (`npm run dev`) and production builds (`npm run build`). The plugin will display ESLint warnings and errors in the console output.

:::warning
We do not recommend using the `@rsbuild/plugin-eslint` plugin, as running ESLint during the build process will significantly increase the build time. Instead, we recommend using a separate `lint` command to run ESLint checks.
:::

## Reading jsconfig.json

In non-TypeScript projects, CRA supports reading the `paths` field in jsconfig.json as the path alias.

To use this feature in Rsbuild, refer to the [Path Alias - jsconfig.json](/guide/advanced/alias.md#jsconfigjson).

## CRACO migration

If your project is using [CRACO](https://craco.js.org) to override CRA configuration, you can refer to the table below for migration:

| CRACO                                                                                           | Rsbuild                                                                             |
| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [webpack.configure](https://craco.js.org/docs/configuration/webpack/#webpackconfigure)          | [tools.rspack](/config/tools/rspack.md)                                                |
| [webpack.alias](https://craco.js.org/docs/configuration/webpack/#webpackalias)                  | [resolve.alias](/config/resolve/alias.md)                                              |
| [webpack.plugins.add](https://craco.js.org/docs/configuration/webpack/#webpackplugins)          | [appendPlugins of tools.rspack](/config/tools/rspack.md#appendplugins)                 |
| [webpack.plugins.remove](https://craco.js.org/docs/configuration/webpack/#webpackpluginsremove) | [removePlugin of tools.rspack](/config/tools/rspack.md#removeplugin)                   |
| [style.modules](https://craco.js.org/docs/configuration/style/#stylemodules)                    | [output.cssModules](/config/output/css-modules.md)                                     |
| [style.css](https://craco.js.org/docs/configuration/style/#stylecss)                            | [tools.cssLoader](/config/tools/css-loader.md)                                         |
| [style.sass](https://craco.js.org/docs/configuration/style/#stylesass)                          | [Sass Plugin](/plugins/list/plugin-sass.md)                                            |
| [style.postcss](https://craco.js.org/docs/configuration/style/#stylepostcss)                    | [tools.postcss](/config/tools/postcss.md)                                              |
| [babel](https://craco.js.org/docs/configuration/babel/)                                         | [Babel Plugin](/plugins/list/plugin-babel.md)                                          |
| [typescript](https://craco.js.org/docs/configuration/typescript/)                               | [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) |
| [devServer](https://craco.js.org/docs/configuration/devserver/)                                 | [server configs](/config/index.md)                                                     |

### Example

Here is an example of migrating from `webpack.configure` to `tools.rspack`:

* Before migration:

```js title="craco.config.js"
const { whenDev } = require('@craco/craco');

module.exports = {
  webpack: {
    configure: {
      resolve: {
        mainFields: ['browser', 'module', 'main'],
      },
    },
    plugins: [...whenDev(() => [new MyWebpackPlugin()], [])],
  },
};
```

* After migration:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: {
      resolve: {
        mainFields: ['browser', 'module', 'main'],
      },
      plugins:
        process.env.NODE_ENV === 'development' ? [new MyWebpackPlugin()] : [],
    },
  },
};
```

## 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 pull request 🤝.

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

---

# Source: https://rsbuild.dev/config/html/crossorigin.md

# html.crossorigin

* **Type:** `boolean | 'anonymous' | 'use-credentials'`
* **Default:** `false`

Set the [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) attribute of the `<script>` and `<style>` tags.

* If `true` is passed, it will automatically be set to `crossorigin="anonymous"`.
* If `false` is passed, it will not set the `crossorigin` attr.

## Example

```ts title="rsbuild.config.ts"
export default {
  html: {
    crossorigin: 'anonymous',
  },
  output: {
    assetPrefix: 'https://example.com',
  },
};
```

After compilation, the `<script>` tag in HTML becomes:

```html
<script
  defer
  src="https://example.com/static/js/main.js"
  crossorigin="anonymous"
></script>
```

The `<style>` tag becomes:

```html
<link
  href="https://example.com/static/css/main.css"
  rel="stylesheet"
  crossorigin="anonymous"
/>
```

:::tip
If the domain of static assets is the same as the current page, Rsbuild will not add the crossorigin="anonymous" attribute, as this attribute is not required for non-cross-domain scenario.
:::

## Optional values

`crossorigin` can the set to the following values:

* `anonymous`: Request uses CORS headers and credentials flag is set to 'same-origin'. There is no exchange of user credentials via cookies, client-side SSL certificates or HTTP authentication, unless destination is the same origin.
* `use-credentials`: Request uses CORS headers, credentials flag is set to 'include' and user credentials are always included.

---

# Source: https://rsbuild.dev/config/tools/css-extract.md

# tools.cssExtract

* **Type:**

```ts
import type {
  CssExtractRspackPluginOptions,
  CssExtractRspackLoaderOptions,
} from '@rspack/core';

type CSSExtractOptions = {
  pluginOptions?: CssExtractRspackPluginOptions;
  loaderOptions?: CssExtractRspackLoaderOptions;
};
```

* **Default:**

```js
const defaultOptions = {
  pluginOptions: {
    ignoreOrder: true,
    // The default value is determined by the output.distPath and output.filename options of Rsbuild
    filename: 'static/css/[name].css',
    chunkFilename: 'static/css/async/[name].css',
  },
  loaderOptions: {},
};
```

* **Version:** `>= 0.7.0`

Rsbuild uses the CssExtractRspackPlugin plugin by default to extract CSS into separate files.

The options for [CssExtractRspackPlugin](https://rspack.rs/plugins/rspack/css-extract-rspack-plugin) can be changed through `tools.cssExtract`.

## pluginOptions

* **Type:** `CssExtractRspackPluginOptions`
* **Example:**

```ts title="rsbuild.config.ts"
export default {
  tools: {
    cssExtract: {
      pluginOptions: {
        ignoreOrder: false,
      },
    },
  },
};
```

## loaderOptions

* **Type:** `CssExtractRspackLoaderOptions`
* **Example:**

```ts title="rsbuild.config.ts"
export default {
  tools: {
    cssExtract: {
      loaderOptions: {
        esModule: false,
      },
    },
  },
};
```

> Please refer to the [CssExtractRspackPlugin](https://rspack.rs/plugins/rspack/css-extract-rspack-plugin) plugin documentation to learn about all available options.

---

# Source: https://rsbuild.dev/guide/styling/css-in-js.md

# CSS-in-JS

This document outlines how to use common CSS-in-JS libraries in Rsbuild.

Although the examples are based on React, some CSS-in-JS libraries (such as [vanilla-extract](#vanilla-extract)) also support other frameworks.

### Use Emotion

Rsbuild supports compiling [Emotion](https://github.com/emotion-js/emotion). Add the following configuration to enable it:

* [swcReactOptions.importSource](/plugins/list/plugin-react.md#swcreactoptions)
* [@swc/plugin-emotion](https://npmjs.com/package/@swc/plugin-emotion)

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

export default defineConfig({
  plugins: [
    pluginReact({
      swcReactOptions: {
        importSource: '@emotion/react',
      },
    }),
  ],
  tools: {
    swc: {
      jsc: {
        experimental: {
          plugins: [['@swc/plugin-emotion', {}]],
        },
      },
    },
  },
});
```

> Refer to this example: [emotion](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/emotion).

### Use styled-jsx

You can use [styled-jsx](https://github.com/vercel/styled-jsx) through [@swc/plugin-styled-jsx](https://npmjs.com/package/@swc/plugin-styled-jsx):

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

export default defineConfig({
  plugins: [pluginReact()],
  tools: {
    swc: {
      jsc: {
        experimental: {
          plugins: [['@swc/plugin-styled-jsx', {}]],
        },
      },
    },
  },
});
```

Make sure to choose the SWC plugin version that matches your current `@swc/core` version so SWC can run correctly. See [tools.swc](/config/tools/swc.md).

> Refer to this example: [styled-jsx](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/styled-jsx).

### Use vanilla-extract

Rsbuild supports [@vanilla-extract/webpack-plugin](https://npmjs.com/package/@vanilla-extract/webpack-plugin). Add the following config to use [vanilla-extract](https://github.com/vanilla-extract-css/vanilla-extract):

Currently, Rspack has an [HMR issue](https://github.com/web-infra-dev/rsbuild/issues/6049) when `splitChunks` is used with `@vanilla-extract/webpack-plugin`. In development mode, you can use a dedicated `splitChunks` configuration to avoid the issue.

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

export default defineConfig({
  plugins: [
    pluginReact({
      reactRefreshOptions: {
        exclude: [/\.css\.ts$/],
      },
    }),
  ],
  performance: {
    chunkSplit: {
      override: {
        cacheGroups: {
          vanilla: {
            test: /@vanilla-extract\/webpack-plugin/,
            // make sure the chunk contains modules created by @vanilla-extract/webpack-plugin has stable id in development mode to avoid HMR issues
            name: process.env.NODE_ENV === 'development' && 'vanilla',
            chunks: 'all',
          },
        },
      },
    },
  },
  tools: {
    rspack: {
      plugins: [new VanillaExtractPlugin()],
    },
  },
});
```

> Refer to this example: [vanilla-extract](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/vanilla-extract).

#### Static assets

When importing static assets, use import syntax:

```ts title="src/App.css.ts"
import { style } from '@vanilla-extract/css';
import logoUrl from './logo.png';

export const containerStyle = style({
  backgroundImage: `url(${logoUrl})`,
});
```

Since `logoUrl` already resolves to the dist directory, `css-loader` doesn't need to process it again. Disable CSS URL processing via [tools.cssLoader.url](/config/tools/css-loader.md) to avoid module resolution errors:

```ts title="rsbuild.config.ts"
export default defineConfig({
  // ... other config
  tools: {
    cssLoader: {
      url: false,
    },
  },
});
```

> Reference: [#6215](https://github.com/web-infra-dev/rsbuild/issues/6215).

### Use StyleX

You can use [StyleX](https://github.com/facebook/stylex) via [unplugin-stylex](https://github.com/eryue0220/unplugin-stylex):

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

export default defineConfig({
  plugins: [pluginReact()],
  tools: {
    rspack: {
      plugins: [stylexPlugin()],
    },
  },
});
```

> Refer to this example: [stylex](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/stylex).

### Use styled-components

[styled-components](https://github.com/styled-components/styled-components) is a runtime library, so you can use it directly without additional configuration.

Rsbuild supports compiling styled-components, improving the debugging experience and adding SSR support to styled-components.

To use styled-components, we recommend using the [@rsbuild/plugin-styled-components](https://github.com/rsbuild-contrib/rsbuild-plugin-styled-components).

```ts title="rsbuild.config.ts"
import { defineConfig } from '@rsbuild/core';
import { pluginStyledComponents } from '@rsbuild/plugin-styled-components';

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

> Refer to this example: [styled-components](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/styled-components).

:::tip
styled-components is no longer recommended for new projects as it is in [maintenance mode](https://opencollective.com/styled-components/updates/thank-you).
:::

---

# Source: https://rsbuild.dev/config/tools/css-loader.md

# tools.cssLoader

* **Type:** `Object | Function`

```js
const defaultOptions = {
  modules: rsbuildConfig.output.cssModules,
  sourceMap: rsbuildConfig.output.sourceMap.css,
};
```

Rsbuild uses [css-loader](https://github.com/webpack/css-loader) by default to handle CSS resources. You can modify the options of css-loader through `tools.cssLoader`.

:::tip
To modify the options related to CSS Modules, it is recommended to use the [output.cssModules](/config/output/css-modules.md) config first.
:::

### Object type

When this value is an Object, it is merged with the default config via deep merge. For example:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    cssLoader: {
      modules: {
        exportOnlyLocals: true,
      },
    },
  },
};
```

### Function type

When the value is a Function, the default config is passed in as the first parameter. You can modify the config object directly, or return an object as the final config. For example:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    cssLoader: (config) => {
      config.modules.exportOnlyLocals = true;
      return config;
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/output/css-modules.md

# Source: https://rsbuild.dev/guide/styling/css-modules.md

# CSS Modules

[CSS Modules](https://github.com/css-modules/css-modules) allows you to write CSS in a modular way, and import these styles in JavaScript files. CSS Modules automatically generates unique class names, isolating styles between modules and avoiding class name conflicts.

Rsbuild 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`

## Usage example

Write styles in a `*.module.css` file:

```css title="button.module.css"
.red {
  background: red;
}
```

Import styles in a JavaScript file:

```tsx title="Button.tsx"
import styles from './button.module.css';

export default () => {
  return <button className={styles.red}>Button</button>;
};
```

After compilation, CSS Modules class names are automatically appended with a hash value to prevent class name conflicts:

```css
/* classnames generated in development mode */
.src-App-module__red-hiQIE4 {
  background: red;
}

/* classnames generated in production mode */
.red-hiQIE4 {
  background: red;
}
```

:::tip
See [Custom Class Names](#custom-class-names) to modify the class name generation rules.
:::

## Named import

If you prefer to use named imports in CSS Modules, you can enable it through the [output.cssModules.namedExport](/config/output/css-modules.md#cssmodulesnamedexport) config.

```ts title="rsbuild.config.ts"
export default {
  output: {
    cssModules: {
      namedExport: true,
    },
  },
};
```

If enabled, you can reference class names using named imports:

```tsx title="Button.tsx"
import { red } from './button.module.css';

export default () => {
  return <button className={red}>Button</button>;
};
```

## CSS Modules recognition rules

By default, only files ending with `*.module.css` are recognized as CSS Modules.

If you want to treat other CSS files as CSS Modules, you can configure [output.cssModules.auto](/config/output/css-modules.md#cssmodulesauto).

For example:

```ts
export default {
  output: {
    cssModules: {
      auto: (resource) => {
        return resource.includes('.module.') || resource.includes('shared/');
      },
    },
  },
};
```

After this configuration, the following two files will be recognized as CSS Modules:

```ts
import styles1 from './foo.module.css';
import styles2 from './shared/bar.css';
```

## Custom class names

Customizing class names generated by CSS Modules is a commonly used feature. You can configure this using [output.cssModules.localIdentName](/config/output/css-modules.md#cssmoduleslocalidentname).

```ts
export default {
  output: {
    cssModules: {
      localIdentName: '[hash:base64:4]',
    },
  },
};
```

If you need to customize other configs of CSS Modules, you can set them via [output.cssModules](/config/output/css-modules.md).

## Global styles

In some cases, you may need to use global styles in CSS Modules, such as overriding the styles of third-party libraries or setting global styles for specific elements.

CSS Modules provides the `:global()` pseudo-class selector for this purpose. Selectors inside `:global()` retain their original class names, allowing them to correctly match global elements.

```css title="styles.module.css"
/* Local selectors, will be hashed */
.container {
  padding: 20px;
}

/* Global selectors, will not be hashed */
:global(.foo) {
  color: red;
}

/* Use local and global selectors together, only .wrapper will be hashed */
.wrapper :global(.bar) {
  margin: 10px;
}
```

You can also nest `:global()`:

```css title="card.module.css"
.card {
  /* Only affects .btn elements inside .card */
  :global(.btn) {
    background: blue;
  }
}
```

## Type declaration

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

```
TS2307: Cannot find module './index.module.css' or its corresponding type declarations.
```

To fix this, you need to add a type declaration file for CSS Modules. Create a `src/env.d.ts` file and add the corresponding type declaration.

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

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

* Method 2: Manually add the required type declarations:

```ts title="src/env.d.ts"
declare module '*.module.css' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.scss' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.sass' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.less' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.styl' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.stylus' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
```

* Method 3: If you need to use **named imports** to reference class names, you can use a looser type declaration:

```ts title="src/env.d.ts"
declare module '*.module.css';
declare module '*.module.scss';
declare module '*.module.sass';
declare module '*.module.less';
declare module '*.module.styl';
declare module '*.module.stylus';
```

After adding the type declaration, if the type error persists, try restarting your IDE or adjusting the directory where `env.d.ts` is located to ensure TypeScript can correctly identify the type definition.

## Type generation

The above method provides types for CSS Modules, but cannot accurately indicate which class names are exported by a specific CSS file.

Rsbuild supports generating accurate type declarations for CSS Modules. Register the [@rsbuild/plugin-typed-css-modules](https://github.com/rstackjs/rsbuild-plugin-typed-css-modules) plugin and run the build to generate type declaration files for all CSS Modules.

```ts title="rsbuild.config.ts"
import { pluginTypedCSSModules } from '@rsbuild/plugin-typed-css-modules';

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

### Example

For example, create two files named `src/index.ts` and `src/index.module.css`:

```tsx title="src/index.ts"
import styles from './index.module.css';

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

```css title="src/index.module.css"
.page-header {
  color: black;
}
```

After building, Rsbuild will generate a `src/index.module.css.d.ts` type declaration file:

```ts title="src/index.module.css.d.ts"
interface CssExports {
  'page-header': string;
  pageHeader: string;
}
declare const cssExports: CssExports;
export default cssExports;
```

Now when you open the `src/index.ts` file, you'll see that the `styles` object has accurate types.

---

# Source: https://rsbuild.dev/guide/styling/css-usage.md

# CSS

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

Rsbuild also provides several configurations to customize CSS file processing.

## 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.
:::

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

### Features

* Lightning CSS automatically adds vendor prefixes like `-webkit-`, `-moz-`, `-ms-`, etc., so you don't need to manually add prefixes or use the [autoprefixer](https://github.com/postcss/autoprefixer) plugin.
* Lightning CSS automatically downgrades CSS syntax, allowing you to use modern CSS features such as CSS nesting and custom media queries without worrying about browser compatibility.
* Use [tools.lightningcssLoader](/config/tools/lightningcss-loader.md) to customize `lightningcss-loader` options.

### Disabling Lightning CSS

If Lightning CSS does not meet your needs, you can disable Lightning CSS and use [PostCSS](#using-postcss) to transform your CSS code.

Steps:

1. Set [tools.lightningcssLoader](/config/tools/lightningcss-loader.md) to `false` to disable the Lightning CSS loader.
2. Use [@rsbuild/plugin-css-minimizer](https://github.com/rstackjs/rsbuild-plugin-css-minimizer) to switch the CSS minifier from Lightning CSS to cssnano or another CSS minifier.

```ts title="rsbuild.config.ts"
import { pluginCssMinimizer } from '@rsbuild/plugin-css-minimizer';

export default {
  plugins: [pluginCssMinimizer()],
  tools: {
    lightningcssLoader: false,
  },
};
```

3. Refer to [PostCSS](#postcss) to configure the PostCSS plugins you need. Here are some commonly used PostCSS plugins:

* [autoprefixer](https://github.com/postcss/autoprefixer): Adds vendor prefixes.
* [postcss-preset-env](https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env): Converts modern CSS into something most browsers can understand.
* [postcss-nesting](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-nesting): Supports CSS nesting.

## CSS minification

When building for production, Rsbuild enables Rspack's built-in [LightningCssMinimizerRspackPlugin](https://rspack.rs/plugins/rspack/lightning-css-minimizer-rspack-plugin) plugin to minify CSS assets for better transmission efficiency.

* You can disable CSS minification using the [output.minify](/config/output/minify.md) option or customize the options for `LightningCssMinimizerRspackPlugin`.
* 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.

## PostCSS

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

### Configuration file

Rsbuild 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.js`:

```js title="postcss.config.cjs"
module.exports = {
  '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 Rsbuild's [tools.postcss](/config/tools/postcss.md) option, which supports modifying the built-in configuration through a function, for example:

```ts title="rsbuild.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, Rsbuild will not register `postcss-loader`.

## CSS Modules

Rsbuild supports CSS Modules by default, please read the [CSS Modules](/guide/styling/css-modules.md) chapter for the complete usage of CSS Modules.

## CSS preprocessors

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

* [Sass Plugin](/plugins/list/plugin-sass.md)
* [Less Plugin](/plugins/list/plugin-less.md)
* [Stylus Plugin](/plugins/list/plugin-stylus.md)

## CSS-in-JS

See [CSS-in-JS](/guide/styling/css-in-js.md) to learn how to use common CSS-in-JS libraries in Rsbuild.

## Inline CSS files

By default, Rsbuild 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/output/inject-styles.md) 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
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

Rsbuild supports importing CSS files from `node_modules`.

* Import in a JS file:

```ts title="src/index.js"
/* reference 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

### inline

Rsbuild 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

* Rsbuild's Sass, Less, and Stylus plugins also support the `?inline` query parameter.
* Rsbuild >= 1.3.0 supports the `?inline` query parameter.

:::

### raw

Rsbuild 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

* Rsbuild's Sass, Less, and Stylus plugins also support the `?raw` query parameter.
* Rsbuild >= 1.3.0 supports the `?raw` query parameter.

:::

---

# Source: https://rsbuild.dev/config/output/data-uri-limit.md

# output.dataUriLimit

* **Type:**

```ts
type DataUriLimit =
  | number
  | {
      svg?: number;
      font?: number;
      image?: number;
      media?: number;
      assets?: number;
    };
```

* **Default:**

```js
const defaultDatUriLimit = {
  svg: 4096,
  font: 4096,
  image: 4096,
  media: 4096,
  assets: 4096,
};
```

Set the size threshold to inline static assets such as images and fonts.

By default, static assets will be Base64 encoded and inlined into the page if they are smaller than 4KiB.

You can adjust this threshold by setting the `dataUriLimit` config.

Details:

* `svg`: The threshold for SVG images.
* `font`: The threshold for font files.
* `image`: The threshold for non-SVG images.
* `media`: The threshold for media assets such as videos.
* `assets`: The threshold for other static assets, such as those defined in [Extend Asset Types](/guide/basic/static-assets.md#extend-asset-types).

> See [Inline static assets](/guide/optimization/inline-assets.md) for more details.

## Example

* Inline all static assets less than 10KiB:

```ts title="rsbuild.config.ts"
export default {
  output: {
    dataUriLimit: 10 * 1024,
  },
};
```

* Disable inlining of static assets:

```ts title="rsbuild.config.ts"
export default {
  output: {
    dataUriLimit: 0,
  },
};
```

* Inline all static assets:

```ts title="rsbuild.config.ts"
export default {
  output: {
    dataUriLimit: Number.MAX_SAFE_INTEGER,
  },
};
```

* Set the threshold for image assets to 5KiB and do not inline video assets:

```ts title="rsbuild.config.ts"
export default {
  output: {
    dataUriLimit: {
      image: 5 * 1024,
      media: 0,
    },
  },
};
```

---

# Source: https://rsbuild.dev/guide/debug/debug-mode.md

# Debug mode

Rsbuild provides a debug mode to troubleshoot problems. Add the `DEBUG=rsbuild` environment variable when you run a build to enable it.

```bash
# Debug in development mode
DEBUG=rsbuild pnpm dev

# Debug in production mode
DEBUG=rsbuild pnpm build
```

In debug mode, Rsbuild prints additional log information and writes the Rsbuild and Rspack configs to the `dist` directory so you can inspect them.

## Log information

In debug mode, the terminal shows logs that start with `rsbuild`, including internal operations and the Rspack version in use.

```bash
$ DEBUG=rsbuild pnpm dev

  ...
  rsbuild 10:00:00 configuration loaded from: /path/to/...
  rsbuild 10:00:00 registering default plugins
  rsbuild 10:00:00 default plugins registered
  ...
```

Rsbuild also prints the following message to indicate that it has written the generated build configurations to disk. Open these files to review the contents.

```bash
config inspection completed, generated files:

   - Rsbuild config: /Project/demo/dist/.rsbuild/rsbuild.config.mjs
   - Rspack config (web): /Project/demo/dist/.rsbuild/rspack.config.web.mjs
```

## Rsbuild config file

In debug mode, Rsbuild automatically generates a `dist/.rsbuild/rsbuild.config.mjs` file that contains the final Rsbuild config after the framework finishes processing your settings.

The structure of the file is as follows:

```js title="rsbuild.config.mjs"
export default {
  dev: {
    // some configs...
  },
  source: {
    // some configs...
  },
  // other configs...
};
```

For a complete introduction to Rsbuild config, please see the [Configure Rsbuild](/guide/configuration/rsbuild.md) chapter.

## Rspack config file

Rsbuild also creates a `dist/.rsbuild/rspack.config.web.mjs` file with the final Rspack config that Rsbuild passes to Rspack.

The structure of the file is as follows:

```js title="rspack.config.web.mjs"
export default {
  resolve: {
    // some resolve configs...
  },
  module: {
    // some Rspack loaders...
  },
  plugins: [
    // some Rspack plugins...
  ],
  // other configs...
};
```

For a complete introduction to Rspack configs, please see [Rspack official documentation](https://rspack.rs/config/).

---

# Source: https://rsbuild.dev/config/source/decorators.md

# source.decorators

* **Type:**

```ts
type Decorators = {
  version?: 'legacy' | '2022-03';
};
```

Used to configure the decorators syntax.

## decorators.version

* **Type:** `'legacy' | '2022-03'`
* **Default:** `'2022-03'`

Specify the decorator syntax version to be used.

If you want to know the differences between different decorators versions, you can refer to: [How does this proposal compare to other versions of decorators?](https://github.com/tc39/proposal-decorators?tab=readme-ov-file#how-does-this-proposal-compare-to-other-versions-of-decorators)

### 2022-03

`2022-03` corresponds to the Stage 3 decorator proposal, equivalent to the decorator syntax supported by TypeScript 5.0 by default.

```ts title="rsbuild.config.ts"
export default {
  source: {
    decorators: {
      version: '2022-03',
    },
  },
};
```

Reference documentation:

* [JavaScript meta programming with the 2022-03 decorators API](https://2ality.com/2022/10/javascript-decorators.html)
* [TypeScript 5.0 Decorators](https://typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html#decorators)

### legacy

Equivalent to TypeScript's `experimentalDecorators: true`.

```ts title="rsbuild.config.ts"
export default {
  source: {
    decorators: {
      version: 'legacy',
    },
  },
};
```

Reference documentation:

* [A Complete Guide to TypeScript Decorators](https://mirone.me/a-complete-guide-to-typescript-decorator/)
* [TypeScript Decorators](https://typescriptlang.org/docs/handbook/decorators.html)

---

# Source: https://rsbuild.dev/config/resolve/dedupe.md

# resolve.dedupe

* **Type:** `string[]`
* **Default:** `undefined`
* **Version:** `>= 1.1.7`

Force Rsbuild to resolve the specified packages from project root, which is useful for deduplicating packages and reducing the bundle size.

## Example

For example, assume your project is based on React 19, and you are using the `foo` package that depends on React 17, then your project will have two different versions of React:

```
app/
├── src/
└── node_modules/
    ├── foo/
    │   └── node_modules/
    │       ├── react (v17)
    │       └── react-dom (v17)
    ├── react (v19)
    └── react-dom (v19)
```

In this case, you can use the `resolve.dedupe` config to remove the duplicate React packages, and resolve all `react` and `react-dom` packages to `/node_modules/react` and `/node_modules/react-dom`:

```ts title="rsbuild.config.ts"
export default defineConfig({
  resolve: {
    dedupe: ['react', 'react-dom'],
  },
});
```

Note that using `resolve.dedupe` to unify different major versions of a package may cause some packages to fail because they may depend on specific versions of APIs or features.

For example, if `foo` depends on a React 17-specific API or feature, then unifying React 17 and React 19 with React 19 using `resolve.dedupe` may cause `foo` to fail.

## How it works

`resolve.dedupe` is implemented based on [resolve.alias](/config/resolve/alias.md), it will get the path of the specified package through `require.resolve` in the project root directory and set it to the alias.

In the above example, `resolve.dedupe` will be converted to the following alias config:

```ts
const alias = {
  react: '/app/node_modules/react',
  'react-dom': '/app/node_modules/react-dom',
};
```

The alias generated by `resolve.dedupe` will be merged with the configured `resolve.alias` in the project, and the `resolve.alias` config will take precedence when the keys are the same.

---

# Source: https://rsbuild.dev/config/source/define.md

# source.define

* **Type:** `Record<string, unknown>`
* **Default:** `{}`

Replaces variables in your code with other values or expressions at compile time. This enables different behavior between development and production builds.

Each configuration key represents an identifier or multiple identifiers joined with `.`:

* String values are used as code fragments.
* Other types (including functions) are stringified.
* Object values define all keys the same way.
* Keys prefixed with `typeof` are only defined for typeof calls.

> For more usage, see [Using define](/guide/advanced/env-vars.md#using-define) and [Rspack - DefinePlugin](https://rspack.rs/plugins/webpack/define-plugin).

## Example

```ts title="rsbuild.config.ts"
export default {
  source: {
    define: {
      PRODUCTION: JSON.stringify(true),
      VERSION: JSON.stringify('5fa3b9'),
      BROWSER_SUPPORTS_HTML5: true,
      TWO: '1 + 1',
      'typeof window': JSON.stringify('object'),
      'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
      'import.meta.test': JSON.stringify('foo'),
    },
  },
};
```

Expressions are replaced with the corresponding code fragments:

```js
const foo = TWO;

// ⬇️ Turns into
const foo = 1 + 1;
```

---

# Source: https://rsbuild.dev/api/javascript-api/dev-server-api.md

# Dev server API

Rsbuild provides a set of dev server APIs that you can access through plugin hooks or JavaScript API.

## How to use

* If you are a plugin author, you can access the dev server instance through the [onBeforeStartDevServer](/plugins/dev/hooks.md#onbeforestartdevserver) hook.

```ts
const myPlugin = () => ({
  setup(api) {
    api.onBeforeStartDevServer(({ server }) => {
      console.log('the server is ', server);
    });
  },
});
```

* If you are using the JavaScript API of Rsbuild, you can create a dev server instance through the [rsbuild.createDevServer](/api/javascript-api/instance.md#rsbuildcreatedevserver) method.

```ts
const server = await rsbuild.createDevServer();

console.log('the server is ', server);
```

## Example

### Integrate with custom server

Here is an example of integrating [express](https://expressjs.com/) with Rsbuild dev server:

```ts
import { createRsbuild } from '@rsbuild/core';
import express from 'express';

async function startDevServer() {
  // Init Rsbuild
  const rsbuild = await createRsbuild({
    config: {
      server: {
        middlewareMode: true,
      },
    },
  });
  const app = express();

  // Create Rsbuild dev server instance
  const rsbuildServer = await rsbuild.createDevServer();

  // Apply Rsbuild's built-in middleware
  app.use(rsbuildServer.middlewares);

  const server = app.listen(rsbuildServer.port, async () => {
    // Notify Rsbuild that the custom server has started
    await rsbuildServer.afterListen();
  });

  // Activate WebSocket connection
  rsbuildServer.connectWebSocket({ server });
}
```

For detailed usage, see:

* [Example code](https://github.com/rstackjs/rstack-examples/blob/main/rsbuild/express/server.mjs).
* [rsbuild.createDevServer](/api/javascript-api/instance.md#rsbuildcreatedevserver)
* [server.middlewareMode](/config/server/middleware-mode.md)

## API

### Type definitions

```ts
type EnvironmentAPI = {
  [name: string]: {
    /**
     * Get stats info about current environment.
     */
    getStats: () => Promise<Stats>;
    /**
     * Load and execute stats bundle in server.
     *
     * @param entryName - relate to Rsbuild's `source.entry`
     * @returns the return value of entry module.
     */
    loadBundle: <T = unknown>(entryName: string) => Promise<T>;
    /**
     * Get the compiled HTML template.
     */
    getTransformedHtml: (entryName: string) => Promise<string>;
  };
};

type RsbuildDevServer = {
  /**
   * The `connect` app instance.
   * Can be used to attach custom middleware to the dev server.
   */
  middlewares: Connect.Server;
  /**
   * The Node.js HTTP server instance.
   * - Will be `Http2SecureServer` if `server.https` config is used.
   * - Will be `null` if `server.middlewareMode` is enabled.
   */
  httpServer:
    | import('node:http').Server
    | import('node:http2').Http2SecureServer
    | null;
  /**
   * Start listening on the Rsbuild dev server.
   * Do not call this method if you are using a custom server.
   */
  listen: () => Promise<{
    port: number;
    urls: string[];
    server: {
      close: () => Promise<void>;
    };
  }>;
  /**
   * Environment API of Rsbuild server.
   */
  environments: EnvironmentAPI;
  /**
   * The resolved port.
   * By default, Rsbuild server listens on port `3000` and automatically increments
   * the port number if the port is occupied.
   */
  port: number;
  /**
   * Notifies Rsbuild that the custom server has successfully started.
   * Rsbuild will trigger the `onAfterStartDevServer` hook at this stage.
   */
  afterListen: () => Promise<void>;
  /**
   * Activates the WebSocket connection.
   * This ensures that HMR works properly.
   */
  connectWebSocket: (options: {
    server: import('node:http').Server | import('node:http2').Http2SecureServer;
  }) => void;
  /**
   * Close the Rsbuild server.
   */
  close: () => Promise<void>;
  /**
   * Print the server URLs.
   */
  printUrls: () => void;
  /**
   * Open URL in the browser after starting the server.
   */
  open: () => Promise<void>;
  /**
   * Allows middleware to send some message to HMR client, and then the HMR
   * client will take different actions depending on the message type.
   * - `static-changed`: The page will reload.
   */
  sockWrite: SockWrite;
};

type CreateDevServerOptions = {
  /**
   * Whether to get port silently and not print any logs.
   * @default false
   */
  getPortSilently?: boolean;
  /**
   * Whether to trigger Rsbuild compilation
   * @default true
   */
  runCompile?: boolean;
};

function CreateDevServer(
  options?: CreateDevServerOptions,
): Promise<RsbuildDevServer>;
```

### afterListen

* **Type:** `() => Promise<void>`

Notifies Rsbuild that the custom server has successfully started. Rsbuild will trigger the [onAfterStartDevServer](/plugins/dev/hooks.md#onafterstartdevserver) hook at this stage.

For example:

```ts
import express from 'express';
import { createRsbuild } from '@rsbuild/core';

const rsbuild = await createRsbuild();
const rsbuildServer = await rsbuild.createDevServer();
const app = express();

const server = app.listen(rsbuildServer.port, async () => {
  await rsbuildServer.afterListen();
});
```

### close

* **Type:** `() => Promise<void>`

Calling the `close()` method to trigger the [onCloseDevServer](/plugins/dev/hooks.md#onclosedevserver) hook and perform necessary cleanup operations.

```ts
import { createRsbuild } from '@rsbuild/core';

const rsbuild = await createRsbuild();
const rsbuildServer = await rsbuild.createDevServer();

await rsbuildServer.close();
```

### connectWebSocket

* **Type:**

```ts
type ConnectWebSocket = (options: {
  server: import('node:http').Server | import('node:http2').Http2SecureServer;
}) => void;
```

Activates the WebSocket connection. This ensures that HMR works properly.

Rsbuild has a built-in WebSocket handler to support HMR:

1. When a user accesses a page through browser, a WebSocket connection request is automatically initiated to the server.
2. After the Rsbuild dev server detects the connection request, it instructs the built-in WebSocket handler to process it.
3. After the browser successfully establishes a connection with the Rsbuild WebSocket handler, real-time communication is possible.
4. The Rsbuild WebSocket handler notifies the browser after each recompilation is complete. The browser then sends a `hot-update.(js|json)` request to the dev server to load the new compiled module.

When you use a custom server, you may encounter HMR connection error problems. This is because the custom server does not forward WebSocket connection requests to Rsbuild's WebSocket handler.

At this time, you need to use the `connectWebSocket` method to enable Rsbuild to sense and process the WebSocket connection request from the browser.

```ts
import express from 'express';
import { createRsbuild } from '@rsbuild/core';

const rsbuild = await createRsbuild();
const rsbuildServer = await rsbuild.createDevServer();
const app = express();

const httpServer = app.listen(rsbuildServer.port);

rsbuildServer.connectWebSocket({ server: httpServer });
```

### environments

* **Type:** [EnvironmentAPI](/api/javascript-api/environment-api.md#environment-api)

Provides Rsbuild's [environment API](/api/javascript-api/environment-api.md#environment-api), which allows you to get the build outputs information for a specific environment in the server side.

```ts title="rsbuild.config.ts"
const rsbuildServer = await rsbuild.createDevServer();
const webStats = await rsbuildServer.environments.web.getStats();

console.log(webStats.toJson({ all: false }));
```

### sockWrite

* **Type:** `(type: 'static-changed') => void`

Sends some message to HMR client, and then the HMR client will take different actions depending on the message type.

For example, if you send a `'static-changed'` message, the page will reload.

```ts
const rsbuildServer = await rsbuild.createDevServer();
if (someCondition) {
  rsbuildServer.sockWrite('static-changed');
}
```

> Sending `content-changed` and `static-changed` have the same effect. Since `content-changed` has been deprecated, please use `static-changed` instead.

---

# Source: https://rsbuild.dev/config/output/dist-path.md

# output.distPath

* **Type:**

```ts
type DistPathConfig =
  | string
  | {
      root?: string;
      html?: string;
      favicon?: string;
      js?: string;
      jsAsync?: string;
      css?: string;
      cssAsync?: string;
      svg?: string;
      font?: string;
      wasm?: string;
      image?: string;
      media?: string;
      assets?: string;
    };
```

* **Default:**

```js
const defaultDistPath = {
  root: 'dist',
  html: './',
  favicon: './',
  js: output.target === 'node' ? '' : 'static/js',
  jsAsync: output.target === 'node' ? '' : 'static/js/async',
  css: 'static/css',
  cssAsync: 'static/css/async',
  svg: 'static/svg',
  font: 'static/font',
  wasm: 'static/wasm',
  image: 'static/image',
  media: 'static/media',
  assets: 'static/assets',
};
```

Configure the directory for output files. Rsbuild outputs files to the specified subdirectory according to file type.

* `string`: Set the root output directory to a specific path, equivalent to `distPath.root`.
* `object`: Set the output directory for each file type.

> See [Output files](/guide/basic/output-files.md) for more information.

## File types

`output.distPath` can be configured differently for different file types.

Each `output.distPath` option controls different file types:

* `root`: The root directory of all output files.
* `html`: The output directory of HTML files.
* `favicon`: The output directory of favicon files.
* `js`: The output directory of JavaScript files.
* `jsAsync`: The output directory of async JavaScript files, which by default are output to the `async` subdirectory of `distPath.js`.
* `css`: The output directory of CSS style files.
* `cssAsync`: The output directory of async CSS files, which by default are output to the `async` subdirectory of `distPath.css`.
* `svg`: The output directory of SVG images.
* `font`: The output directory of font files.
* `wasm`: The output directory of WebAssembly files.
* `image`: The output directory of non-SVG images.
* `media`: The output directory of media assets, such as videos.
* `assets`: The output directory of other static assets, such as the assets defined in [Extend Asset Types](/guide/basic/static-assets.md#extend-asset-types).

## Root directory

The `root` is the root directory of the build artifacts and can be specified as a relative or absolute path. If `root` is a relative path, it is appended to the project's root directory to form an absolute path.

Other directories can only be specified as relative paths and will be output relative to the `root` directory.

## Example

The JavaScript files will be output to the `distPath.root` + `distPath.js` directory, which is `dist/static/js`.

To output JavaScript files to the `build/resource/js` directory, add the following configuration:

```ts title="rsbuild.config.ts"
export default {
  output: {
    distPath: {
      root: 'build',
      js: 'resource/js',
    },
  },
};
```

The above configuration will generate the following directory structure:

```bash
build
├── resource
│   └── js
│       └── index.js
└── index.html
```

## Version history

| Version | Changes                                     |
| ------- | ------------------------------------------- |
| v1.4.13 | Added support for `distPath.favicon` option |
| v1.6.0  | Added support for string type               |

---

# Source: https://rsbuild.dev/config/performance/dns-prefetch.md

# performance.dnsPrefetch

* **Type:** `string[] | undefined`
* **Default:** `undefined`

Injects [`<link rel="dns-prefetch">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch) tags into the HTML file.

## When to use

When a browser requests a resource from a (third party) server, that cross-origin's domain name must be resolved to an IP address before the browser can issue the request. This process is known as DNS resolution. While DNS caching can help to reduce this latency, DNS resolution can add significant latency to requests.

Configuring `dns-prefetch` can resolve the domain before requesting resources, reducing request latency and improving loading performance.

For more information, see [Using dns-prefetch](https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch).

## Example

```ts title="rsbuild.config.ts"
export default {
  performance: {
    dnsPrefetch: ['https://example.com'],
  },
};
```

The generated HTML tag in HTML is:

```html
<link rel="dns-prefetch" href="https://example.com" />
```

## Notes

In general, a website should not configure more than 10 DNS prefetches.

Using too many DNS prefetches can lead to performance issues because browsers have limits on the number of DNS requests they can maintain. Excessive DNS prefetching, or prefetching for domains that are not ultimately used can cause resource contention and may reduce browser efficiency.

For more details, refer to [What Is a DNS Prefetch?](https://www.splunk.com/en_us/blog/learn/dns-prefetch.html).

---

# Source: https://rsbuild.dev/config/output/emit-assets.md

# output.emitAssets

* **Type:** `boolean`
* **Default:** `true`

Controls whether to emit static assets such as images, fonts, audio, video, etc.

In scenarios such as SSR, you may not need to emit duplicate static assets. You can set `emitAssets` to `false` to avoid emitting assets.

## Example

The following example will emit static assets when building web bundles, and avoid emitting when building node bundles.

```ts title="rsbuild.config.ts"
export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
        emitAssets: false,
      },
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/output/emit-css.md

# output.emitCss

* **Type:** `boolean`
* **Default:** `true` when [output.target](/config/output/target.md) is `web`, otherwise `false`

Controls whether CSS is emitted to output bundles.

If `false`, the CSS will not be extracted to separate files or injected into the JavaScript bundles via [output.injectStyles](/config/output/inject-styles.md).

:::tip

When `output.emitCss` is `false`, the class name information of CSS Modules will still be injected into the JS bundles, which helps to ensure the correctness of CSS Modules class names in SSR.

:::

## Example

When building Node.js bundles, set `output.emitCss` to `true` to output CSS files:

```ts title="rsbuild.config.ts"
export default {
  output: {
    target: 'node',
    emitCss: true,
  },
};
```

---

# Source: https://rsbuild.dev/config/source/entry.md

# source.entry

* **Type:**

```ts
type Entry = Record<
  string,
  string | string[] | (Rspack.EntryDescription & { html?: boolean })
>;
```

* **Default:**

```ts
const defaultEntry = {
  // Rsbuild also supports other suffixes by default, such as ts, tsx, jsx, mts, cts, mjs, cjs
  index: './src/index.js',
};
```

Set the entry modules for building.

`source.entry` is an object where the key is the entry name and the value is the path of the entry module or a [description object](#description-object).

If the value is a path, it can be an absolute path or a relative path. Relative paths will be resolved based on [root](/config/root.md).

## HTML generation

Rsbuild will register [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin) for each entry in `source.entry` and generate the corresponding HTML files.

* **Example:**

```ts title="rsbuild.config.ts"
export default {
  source: {
    entry: {
      foo: './src/pages/foo/index.ts', // generate foo.html
      bar: './src/pages/bar/index.ts', // generate bar.html
    },
  },
};
```

The generated directory structure is as follows:

```
.
├── foo.html
├── bar.html
└── static
    ├── css
    │   ├── foo.css
    │   └── bar.css
    └── js
        ├── foo.js
        └── bar.js
```

If you do not need to generate HTML files:

* Set the [html](/config/source/entry.md#html-property) property to `false` in the entry description object to disable the HTML generation for a single entry.
* Set [tools.htmlPlugin](/config/tools/html-plugin.md) to `false` to disable the HTML generation for all entries.

## Description object

`source.entry` also supports Rspack's entry description object. For example:

```ts title="rsbuild.config.ts"
export default {
  source: {
    entry: {
      foo: {
        import: './src/foo.js',
        runtime: 'foo',
      },
      bar: {
        import: './src/bar.js',
        runtime: 'bar',
      },
    },
  },
};
```

### `html` property

Rsbuild has added an `html` property to the description object that controls whether an HTML file is generated.

For example, the `bar` entry does not generate an HTML file:

```ts title="rsbuild.config.ts"
export default {
  source: {
    entry: {
      foo: './src/foo.js',
      bar: {
        import: './src/bar.js',
        html: false,
      },
    },
  },
};
```

In the above example, `foo.html` will be generated, while `bar.html` will not be generated.

> For detailed usage of the description object, refer to [Rspack - Entry description object](https://rspack.rs/config/entry#entry-description-object).

## Set by environment

When you build for multiple [environments](/config/environments.md), you can set different entry for each environment:

For example, set different entry for `web` and `node` environments:

```ts title="rsbuild.config.ts"
export default {
  environments: {
    web: {
      source: {
        entry: {
          index: './src/index.client.js',
        },
      },
      output: {
        target: 'web',
      },
    },
    node: {
      source: {
        entry: {
          index: './src/index.server.js',
        },
      },
      output: {
        target: 'node',
      },
    },
  },
};
```

## Asynchronous setting

To set entry asynchronously, for example, use [glob](https://npmjs.com/package/glob) to scan the directory, you can export an async function in `rsbuild.config.ts`:

```ts title="rsbuild.config.ts"
import path from 'node:path';
import { glob } from 'glob';
import { defineConfig } from '@rsbuild/core';

export default defineConfig(async () => {
  const entryFiles = await glob('./src/**/main.{ts,tsx,js,jsx}');

  const entry = Object.fromEntries(
    entryFiles.map((file) => {
      const entryName = path.basename(path.dirname(file));
      return [entryName, `./${file}`];
    }),
  );

  return {
    source: {
      entry: entry,
    },
  };
});
```

---

# Source: https://rsbuild.dev/guide/advanced/env-vars.md

# Environment variables

Rsbuild supports injecting environment variables or expressions into your code during the build. This helps you distinguish between environments or replace constants.

This chapter explains how to use environment variables in Rsbuild.

## Default variables

By default, Rsbuild uses [source.define](#using-define) to inject environment variables into your code, replacing them with their values during the build:

`import.meta.env` contains these environment variables:

* [import.meta.env.MODE](#importmetaenvmode)
* [import.meta.env.DEV](#importmetaenvdev)
* [import.meta.env.PROD](#importmetaenvprod)
* [import.meta.env.BASE\_URL](#importmetaenvbase_url)
* [import.meta.env.ASSET\_PREFIX](#importmetaenvasset_prefix)

`process.env` contains these environment variables:

* [process.env.BASE\_URL](#processenvbase_url)
* [process.env.ASSET\_PREFIX](#processenvasset_prefix)
* [process.env.NODE\_ENV](#processenvnode_env)

### import.meta.env.MODE

* **Type:** `'production' | 'development' | 'none'`
* **Scope:** Available in source code, replaced at build time via [define](/guide/advanced/env-vars.md#using-define)

Use `import.meta.env.MODE` in client code to read the [mode](/config/mode.md) configuration value.

```ts
if (import.meta.env.MODE === 'development') {
  console.log('this is development mode');
}
```

In development mode, the above code will be compiled to:

```js
if (true) {
  console.log('this is development mode');
}
```

In production mode, the above code will be compiled to:

```js
if (false) {
  console.log('this is development mode');
}
```

During code minification, `if (false) { ... }` will be recognized as dead code and automatically removed.

### import.meta.env.DEV

* **Type:** `boolean`
* **Scope:** Available in source code, replaced at build time via [define](/guide/advanced/env-vars.md#using-define)

If [mode](/config/mode.md) is `'development'`, the value is `true`; otherwise, it is `false`.

```ts
if (import.meta.env.DEV) {
  console.log('this is development mode');
}
```

### import.meta.env.PROD

* **Type:** `boolean`
* **Scope:** Available in source code, replaced at build time via [define](/guide/advanced/env-vars.md#using-define)

If [mode](/config/mode.md) is `'production'`, the value is `true`; otherwise, it is `false`.

```ts
if (import.meta.env.PROD) {
  console.log('this is production mode');
}
```

### import.meta.env.BASE\_URL

* **Type:** `string`
* **Scope:** Available in source code, replaced at build time via [define](/guide/advanced/env-vars.md#using-define)

You can use `import.meta.env.BASE_URL` in client code to access the [base path](/guide/basic/server.md#base-path) of the server. This base path is determined by the [server.base](/config/server/base.md) configuration and is useful for referencing assets from the [public folder](/guide/basic/static-assets.md#public-folder) in your code.

For example, set the server's base path to `/foo` using the [server.base](/config/server/base.md) configuration:

```ts
export default {
  server: {
    base: '/foo',
  },
};
```

Then, the URL for the `favicon.ico` file in the public directory becomes `http://localhost:3000/foo/favicon.ico`. You can use `import.meta.env.BASE_URL` to construct the URL in JavaScript files:

```js title="index.js"
const image = new Image();
// Equivalent to "/foo/favicon.ico"
image.src = `${import.meta.env.BASE_URL}/favicon.ico`;
```

### import.meta.env.ASSET\_PREFIX

* **Type:** `string`
* **Scope:** Available in source code, replaced at build time via [define](/guide/advanced/env-vars.md#using-define)

You can use `import.meta.env.ASSET_PREFIX` in client code to access the URL prefix of static assets.

* In development, it is equivalent to the value set by [dev.assetPrefix](/config/dev/asset-prefix.md).
* In production, it is equivalent to the value set by [output.assetPrefix](/config/output/asset-prefix.md).
* Rsbuild will automatically remove the trailing slash from `assetPrefix` to make string concatenation easier.

For example, copy the `static/icon.png` image to the `dist` directory using the [output.copy](/config/output/copy.md) configuration:

```ts
export default {
  dev: {
    assetPrefix: '/',
  },
  output: {
    copy: [{ from: './static', to: 'static' }],
    assetPrefix: 'https://example.com',
  },
};
```

Then you can access the image URL in client code:

```jsx
const Image = <img src={`${import.meta.env.ASSET_PREFIX}/static/icon.png`} />;
```

In development mode, the above code will be compiled to:

```jsx
const Image = <img src={`/static/icon.png`} />;
```

In production mode, the above code will be compiled to:

```jsx
const Image = <img src={`https://example.com/static/icon.png`} />;
```

### process.env.BASE\_URL

* **Type:** `string`
* **Scope:** Available in source code, replaced at build time via [define](/guide/advanced/env-vars.md#using-define)

Rsbuild also supports using `process.env.BASE_URL`, which is an alias for [import.meta.env.BASE\_URL](#importmetaenvbase_url).

For example, in the HTML template, you can use `process.env.BASE_URL` to concatenate the URL:

```html title="index.html"
<!-- Equivalent to "/foo/favicon.ico" -->
<link rel="icon" href="<%= process.env.BASE_URL %>/favicon.ico" />
```

### process.env.ASSET\_PREFIX

* **Type:** `string`
* **Scope:** Available in source code, replaced at build time via [define](/guide/advanced/env-vars.md#using-define)

Rsbuild also supports using `process.env.ASSET_PREFIX`, which is an alias for [import.meta.env.ASSET\_PREFIX](#importmetaenvasset_prefix).

For example, in the HTML template, you can use `process.env.ASSET_PREFIX` to concatenate the URL:

```html title="index.html"
<!-- Equivalent to "https://example.com/static/icon.png" -->
<link rel="icon" href="<%= process.env.ASSET_PREFIX %>/static/icon.png" />
```

### process.env.NODE\_ENV

* **Type:** `string`
* **Scope:** Available in both Node.js process and source code

By default, Rsbuild sets the `process.env.NODE_ENV` environment variable to `'development'` in development mode and `'production'` in production mode.

You can use `process.env.NODE_ENV` directly in Node.js and in client code.

```ts
if (process.env.NODE_ENV === 'development') {
  console.log('this is a development log');
}
```

In development mode, the above code will be compiled to:

```js
if (true) {
  console.log('this is a development log');
}
```

In production mode, the above code will be compiled to:

```js
if (false) {
  console.log('this is a development log');
}
```

During code minification, `if (false) { ... }` is recognized as dead code and removed automatically.

#### Custom NODE\_ENV

`process.env.NODE_ENV` is injected by Rspack by default. To disable the injection or customize the value, use Rspack's [optimization.nodeEnv](https://rspack.rs/config/optimization#optimizationnodeenv) option:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: { optimization: { nodeEnv: false } },
  },
};
```

## `.env` file

When a `.env` file exists in the project root directory, Rsbuild CLI automatically uses [dotenv](https://npmjs.com/package/dotenv) to load these environment variables and add them to the current Node.js process. [Public variables](#public-variables) are then exposed in client code.

You can access these environment variables through `import.meta.env.[name]` or `process.env.[name]`.

### File types

Rsbuild supports reading the following types of env files:

| File Name                | Description                                                              |
| ------------------------ | ------------------------------------------------------------------------ |
| `.env`                   | Loaded by default in all scenarios.                                      |
| `.env.local`             | Local overrides for `.env`, should be added to `.gitignore`.             |
| `.env.development`       | Read when `process.env.NODE_ENV` is `'development'`.                     |
| `.env.production`        | Read when `process.env.NODE_ENV` is `'production'`.                      |
| `.env.development.local` | Local overrides for `.env.development`, should be added to `.gitignore`. |
| `.env.production.local`  | Local overrides for `.env.production`, should be added to `.gitignore`.  |

If multiple of the above files exist, they will all be loaded. Files listed lower in the table have higher priority.

### Env mode

Rsbuild also supports reading `.env.[mode]` and `.env.[mode].local` files. You can specify the env mode using the `--env-mode <mode>` flag.

For example, set the env mode as `test`:

```bash
npx rsbuild dev --env-mode test
```

Rsbuild will read these files in the following order and merge their contents. If the same environment variable is defined in multiple files, files loaded later will override those loaded earlier:

* .env
* .env.local
* .env.test
* .env.test.local

:::tip
The `--env-mode` option takes precedence over `process.env.NODE_ENV`.

We recommend using `--env-mode` to set the env mode instead of modifying `process.env.NODE_ENV`.

:::

#### Accessing in client code

By default, Rsbuild does not inject the env mode into client code. You can manually define a global identifier using [source.define](#using-define) to make it available in the client code:

```js title="rsbuild.config.js"
export default ({ envMode }) => ({
  source: {
    define: {
      ENV_MODE: JSON.stringify(envMode),
    },
  },
});
```

Then you can access it in client code:

```js title="src/index.js"
if (ENV_MODE === 'my-mode') {
  // ...
}
```

### Env directory

By default, the `.env` file is located in the root directory of the project. You can specify the env directory by using the `--env-dir <dir>` option in the CLI.

For example, to specify the env directory as `config`:

```bash
npx rsbuild dev --env-dir config
```

Rsbuild will then read `./config/.env` and other env files from that directory.

### Example

For example, create a `.env` file and add the following contents:

```shell title=".env"
FOO=hello
BAR=1
```

Then, in the `rsbuild.config.ts` file, you can access the environment variables using `import.meta.env.[name]` or `process.env.[name]`:

```ts title="rsbuild.config.ts"
console.log(import.meta.env.FOO); // 'hello'
console.log(import.meta.env.BAR); // '1'

console.log(process.env.FOO); // 'hello'
console.log(process.env.BAR); // '1'
```

Now, create a `.env.local` file and add the following contents:

```shell title=".env.local"
BAR=2
```

The value of `BAR` is overridden to `'2'`:

```ts title="rsbuild.config.ts"
console.log(import.meta.env.BAR); // '2'
console.log(process.env.BAR); // '2'
```

### Manually load env

If you are not using the Rsbuild CLI and instead use the [JavaScript API](/api/start/index.md), you need to manually call the [loadEnv](/api/javascript-api/core.md#loadenv) method to read environment variables and inject them via the [source.define](/config/source/define.md) config.

```ts
import { loadEnv, mergeRsbuildConfig } from '@rsbuild/core';

// By default, `publicVars` are variables prefixed with `PUBLIC_`
const { parsed, publicVars } = loadEnv();

const mergedConfig = mergeRsbuildConfig(
  {
    source: {
      define: publicVars,
    },
  },
  userConfig,
);
```

### Disable loading

You can disable loading `.env` files by using the `--no-env` flag in the CLI.

```bash
npx rsbuild dev --no-env
```

When using the `--no-env` flag, Rsbuild CLI will not read any `.env` files. You can then manage environment variables using other tools, such as [dotenvx](https://dotenvx.com/).

## Public variables

All environment variables starting with `PUBLIC_` can be accessed in client code. For example, if the following variables are defined:

```bash title=".env"
PUBLIC_NAME=jack
PASSWORD=123
```

In client code, you can access these environment variables through `import.meta.env.PUBLIC_*` or `process.env.PUBLIC_*`. Rsbuild will match the identifiers and replace them with their corresponding values.

```ts title="src/index.ts"
console.log(import.meta.env.PUBLIC_NAME); // -> 'jack'
console.log(import.meta.env.PASSWORD); // -> undefined

console.log(process.env.PUBLIC_NAME); // -> 'jack'
console.log(process.env.PASSWORD); // -> undefined
```

:::tip

* The content of public variables will be exposed to your client code, so please avoid including sensitive information in public variables.
* Public variables are replaced through [source.define](/config/source/define.md). Read ["Using define"](#using-define) to understand the principles and caveats of define.

:::

### Replacement scope

Public variables will replace identifiers in client code. The replacement scope includes:

* JavaScript files and files that can be converted to JavaScript code, such as `.js`, `.ts`, `.tsx`, etc.
* HTML template files, for example:

```xml title="template.html"
<div><%= process.env.PUBLIC_NAME %></div>
```

Note that public variables will not replace identifiers in the following files:

* CSS files, such as `.css`, `.scss`, `.less`, etc.

### Custom prefix

Rsbuild provides the [loadEnv](/api/javascript-api/core.md#loadenv) method, which can inject environment variables with any prefix into client code.

For example, when migrating a Create React App project to Rsbuild, you can read environment variables starting with `REACT_APP_` and inject them through the [source.define](/config/source/define.md) config as follows:

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

const { publicVars } = loadEnv({ prefixes: ['REACT_APP_'] });

export default defineConfig({
  source: {
    define: publicVars,
  },
});
```

## Using define

By using [source.define](/config/source/define.md), you can replace global identifiers with expressions or values at compile time.

`define` is similar to macro definition capabilities in other languages. It is often used to inject environment variables and other information into code during build time.

### Replace identifiers

The most basic use case for `define` is to replace global identifiers at compile time.

The value of the environment variable `NODE_ENV` affects the behavior of many vendor packages. Usually, we need to set it to `production`.

```js
export default {
  source: {
    define: {
      'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
    },
  },
};
```

Note that the value provided here must be a JSON string, e.g. `process.env.NODE_ENV` with a value of `"production"` should be passed in as `"\"production\""` to be processed correctly.

Similarly, `{ foo: "bar" }` should be converted to `"{\"foo\":\"bar\"}"`. If you pass the object directly, it means replacing the identifier `process.env.NODE_ENV.foo` with the identifier `bar`.

For more about `source.define`, refer to the [API References](/config/source/define.md).

:::tip
The `NODE_ENV` environment variable shown in the example above is already injected by Rsbuild, so you usually don't need to configure it manually.
:::

### Identifier matching

Note that `source.define` can only match complete global identifiers. You can think of it as performing text replacement.

If the identifier in the code doesn't exactly match the key defined in `define`, Rsbuild will not replace it.

```js
// Good
console.log(process.env.NODE_ENV); // 'production'

// Bad
console.log(process.env['NODE_ENV']); // process is not defined!

// Bad
console.log(process.env?.NODE_ENV); // process is not defined!

// Bad
const { NODE_ENV } = process.env;
console.log(NODE_ENV); // process is not defined!

// Bad
const env = process.env;
console.log(env.NODE_ENV); // process is not defined!
```

### process.env Replacement

When using `source.define`, avoid replacing the entire `process.env` object. For example, the following usage is not recommended:

```js
export default {
  source: {
    define: {
      'process.env': JSON.stringify(process.env),
    },
  },
};
```

If you use the above approach, it will cause the following problems:

1. Unused environment variables are injected unnecessarily, causing the dev server's environment variables to leak into the frontend code.
2. Every `process.env` reference will be replaced with the complete environment variable object, increasing bundle size and reducing performance.

Therefore, only inject the specific environment variables you need on `process.env`, and avoid replacing it entirely.

## Type declarations

### Public variables

When you access a public environment variable in a TypeScript file, TypeScript may report that the variable is missing a type definition. You'll need to add the corresponding type declaration.

For example, if you reference a `PUBLIC_FOO` variable, TypeScript will display the following error:

```
TS2304: Cannot find name 'PUBLIC_FOO'.
```

To fix this, you can create a `src/env.d.ts` file in your project and add the following content:

```ts title="src/env.d.ts"
declare const PUBLIC_FOO: string;
```

### import.meta.env

Rsbuild provides default TypeScript type definitions for `import.meta.env` through [Preset types](/guide/basic/typescript.md#preset-types).

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

If you have customized environment variables starting with `import.meta.env`, you can extend the `ImportMetaEnv` interface:

```ts title="src/env.d.ts"
interface ImportMetaEnv {
  // import.meta.env.PUBLIC_FOO
  readonly PUBLIC_FOO: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}
```

By default, Rsbuild's preset types allow you to access any property on `import.meta.env` without TypeScript type errors.

For stricter type safety, you can enable the `strictImportMetaEnv` option by extending the `RsbuildTypeOptions` interface. When this option is enabled, only properties predefined by Rsbuild or explicitly declared in your project can be accessed. Accessing any other property will cause a TypeScript type error.

You can add the following code to your `src/env.d.ts` file:

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

interface RsbuildTypeOptions {
  strictImportMetaEnv: true;
}
```

### process.env

If types for `process.env` are missing, install [@types/node](https://npmjs.com/package/@types/node):

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @types/node -D" />

Then extend the type of `process.env`:

```ts title="src/env.d.ts"
declare namespace NodeJS {
  interface ProcessEnv {
    // process.env.PUBLIC_FOO
    PUBLIC_FOO: string;
  }
}
```

## Tree shaking

`define` can also be used to mark dead code and assist Rspack with tree shaking optimization.

Build different artifacts for different languages by replacing `import.meta.env.LANGUAGE` with specific values. For example:

```ts title="rsbuild.config.ts"
export default {
  source: {
    define: {
      'import.meta.env.LANGUAGE': JSON.stringify(import.meta.env.LANGUAGE),
    },
  },
};
```

For internationalized code:

```js
const App = () => {
  if (import.meta.env.LANGUAGE === 'en') {
    return <EntryFoo />;
  } else if (import.meta.env.LANGUAGE === 'zh') {
    return <EntryBar />;
  }
};
```

Specifying the environment variable `LANGUAGE=zh` and running the build will eliminate dead code:

```js
const App = () => {
  if (false) {
  } else if (true) {
    return <EntryBar />;
  }
};
```

Unused components will not be bundled, and their dependencies will be removed accordingly, resulting in a smaller build output.

---

# Source: https://rsbuild.dev/api/javascript-api/environment-api.md

# Environment API

Here you can find all environment APIs.

> See [Multi-environment builds](/guide/advanced/environments.md) for more details.

## Environment context

Environment context is a read-only object that provides context information about the current environment.

* **Type:**

```ts
type EnvironmentContext = {
  name: string;
  browserslist: string[];
  config: NormalizedEnvironmentConfig;
  distPath: string;
  entry: RsbuildEntry;
  htmlPaths: Record<string, string>;
  tsconfigPath?: string;
  manifest?: Record<string, unknown> | ManifestData;
};
```

You can get the environment context in the following ways:

1. In Rsbuild's [Plugin hooks](/plugins/dev/hooks.md#plugin-hooks), you can get the environment context object through the `environment` or `environments` parameter.
2. In the [Environment API](#environment-api-1), it is available via `environments.context`.

### name

The unique name of the current environment, used to distinguish and locate the environment. Corresponds to the key in the [environments](/config/environments.md) configuration.

* **Type:** `string`
* **Example:**

```js
api.modifyRspackConfig((config, { environment }) => {
  if (environment.name === 'node') {
    // modify config for node environment
  }
  return config;
});
```

### browserslist

The browserslist configuration of the current environment. See [Browserslist](/guide/advanced/browserslist.md) for more details.

* **Type:** `string[]`
* **Example:**

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.browserslist);
  return config;
});
```

### config

The normalized Rsbuild config for the current environment.

* **Type:**

```ts
type NormalizedEnvironmentConfig = DeepReadonly<{
  dev: NormalizedDevConfig;
  html: NormalizedHtmlConfig;
  tools: NormalizedToolsConfig;
  source: NormalizedSourceConfig;
  server: NormalizedServerConfig;
  output: NormalizedOutputConfig;
  plugins?: RsbuildPlugins;
  security: NormalizedSecurityConfig;
  performance: NormalizedPerformanceConfig;
  moduleFederation?: ModuleFederationConfig;
}>;
```

* **Example:**

```js
api.modifyRspackConfig((config, { environment }) => {
  // Rspack config
  console.log(config);
  // Rsbuild config for current environment
  console.log(environment.config);
  return config;
});
```

### distPath

The absolute path of the output directory, corresponding to the [output.distPath.root](/config/output/dist-path.md) config of Rsbuild.

* **Type:** `string`

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.distPath);
  return config;
});
```

### entry

The entry object from the [source.entry](/config/source/entry.md) option.

* **Type:**

```ts
type RsbuildEntry = Record<string, string | string[] | EntryDescription>;
```

* **Example:**

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.entry);
  return config;
});
```

### htmlPaths

The path information for all HTML assets.

This value is an object, the key is the entry name and the value is the relative path of the HTML file in the dist directory.

* **Type:**

```ts
type htmlPaths = Record<string, string>;
```

* **Example:**

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.htmlPaths);
  return config;
});
```

### tsconfigPath

The absolute path of the tsconfig.json file, or `undefined` if the tsconfig.json file does not exist in current project.

* **Type:**

```ts
type TsconfigPath = string | undefined;
```

* **Example:**

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.tsconfigPath);
  return config;
});
```

### manifest

The manifest data. Only available when the [output.manifest](/config/output/manifest.md) config is enabled.

* **Type:** `Record<string, unknown> | ManifestData | undefined`
* **Example:**

```js
api.onAfterBuild(({ environments }) => {
  // Get the manifest data of web environment
  console.log(environments.web.manifest);
});

api.onAfterDevCompile(({ environments }) => {
  console.log(environments.web.manifest);
});

api.onAfterEnvironmentCompile(({ environment }) => {
  console.log(environment.manifest);
});
```

The manifest data is only available after the build has completed, you can access it in the following hooks:

* [onAfterBuild](/plugins/dev/hooks.md#onafterbuild)
* [onAfterEnvironmentCompile](/plugins/dev/hooks.md#onafterenvironmentcompile)
* [onCloseBuild](/plugins/dev/hooks.md#onclosebuild)
* [onCloseDevServer](/plugins/dev/hooks.md#onclosedevserver)
* [onAfterDevCompile](/plugins/dev/hooks.md#onafterdevcompile)
* [onExit](/plugins/dev/hooks.md#onexit)

### webSocketToken

WebSocket authentication token, used to authenticate WebSocket connections and prevent unauthorized access.

Only available in development mode, and is an empty string in production mode.

* **Type:** `string`
* **Version:** Added in v1.4.4

When you need to establish a WebSocket connection with the Rsbuild dev server in the browser, you need to use this token as a query parameter.

```js
const { webSocketToken } = environments.web.context;

const webSocketUrl = `ws://localhost:${port}${pathname}?token=${webSocketToken}`;
```

## Environment API

Environment API provides some APIs related to the multi-environment build.

You can use environment API via [rsbuild.createDevServer()](/api/javascript-api/instance.md#rsbuildcreatedevserver) or [dev.setupMiddlewares](/config/dev/setup-middlewares.md), which allows you to get the build outputs information for a specific environment in the server side.

```ts
type EnvironmentAPI = {
  [name: string]: {
    context: EnvironmentContext;
    getStats: () => Promise<Stats>;
    loadBundle: <T = unknown>(entryName: string) => Promise<T>;
    getTransformedHtml: (entryName: string) => Promise<string>;
  };
};
```

### context

You can get context information related to the current environment through the Environment API.

* **Type:** [EnvironmentContext](#environment-context)
* **Example:**

```ts
const webManifest = environments.web.context.manifest;

console.log(webManifest.entries);
```

### getStats

Get the build stats of current environment.

* **Type:**

```ts
type GetStats = () => Promise<Stats>;
```

* **Example:**

```ts
const webStats = await environments.web.getStats();

console.log(webStats.toJson({ all: false }));
```

### loadBundle

Loads and executes the compiled bundle on the server. This method returns the exported content of the specified entry module and is typically used to run bundles generated by Rsbuild in a server-side environment.

`loadBundle` resolves only after the build process has finished and the [onAfterDevCompile](/plugins/dev/hooks.md#onafterdevcompile) hook has completed. As a result, it cannot be called within the `onAfterDevCompile` hook.

* **Type:**

```ts
/**
 * @param entryName - Entry name, corresponding to a key in Rsbuild `source.entry`
 * @returns The return value of the entry module
 */
type LoadBundle = <T = unknown>(entryName: string) => Promise<T>;
```

* **Example:**

```ts
// Load the bundle of `main` entry
const result = await environments.node.loadBundle('main');
```

### getTransformedHtml

Get the HTML template content after compilation and transformation.

* **Type:**

```ts
type GetTransformedHtml = (entryName: string) => Promise<string>;
```

* **Example:**

```ts
// Get the HTML content of main entry
const html = await environments.web.getTransformedHtml('main');
```

This method returns the complete HTML string, including all resources and content injected through HTML plugins.

---

# Source: https://rsbuild.dev/config/environments.md

# Source: https://rsbuild.dev/guide/advanced/environments.md

# Multi-environment builds

Rsbuild can build outputs for multiple environments in a single run. Use [environments](/config/environments.md) to build them in parallel and set a separate Rsbuild config for each one.

## What is an environment

The `environment` refers to the runtime environment for build output. Common environments include browsers, Node.js, and Workers. Rsbuild allows you to define custom environment names and set build options for each environment individually.

A typical scenario is server-side rendering (SSR). You can define two environments, `web` and `node`, where the build targets ([output.target](/config/output/target.md)) are `web` and `node`. These are used for client-side rendering (CSR) and server-side rendering (SSR) scenarios.

You can also define different environments for the same build target, for example:

* Define `rsc` and `ssr` environments, both targeting `node`, used separately for React Server Components and SSR.
* Define `desktop` and `mobile` environments, both targeting `web`, used separately for desktop and mobile browsers.

Without the `environments` configuration, you would need to define multiple configurations for these scenarios and run multiple independent Rsbuild builds. With `environments`, you can build every output in a single Rsbuild run (Rsbuild achieves this using Rspack's [MultiCompiler](https://rspack.rs/api/javascript-api/compiler#multicompiler)).

In Rsbuild, each `environment` is associated with an Rsbuild configuration, an Rspack configuration, and a set of build outputs. Plugin authors can tailor the build for a specific environment—modifying configs, registering or removing plugins, adjusting Rspack rules, or inspecting asset information—based on the environment name.

## Environment configs

Rsbuild supports defining different Rsbuild configurations for each environment through [environments](/config/environments.md).

For example, if your project needs SSR support, you need to define different configurations for the client and server. You can define web and node environments.

```ts title="rsbuild.config.ts"
export default {
  environments: {
    // Configure the web environment for browsers
    web: {
      source: {
        entry: {
          index: './src/index.client.js',
        },
      },
      output: {
        // Use 'web' target for the browser outputs
        target: 'web',
      },
      resolve: {
        alias: {
          '@common': './src/client/common',
        },
      },
    },
    // Configure the node environment for SSR
    node: {
      source: {
        entry: {
          index: './src/index.server.js',
        },
      },
      output: {
        // Use 'node' target for the Node.js outputs
        target: 'node',
      },
      resolve: {
        alias: {
          '@common': './src/server/common',
        },
      },
    },
  },
};
```

### Config merging

If you configure `environments`, Rsbuild will merge the config in `environments` with the outer base config. When merging, the config in `environments` has higher priority.

In the example above, after merging the configs, Rsbuild generates two standalone environment configs for building web and node environments.

* **web environments config**: Generated by merging base config with `environments.web`
* **node environments config**: Generated by merging base config with `environments.node`

Then, Rsbuild will use these environment configurations to internally generate two Rspack configs and execute a single build using Rspack’s MultiCompiler.

### Debug config

When you execute the command `npx rsbuild inspect` in the project root directory, you will see the following output:

* `rsbuild.config.[name].mjs`: The Rsbuild config used for a certain environment during build.
* `rspack.config.[name].mjs`: The Rspack config corresponding to a certain environment when building.

```bash
➜ npx rsbuild inspect

config inspection completed, generated files:

  - Rsbuild config (web): /project/dist/.rsbuild/rsbuild.config.web.mjs
  - Rsbuild config (node): /project/dist/.rsbuild/rsbuild.config.node.mjs
  - Rspack config (web): /project/dist/.rsbuild/rspack.config.web.mjs
  - Rspack config (node): /project/dist/.rsbuild/rspack.config.node.mjs
```

## Default environment

When `environments` is not specified, Rsbuild creates an environment by default with the same name as the current target type (the value of [output.target](/config/output/target.md)).

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

The above config is equivalent to a simplification of the following config:

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

## Build a specific environment

By default, Rsbuild will build all environments in the Rsbuild configuration when you execute `rsbuild dev` or `rsbuild build`. You can build only the specified environments with `--environment <name>`.

```bash
# Build for all environments by default
rsbuild dev

# Build for the web environment
rsbuild dev --environment web

# Build for the web and ssr environments
rsbuild dev --environment web --environment node

# Building multiple environments can be shortened to:
rsbuild dev --environment web,node
```

## Add plugins for specified environment

Plugins configured through the [plugins](/config/plugins.md) field support running in all environments. If you want a plugin to run only in a specified environment, you can configure the plugin in the specified `environment`.

For example, enable the React plugin only in the web environment:

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

export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
      plugins: [pluginReact()],
    },
    node: {
      output: {
        target: 'node',
      },
    },
  },
};
```

If you are a plugin developer, you can view [Developing environment plugins](/plugins/dev/index.md#environment-plugin) for details.

## Configuring output directories

When building for multiple environments, it's recommended to configure different output directories for each environment to prevent dist files with the same name from overwriting each other.

You can use [output.distPath.root](/config/output/dist-path.md) to set independent output root directories for each environment.

For example, output the web bundles to the default `dist` directory, and the node bundles to `dist/server`:

```ts title="rsbuild.config.ts"
export default {
  environments: {
    web: {
      source: {
        entry: {
          index: './src/index.client.js',
        },
      },
    },
    node: {
      source: {
        entry: {
          index: './src/index.server.js',
        },
      },
      output: {
        target: 'node',
        distPath: {
          root: 'dist/server',
        },
      },
    },
  },
};
```

## Plugin API

### Update environment config

Rsbuild supports modifying or adding environment config through the [modifyRsbuildConfig](/plugins/dev/hooks.md#modifyrsbuildconfig) hook.

```ts
const myPlugin = () => ({
  setup(api) {
    api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) => {
      return mergeRsbuildConfig(config, {
        environments: {
          web1: {
            source: {
              entry: {
                index: './src/web1/index',
              },
            },
          },
        },
      });
    });
  },
});
```

### Configuring a specific environment

Rsbuild supports modifying the Rsbuild config of a specific environment through the [modifyEnvironmentConfig](/plugins/dev/hooks.md#modifyenvironmentconfig) hook.

```ts
const myPlugin = () => ({
  setup(api) {
    api.modifyEnvironmentConfig((config, { name }) => {
      if (name !== 'web') {
        return config;
      }
      config.html.title = 'My Default Title';
    });
  },
});
```

## Environment context

[Environment context](/api/javascript-api/environment-api.md#environment-context) is a read-only object that provides some context infos about the current environment. Rsbuild supports obtaining environment context information in plugin hooks.

For some plugin hooks related to the build environment (such as [modifyRspackConfig](/plugins/dev/hooks.md#modifyrspackconfig) and [modifyBundlerChain](/plugins/dev/hooks.md#modifybundlerchain)), Rsbuild supports obtaining the current environment context through the `environment` parameter.

```ts
const myPlugin = () => ({
  setup(api) {
    api.modifyRspackConfig((rspackConfig, { environment }) => {
      if (environment.name === 'node') {
        // do some thing
      }
    });
  },
});
```

For some global plugin hooks (such as [onAfterDevCompile](/plugins/dev/hooks.md#onafterdevcompile), [onBeforeStartDevServer](/plugins/dev/hooks.md#onbeforestartdevserver), etc.), Rsbuild supports obtaining the context of all environments through the `environments` parameter.

```ts
const myPlugin = () => ({
  setup(api) {
    api.onAfterDevCompile(({ environments }) => {
      environments.forEach((environment) => {
        console.log('environment', environment);
      });
    });
  },
});
```

## Environment API

Rsbuild server provides a series of APIs related to the build environment. Users can operate the build artifacts in a specific environment on the server side through the Rsbuild [environment API](/api/javascript-api/environment-api.md#environment-api).

You can use the environment API in [Rsbuild DevMiddleware](/config/dev/setup-middlewares.md) or [Custom Server](/api/javascript-api/instance.md#rsbuildcreatedevserver).

For example, you can quickly implement an SSR function through the Rsbuild environment API in development mode:

```ts
import express from 'express';
import { createRsbuild, loadConfig } from '@rsbuild/core';

const serverRender =
  ({ environments }) =>
  async (_req, res) => {
    const bundle = await environments.node.loadBundle('index');
    const rendered = bundle.render();
    const template = await environments.web.getTransformedHtml('index');
    const html = template.replace('<!--app-content-->', rendered);

    res.writeHead(200, {
      'Content-Type': 'text/html',
    });
    res.end(html);
  };

export async function startDevServer() {
  const { content } = await loadConfig();

  // Init Rsbuild
  const rsbuild = await createRsbuild({
    config: content,
  });

  const app = express();

  // Create Rsbuild dev server instance
  const rsbuildServer = await rsbuild.createDevServer();

  const serverRenderMiddleware = serverRender(rsbuildServer);

  app.get('/', async (req, res, next) => {
    try {
      await serverRenderMiddleware(req, res, next);
    } catch (err) {
      logger.error('SSR render error, downgrade to CSR...');
      logger.error(err);
      next();
    }
  });

  // Apply Rsbuild’s built-in middleware
  app.use(rsbuildServer.middlewares);

  // ...
}
```

For detailed usage, please refer to: [SSR + Express Example](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/ssr-express).

## Build order

By default, Rsbuild builds all environments in parallel.

To control the build order between different environments, you can set build dependencies through Rspack's [dependencies](https://rspack.rs/config/other-options#dependencies) configuration.

For example, if you need to build the `web` environment first, then build the `node` environment, you can add the following configuration:

```ts title="rsbuild.config.ts"
export default {
  environments: {
    web: {
      tools: {
        rspack: {
          name: 'foo',
        },
      },
    },
    node: {
      tools: {
        rspack: {
          dependencies: ['foo'],
        },
      },
    },
  },
};
```

We can use a simple plugin to test the build order of multiple environments:

```ts
const testPlugin: RsbuildPlugin = {
  name: 'test-plugin',
  setup(api) {
    api.onBeforeEnvironmentCompile(({ environment }) => {
      console.log('build start:', environment.name);
    });

    api.onAfterEnvironmentCompile(({ stats, environment }) => {
      console.log('build done:', environment.name);
      console.log('stats', stats);
    });
  },
};

// The plugin will output:
// - build start: web
// - build done: web
// - stats: { ... }
// - build start: node
// - build done: node
// - stats: { ... }
```

---

# Source: https://rsbuild.dev/guide/faq/exceptions.md

# Exceptions FAQ

### Seeing ESNext code in the compiled files?

By default, Rsbuild does not compile JavaScript files in `node_modules`. If an npm package includes ESNext syntax, that code is bundled as is.

To compile these files, use the [source.include](/config/source/include.md) configuration to specify additional directories or modules.

***

### Build error `Error: [object Object] is not a PostCSS plugin`?

Rsbuild uses PostCSS v8. If you encounter this error during compilation, it's usually because a package is using an incompatible PostCSS version. For example, the `postcss` peer dependency version in `cssnano` may not match the expected version.

To find unmet peer dependencies, run `npm ls postcss`. Then fix the issue by specifying the correct PostCSS version in your package.json.

```
npm ls postcss

 ├─┬ css-loader@6.3.0
 │ └── UNMET PEER DEPENDENCY postcss@8.3.9
 ├─┬ css-minimizer-webpack-plugin@3.0.0
 │ └── UNMET PEER DEPENDENCY postcss@8.3.9
```

***

### Build error `You may need additional loader`?

If you see this error during compilation, it means some files cannot be compiled correctly.

```bash
Module parse failed: Unexpected token
File was processed with these loaders:
 * some-loader/index.js

You may need an additional loader to handle the result of these loaders.
```

Check whether you're importing unsupported file formats, and configure the appropriate Rspack loader to handle them.

***

### Compilation error `export 'foo' (imported as 'foo') was not found in './utils'`?

This error means your code is importing a symbol that doesn't exist.

For example, in the following code, `index.ts` is importing the `foo` variable from `utils.ts`, but `utils.ts` only exports the `bar` variable.

```ts
// utils.ts
export const bar = 'bar';

// index.ts
import { foo } from './utils';
```

In this case, Rsbuild will throw the following error:

```bash
Compile Error:
File: ./src/index.ts
export 'foo' (imported as 'foo') was not found in './utils' (possible exports: bar)
```

To fix this, check your import/export statements and correct any errors.

There are some common mistakes:

* Importing a non-existent variable:

```ts
// utils.ts
export const bar = 'bar';

// index.ts
import { foo } from './utils';
```

* Re-exporting a type without the `type` modifier, which prevents transpilers like SWC or Babel from recognizing the type export.

```ts
// utils.ts
export type Foo = 'bar';

// index.ts
export { Foo } from './utils'; // Incorrect
export type { Foo } from './utils'; // Correct
```

In some cases, a third-party dependency you can't modify causes this error. If you're sure it doesn't affect your application, you can downgrade the log level from `error` to `warn`:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: {
      module: {
        parser: {
          javascript: {
            exportsPresence: 'warn',
          },
        },
      },
    },
  },
};
```

However, you should still contact the dependency maintainer to report the issue.

> You can refer to the Rspack documentation for more details on [module.parser.javascript.exportsPresence](https://rspack.rs/config/module#moduleparserjavascriptexportspresence).

***

### Tree shaking does not take effect?

Rsbuild enables Rspack's tree shaking by default during production builds. Whether tree shaking works depends on whether your code meets Rspack's tree shaking requirements.

If tree shaking isn't working as expected, check the `sideEffects` configuration in the related npm package. To learn more about `sideEffects` and tree shaking principles, see [Rspack - Tree shaking](https://rspack.rs/guide/optimization/tree-shaking).

***

### `JavaScript heap out of memory` when compiling?

This error indicates a memory overflow during the build process. This typically happens when the bundled content exceeds Node.js's default memory limit.

To fix out-of-memory issues, the easiest solution is to increase the memory limit using Node.js's `--max-old-space-size` option. Set this by adding [NODE\_OPTIONS](https://nodejs.org/api/cli.html#node_optionsoptions) before your CLI command.

For example, add parameters before the `rsbuild build` command:

```json title="package.json"
{
  "scripts": {
    "build": "rsbuild build" // [!code --]
    "build": "NODE_OPTIONS=--max_old_space_size=16384 rsbuild build" // [!code ++]
  }
}
```

For other commands like `rsbuild dev`, add the parameters before that command instead.

The value of the `max_old_space_size` parameter represents the upper limit of the memory size (MB). Generally, it can be set to `16384` (16GB).

The following parameters are explained in more detail in the official Node.js documentation:

* [NODE\_OPTIONS](https://nodejs.org/api/cli.html#node_optionsoptions)
* [--max-old-space-size](https://nodejs.org/api/cli.html#--max-old-space-sizesize-in-megabytes)

Besides increasing the memory limit, you can also improve efficiency by enabling optimization strategies. See [Improve Build Performance](/guide/optimization/build-performance.md) for details.

If these methods don't solve your problem, unusual logic in your project may be causing the overflow. Debug recent code changes to find the root cause. If you can't locate it, please contact us.

***

### `Can't resolve 'core-js/modules/abc.js'` when compiling?

If you see an error like this during compilation, it means [core-js](https://github.com/zloirock/core-js) cannot be resolved in your project.

```
Module not found: Can't resolve 'core-js/modules/es.error.cause.js'
```

Usually, you don't need to install `core-js` because Rsbuild includes `core-js` v3 by default.

If `core-js` cannot be found, the issue may be:

1. Your project overrides Rsbuild's built-in `alias` configuration, causing incorrect `core-js` path resolution. Check your `alias` configuration.
2. Some code depends on `core-js` v2. Find the corresponding code and upgrade to `core-js` v3.
3. An npm package in `node_modules` imports `core-js` but doesn't declare it in `dependencies`. Either add the `core-js` dependency to that package, or install `core-js` in your project root.

---

# Source: https://rsbuild.dev/config/source/exclude.md

# source.exclude

* **Type:** [Rspack.RuleSetCondition](https://rspack.rs/config/module-rules#condition)
* **Default:** `[]`

Exclude JavaScript or TypeScript files that do not need to be compiled by [SWC](/guide/configuration/swc.md).

## Usage

The usage of `source.exclude` is similar to [source.include](/config/source/include.md), supporting passing in strings or regular expressions to match the module path.

For example:

```ts title="rsbuild.config.ts"
import path from 'node:path';

export default {
  source: {
    exclude: [path.resolve(__dirname, 'src/module-a'), /src\/module-b/],
  },
};
```

> See [source.include](/config/source/include.md) to learn more usages.

## Priority

When both `source.include` and `source.exclude` are set, `source.exclude` has higher priority.

For example, in the following example, although `source.include` matches the entire `src` directory, JavaScript files in the `src/foo` directory will not be compiled by SWC:

```ts title="rsbuild.config.ts"
import path from 'node:path';

export default {
  source: {
    include: [path.resolve(__dirname, 'src')],
    exclude: [path.resolve(__dirname, 'src/foo')],
  },
};
```

## Exclude from bundling

`source.exclude` specifies JavaScript/TypeScript files that do not need to be compiled. These files will not be transformed by SWC, but referenced files will still be bundled into the outputs.

If you want certain files to be excluded and not bundled into the outputs, you can use Rspack's [IgnorePlugin](https://rspack.rs/plugins/webpack/ignore-plugin).

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: (config, { rspack }) => {
      config.plugins.push(
        new rspack.IgnorePlugin({
          resourceRegExp: /^\.\/locale$/,
          contextRegExp: /moment$/,
        }),
      );
      return config;
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/resolve/extensions.md

# resolve.extensions

* **Type:** `string[]`
* **Default:** `['.ts', '.tsx', '.mjs', '.js', '.jsx', '.json']`
* **Version:** `>= 1.1.9`

Automatically resolve file extensions when importing modules. This means you can import files without explicitly writing their extensions.

For example, if importing `'./index'`, Rsbuild will try to resolve using the following order:

* `./index.ts`
* `./index.tsx`
* `./index.mjs`
* `./index.js`
* `./index.jsx`
* `./index.json`

:::tip
It is not recommended to omit `.vue` or other custom import extension names using `resolve.extensions`, as this may interfere IDE and type support.
:::

## Example

The value of `resolve.extensions` overrides the default value of Rsbuild:

```ts title="rsbuild.config.ts"
export default {
  resolve: {
    extensions: ['.ts', '.tsx', '.js'],
  },
};
```

## Rspack config

`resolve.extensions` is provided by Rspack, see [Rspack - resolve.extensions](https://rspack.rs/config/resolve#resolveextensions).

You can also configure it using [tools.rspack](/config/tools/rspack.md):

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: {
      resolve: {
        extensions: ['.ts', '.tsx', '.js'],
      },
    },
  },
};
```

The difference between them is how the configuration is merged.

`tools.rspack` merges the configuration arrays based on [webpack-merge](https://github.com/survivejs/webpack-merge), which means `tools.rspack.resolve.extensions` will merge with the default value of Rsbuild, rather than overriding it.

---

# Source: https://rsbuild.dev/config/output/externals.md

# output.externals

* **Type:**

```ts
type Externals =
  | string
  | object
  | function
  | RegExp
  | Array<string | object | function | RegExp>;
```

* **Default:** `undefined`

At build time, prevent some `import` dependencies from being packed into bundles in your code, and instead fetch them externally at runtime.

> For more information, please see: [Rspack Externals](https://rspack.rs/config/externals).

## Examples

### Basic usage

Exclude the `react-dom` dependency from the output bundle. To get this module at runtime, the value of `react-dom` will globally retrieve the `ReactDOM` variable.

```ts title="rsbuild.config.ts"
export default {
  output: {
    externals: {
      'react-dom': 'ReactDOM',
    },
  },
};
```

### Array format

Use an array to define multiple external configurations:

```ts title="rsbuild.config.ts"
export default {
  output: {
    externals: [
      {
        react: 'React',
        'react-dom': 'ReactDOM',
      },
      'lodash',
    ],
  },
};
```

### Using with CDN

A common use case is to load libraries from CDN and exclude them from your bundle, then use [html.tags](/config/html/tags.md) to include them in your HTML.

```ts title="rsbuild.config.ts"
export default {
  output: {
    externals: {
      axios: 'axios',
    },
  },
  html: {
    tags: [
      {
        tag: 'script',
        append: false,
        attrs: {
          defer: true,
          crossorigin: true,
          src: 'https://unpkg.com/axios@1/dist/axios.min.js',
        },
      },
    ],
  },
};
```

Then you can use the external libraries in your source code:

```js title="src/api.js"
const response = await window.axios.get('/api/users');
```

### RegExp patterns

Use regular expressions to match multiple modules with a pattern:

```ts title="rsbuild.config.ts"
export default {
  output: {
    externals: [
      // Externalize all @babel packages
      /^@babel\/.+$/,
      // Externalize all lodash sub-modules
      /^lodash\/.+$/,
    ],
  },
};
```

:::tip
If [output.target](/config/output/target.md) is `web-worker`, externals will not take effect. This is because the Web Worker environment cannot access global variables.
:::

---

# Source: https://rsbuild.dev/config/html/favicon.md

# html.favicon

* **Type:** `string ｜ Function`
* **Default:** Automatically detects favicon files in the `public` directory

Set the favicon icon path for all pages, can be set as:

* a URL.
* an absolute file path.
* a relative path relative to the project [root](/config/root.md).

After config this option, the favicon will be automatically copied to the dist directory during the compilation, and the corresponding `link` tag will be added to the HTML.

:::tip
Rsbuild also provides [html.appIcon](/config/html/app-icon.md) to set the icon of the web application.
:::

## Default value

When `html.favicon` is not explicitly configured, Rsbuild will automatically look for favicon files in the [public directory](/config/server/public-dir.md).

It searches for the following files in order, and uses the first one it finds as the default favicon:

* `public/favicon.ico`
* `public/favicon.png`
* `public/favicon.svg`

## Example

Set as a relative path:

```ts title="rsbuild.config.ts"
export default {
  html: {
    favicon: './src/assets/icon.png',
  },
};
```

Set to an absolute path:

```js
import path from 'node:path';

export default {
  html: {
    favicon: path.resolve(__dirname, './src/assets/icon.png'),
  },
};
```

Set to a URL:

```js
import path from 'node:path';

export default {
  html: {
    favicon: 'https://foo.com/favicon.ico',
  },
};
```

After recompiling, the following tags are automatically generated in the HTML:

```html
<link rel="icon" href="/favicon.ico" />
```

## Output path

By default, favicons are output to the root path of the output directory, for example:

* `./src/assets/icon.png` will be output to `./dist/icon.png`.
* `./src/assets/favicon.ico` will be output to `./dist/favicon.ico`.

You can customize the output path for favicons using the [output.distPath.favicon](/config/output/dist-path.md) option:

```ts title="rsbuild.config.ts"
export default {
  output: {
    distPath: {
      // Output favicon to "./dist/static/favicon/" directory
      favicon: 'static/favicon',
    },
  },
};
```

## Function usage

* **Type:**

```ts
type FaviconFunction = ({ value: string; entryName: string }) => string | void;
```

When `html.favicon` is of type Function, the function receives an object as input, with the following properties:

* `value`: the default favicon configuration for Rsbuild.
* `entryName`: the name of the current entry.

In the context of MPA (Multi-Page Application), you can return different `favicon` based on the entry name, thus generating different tags for each page:

```ts title="rsbuild.config.ts"
export default {
  html: {
    favicon({ entryName }) {
      const icons = {
        foo: 'https://example.com/foo.ico',
        bar: 'https://example.com/bar.ico',
      };
      return icons[entryName] || 'https://example.com/default.ico';
    },
  },
};
```

## Version history

| Version | Changes                                                     |
| ------- | ----------------------------------------------------------- |
| v1.6.0  | Added automatic favicon detection from the public directory |

---

# Source: https://rsbuild.dev/guide/faq/features.md

# Source: https://rsbuild.dev/guide/start/features.md

# Features

Overview of the main features supported by Rsbuild.

## JavaScript

| Features             | Description                                                                                               | Links                                                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Rspack               | Use Rspack as the bundler by default                                                                      | <ul><li>[Configure Rspack](/guide/configuration/rspack.md)</li></ul>                                                                   |
| SWC compilation      | Transform and minify JavaScript and TypeScript code using SWC by default                                  | <ul><li>[Configure SWC](/guide/configuration/swc.md)</li></ul>                                                                         |
| TS compilation       | TypeScript files are compiled using SWC by default                                                        | <ul><li>[TypeScript compilation](/guide/basic/typescript.md#typescript-compilation)</li></ul>                                          |
| Code minification    | Code minification is enabled by default in production mode                                                | <ul><li>[output.minify](/config/output/minify.md)</li></ul>                                                                            |
| Polyfill injection   | Optional feature, inject core-js and other polyfills                                                      | <ul><li>[Browser compatibility](/guide/advanced/browser-compatibility.md)</li><li>[output.polyfill](/config/output/polyfill.md)</li></ul> |
| SourceMap generation | Source maps are generated in development mode by default                                                  | <ul><li>[output.sourceMap](/config/output/source-map.md)</li></ul>                                                                     |
| Alias                | Optional feature, set import alias                                                                        | <ul><li>[resolve.alias](/config/resolve/alias.md)</li></ul>                                                                            |
| Babel compilation    | Optional feature, use Babel to transform JavaScript and TypeScript code                                   | <ul><li>[Babel plugin](/plugins/list/plugin-babel.md)</li></ul>                                                                        |
| Node outputs         | Optional feature, build bundles that run in Node.js environment                                           | <ul><li>[Node target](/config/output/target.md#node-target)</li></ul>                                                                  |
| Web Workers          | Optional feature, use Web Workers                                                                         | <ul><li>[Web Workers](/guide/basic/web-workers.md)</li></ul>                                                                           |
| Browserslist         | Optional feature, use browserslist to specify which browsers should be supported in your web application. | <ul><li>[Browserslist](/guide/advanced/browserslist.md)</li></ul>                                                                      |
| Compatibility check  | Optional feature, scan build outputs for advanced syntax that isn't supported by the target browsers      | <ul><li>[@rsbuild/plugin-check-syntax](https://github.com/rstackjs/rsbuild-plugin-check-syntax)</li></ul>                           |
| Environment variable | Optional feature, inject environment variables or expressions into the code                               | <ul><li>[Environment variables](/guide/advanced/env-vars.md)</li></ul>                                                                 |
| Node polyfill        | Optional feature, inject polyfills for Node core modules on the browser side                              | <ul><li>[Node polyfill plugin](https://github.com/rstackjs/rsbuild-plugin-node-polyfill)</li></ul>                                  |
| Type check           | Optional feature, run type checker to check for type issues in code                                       | <ul><li>[Type checking](/guide/basic/typescript.md#type-checking)</li></ul>                                                            |
| Module Federation    | Optional feature, dynamically load modules and share dependencies                                         | <ul><li>[Module Federation](/guide/advanced/module-federation.md)</li></ul>                                                            |

## CSS

| Features                | Description                                                | Links                                                                                                           |
| ----------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Lightning CSS           | Use Lightning CSS to downgrade CSS syntax by default       | <ul><li>[CSS](/guide/styling/css-usage.md)</li></ul>                                                               |
| PostCSS transformation  | Optional feature, use PostCSS to transform CSS files       | <ul><li>[CSS](/guide/styling/css-usage.md)</li><li>[tools.postcss](/config/tools/postcss.md)</li></ul>                |
| Tailwind CSS            | Optional feature, use Tailwind CSS                         | <ul><li>[Tailwind CSS](/guide/styling/tailwindcss.md)</li></ul>                                                    |
| UnoCSS                  | Optional feature, use UnoCSS                               | <ul><li>[UnoCSS](/guide/styling/unocss.md)</li></ul>                                                               |
| Sass preprocessing      | Optional feature, compile Sass/Scss files                  | <ul><li>[CSS](/guide/styling/css-usage.md)</li><li>[Sass plugin](/plugins/list/plugin-sass.md)</li></ul>              |
| Less preprocessing      | Optional feature, compile Less files                       | <ul><li>[CSS](/guide/styling/css-usage.md)</li><li>[Less plugin](/plugins/list/plugin-less.md)</li></ul>              |
| Stylus preprocessing    | Optional feature, compile Stylus files                     | <ul><li>[CSS](/guide/styling/css-usage.md)</li><li>[Stylus plugin](/plugins/list/plugin-stylus.md)</li></ul>          |
| CSS Modules compilation | Support compiling `*.module.*` files by default            | <ul><li>[CSS Modules](/guide/styling/css-modules.md)</li><li>[tools.cssLoader](/config/tools/css-loader.md)</li></ul> |
| CSS Modules type        | Optional feature, generate type definition for CSS Modules | <ul><li>[Typed CSS Modules plugin](https://github.com/rstackjs/rsbuild-plugin-typed-css-modules)</li></ul>      |
| CSS minification        | CSS minification is enabled by default in production build | <ul><li>[CSS](/guide/styling/css-usage.md)</li></ul>                                                               |
| Inline CSS into JS      | Optional feature, inline CSS files to JavaScript files     | <ul><li>[CSS](/guide/styling/css-usage.md)</li><li>[output.injectStyles](/config/output/inject-styles.md)</li></ul>   |

## HTML

| Features            | Description                                  | Links                                                                                                                                     |
| ------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Set title           | Set HTML `<title>` tag                       | <ul><li>[Set page title](/guide/basic/html-template.md#set-page-title)</li><li>[html.title](/config/html/title.md)</li></ul>                    |
| Set meta            | Set HTML `<meta>` tag                        | <ul><li>[Set meta tags](/guide/basic/html-template.md#set-meta-tags)</li><li>[html.meta](/config/html/meta.md)</li></ul>                        |
| Set favicon         | Set favicon                                  | <ul><li>[Set page icon](/guide/basic/html-template.md#set-page-icon)</li><li>[html.favicon](/config/html/favicon.md)</li></ul>                  |
| Set app icon        | Set web application icons                    | <ul><li>[Set page icon](/guide/basic/html-template.md#set-page-icon)</li><li>[html.appIcon](/config/html/app-icon.md)</li></ul>                 |
| EJS template engine | Optional feature, use EJS template engine    | <ul><li>[HTML template - EJS](/guide/basic/html-template.md#ejs)</li></ul>                                                                   |
| Pug template engine | Optional feature, use pug template engine    | <ul><li>[Pug plugin](https://github.com/rstackjs/rsbuild-plugin-pug)</li></ul>                                                            |
| Inline JS files     | Optional feature, inline JS files into HTML  | <ul><li>[Inline static assets](/guide/optimization/inline-assets.md)</li><li>[output.inlineScripts](/config/output/inline-scripts.md)</li></ul> |
| Inline CSS files    | Optional feature, inline CSS files into HTML | <ul><li>[Inline static assets](/guide/optimization/inline-assets.md)</li><li>[output.inlineStyles](/config/output/inline-styles.md)</li></ul>   |

## Server

| Features          | Description                                                               | Links                                                           |
| ----------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Public dir        | Serves public assets from the `public` directory by default               | <ul><li>[server.publicDir](/config/server/public-dir.md)</li></ul> |
| SSR               | Optional feature, implement server-side rendering                         | <ul><li>[SSR](/guide/advanced/ssr.md)</li></ul>                    |
| Proxy             | Optional feature, proxy requests to the specified service                 | <ul><li>[server.proxy](/config/server/proxy.md)</li></ul>          |
| Open page         | Optional feature, automatically open page in browser when starting server | <ul><li>[server.open](/config/server/open.md)</li></ul>            |
| HTTPS             | Optional feature, enable HTTPS server                                     | <ul><li>[server.https](/config/server/https.md)</li></ul>          |
| Custom middleware | Optional feature, use custom middleware                                   | <ul><li>[Middleware](/guide/basic/server.md#middleware)</li></ul>  |

## UI framework

| Features      | Description                                                                | Links                                                                                              |
| ------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| React         | Optional feature, enable compilation of React JSX                          | <ul><li>[React plugin](/plugins/list/plugin-react.md)</li></ul>                                       |
| React Refresh | Optional feature, enable React Refresh                                     | <ul><li>[Hot module replacement](/guide/advanced/hmr.md)</li><li>[dev.hmr](/config/dev/hmr.md)</li></ul> |
| SVGR          | Optional feature, transform SVG to React component                         | <ul><li>[SVGR plugin](/plugins/list/plugin-svgr.md)</li></ul>                                         |
| Vue 3 SFC     | Optional feature, enable compilation of Vue 3 SFC (Single File Components) | <ul><li>[Vue plugin](/plugins/list/plugin-vue.md)</li></ul>                                           |
| Vue 3 JSX     | Optional feature, enable compilation of Vue 3 JSX syntax                   | <ul><li>[Vue JSX plugin](https://github.com/rstackjs/rsbuild-plugin-vue-jsx)</li></ul>             |
| Vue 2 SFC     | Optional feature, enable compilation of Vue 2 SFC (Single File Components) | <ul><li>[Vue 2 plugin](https://github.com/rstackjs/rsbuild-plugin-vue2)</li></ul>                  |
| Vue 2 JSX     | Optional feature, enable compilation of Vue 2 JSX syntax                   | <ul><li>[Vue 2 JSX plugin](https://github.com/rstackjs/rsbuild-plugin-vue2-jsx)</li></ul>          |
| Svelte        | Optional feature, enable compilation of Svelte component                   | <ul><li>[Svelte plugin](/plugins/list/plugin-svelte.md)</li></ul>                                     |
| Solid         | Optional feature, enable compilation of Solid JSX                          | <ul><li>[Solid plugin](/plugins/list/plugin-solid.md)</li></ul>                                       |

## Static assets

| Features               | Description                                                                  | Links                                                                                                                                    |
| ---------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Image assets           | Support importing image assets in code                                       | <ul><li>[Static assets](/guide/basic/static-assets.md)</li></ul>                                                                            |
| Font assets            | Support importing font assets in code                                        | <ul><li>[Static assets](/guide/basic/static-assets.md)</li></ul>                                                                            |
| Video assets           | Support importing video assets in code                                       | <ul><li>[Static assets](/guide/basic/static-assets.md)</li></ul>                                                                            |
| Wasm assets            | Support importing WebAssembly assets in code                                 | <ul><li>[Static assets](/guide/basic/static-assets.md)</li></ul>                                                                            |
| Node addons            | Support importing Node.js addons in code                                     | <ul><li>[Static assets](/guide/basic/static-assets.md)</li></ul>                                                                            |
| Inline static assets   | Small assets are inlined into JavaScript bundles by default                  | <ul><li>[Inline static assets](/guide/optimization/inline-assets.md)</li><li>[output.dataUriLimit](/config/output/data-uri-limit.md)</li></ul> |
| Clean up static assets | Automatically clean up static assets in the dist directory before each build | <ul><li>[output.cleanDistPath](/config/output/clean-dist-path.md)</li></ul>                                                                |
| Copy static assets     | Optional feature, copy static assets to the dist directory                   | <ul><li>[output.copy](/config/output/copy.md)</li></ul>                                                                                     |
| Generate manifest file | Optional feature, generate `manifest.json` file                              | <ul><li>[output.manifest](/config/output/manifest.md)</li></ul>                                                                             |

## Performance and debugging

| Features                   | Description                                                                                                                  | Links                                                                                                                                    |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Chunk splitting            | A variety of chunk splitting strategies are built into Rsbuild to automatically split the bundle into files of moderate size | <ul><li>[Code splitting](/guide/optimization/code-splitting.md)</li><li>[performance.chunkSplit](/config/performance/chunk-split.md)</li></ul> |
| Print file size            | After the production build, all bundle sizes are displayed by default                                                        | <ul><li>[performance.printFileSize](/config/performance/print-file-size.md)</li></ul>                                                       |
| Analyze build process      | Optional feature, use Rsdoctor to analyze build process                                                                      | <ul><li>[Use Rsdoctor](/guide/debug/rsdoctor.md)</li></ul>                                                                                  |
| Analyze bundle size        | Optional feature, analyze bundle size through Bundle Analyzer                                                                | <ul><li>[performance.bundleAnalyze](/config/performance/bundle-analyze.md)</li></ul>                                                        |
| Remove console             | Optional feature, remove `console.[methodName]` in code                                                                      | <ul><li>[performance.removeConsole](/config/performance/remove-console.md)</li></ul>                                                       |
| Optimize moment.js size    | Optional feature, remove the redundant locale files of moment.js                                                             | <ul><li>[performance.removeMomentLocale](/config/performance/remove-moment-locale.md)</li></ul>                                             |
| Dedupe packages            | Optional feature, remove duplicate npm packages                                                                              | <ul><li>[resolve.dedupe](/config/resolve/dedupe.md)</li></ul>                                                                               |
| Component on-demand import | Optional feature, selectively import code and styles from component libraries                                                | <ul><li>[source.transformImport](/config/source/transform-import.md)</li></ul>                                                              |
| Image compression          | Optional feature, compress used image resources                                                                              | <ul><li>[Image compress plugin](https://github.com/rstackjs/rsbuild-plugin-image-compress)</li></ul>                                     |
| Preload                    | Optional feature, fetches and caches a resource ahead of the current navigation                                              | <ul><li>[performance.preload](/config/performance/preload.md)</li></ul>                                                                     |
| Prefetch                   | Optional feature, fetches and caches a resource for an upcoming navigation                                                   | <ul><li>[performance.prefetch](/config/performance/prefetch.md)</li></ul>                                                                   |
| Preconnect                 | Optional feature, opens a connection to the resource's origin before it's needed                                             | <ul><li>[performance.preconnect](/config/performance/preconnect.md)</li></ul>                                                               |
| DNS prefetch               | Optional feature, preemptively perform DNS resolution for the target resource's origin                                       | <ul><li>[performance.dnsPrefetch](/config/performance/dns-prefetch.md)</li></ul>                                                            |

---

# Source: https://rsbuild.dev/config/output/filename-hash.md

# output.filenameHash

* **Type:** `boolean | string`
* **Default:** `true`

Configure whether to add a hash value to the filename after the production build.

### Disable hash

By default, output file names include a hash value:

```bash
dist/static/css/index.7879e19d.css
dist/static/js/index.18a568e5.js
```

You can set `output.filenameHash` to `false` to disable this behavior:

```ts title="rsbuild.config.ts"
export default {
  output: {
    filenameHash: false,
  },
};
```

After rebuilding, the output filenames become:

```bash
dist/static/css/index.css
dist/static/js/index.js
```

### Hash format

The default hash format is `contenthash:8`, which generates an 8-bit hash based on the content of the file.

You can set `output.filenameHash` to other formats supported by Rspack and customize the length.

```ts title="rsbuild.config.ts"
export default {
  output: {
    filenameHash: 'fullhash:16',
  },
};
```

The optional hash formats are:

* `fullhash`: The hash value of the entire compilation. If any file changes, the hash values of all output files in the entire project will change.
* `chunkhash`: The hash value of the chunk. The hash value will only change when the content of the chunk (and its included modules) changes.
* `contenthash`: The hash value of the file content. The hash value will only change when the content of the file itself changes.

### Notes

* [output.filename](/config/output/filename.md) has a higher priority than `output.filenameHash`.
* By default, when the target is not `web`, the hash will not be included in the filename of the output files, such as Node.js bundles.
* By default, the filename in development mode does not include a hash.

---

# Source: https://rsbuild.dev/config/output/filename.md

# output.filename

* **Type:**

```ts
type FilenameConfig = {
  html?: string;
  js?: string | Function;
  css?: string | Function;
  svg?: string | Function;
  font?: string | Function;
  wasm?: string;
  image?: string | Function;
  media?: string | Function;
  assets?: string | Function;
};
```

* **Default:**

```js
// Development mode
const devDefaultFilename = {
  html: '[name].html',
  js: '[name].js',
  css: '[name].css',
  svg: '[name].[contenthash:8].svg',
  font: '[name].[contenthash:8][ext]',
  wasm: '[contenthash:8].module.wasm',
  image: '[name].[contenthash:8][ext]',
  media: '[name].[contenthash:8][ext]',
  assets: '[name].[contenthash:8][ext]',
};

// Production mode
const prodDefaultFilename = {
  html: '[name].html',
  js: output.target === 'node' ? '[name].js' : '[name].[contenthash:8].js',
  css: '[name].[contenthash:8].css',
  svg: '[name].[contenthash:8].svg',
  font: '[name].[contenthash:8][ext]',
  wasm: '[contenthash:8].module.wasm',
  image: '[name].[contenthash:8][ext]',
  media: '[name].[contenthash:8][ext]',
  assets: '[name].[contenthash:8][ext]',
};
```

Set the filename of output files.

After a production build, Rsbuild adds a hash to the filename by default. To disable this behavior, set [output.filenameHash](/config/output/filename-hash.md) to `false`.

:::tip
Rsbuild generates the final file path based on `output.filename` and [output.distPath](/config/output/dist-path.md).

See [Output files](/guide/basic/output-files.md) for more information.

:::

## File types

`output.filename` can be set differently for different file types.

Each `output.filename` option controls different file types:

* `html`: The name of the HTML files.
* `js`: The name of the JavaScript files.
* `css`: The name of the CSS files.
* `svg`: The name of the SVG images.
* `font`: The name of the font files.
* `wasm`: The name of the Wasm files.
* `image`: The name of non-SVG images.
* `media`: The name of media assets, such as video.
* `assets`: The name of other static assets, such as the assets defined in [Extend Asset Types](/guide/basic/static-assets.md#extend-asset-types).

## Example

To set the name of the JavaScript files to `[name]_script.js`:

```ts title="rsbuild.config.ts"
export default {
  output: {
    filename: {
      js: '[name]_script.js',
    },
  },
};
```

Set different filenames for development and production builds:

```ts title="rsbuild.config.ts"
const isProd = process.env.NODE_ENV === 'production';

export default {
  output: {
    filename: {
      js: isProd ? '[name]_script.[contenthash:8].js' : '[name]_script.js',
    },
  },
};
```

:::tip Filename hash
Typically, Rsbuild only sets the filename hash in production mode (`process.env.NODE_ENV === 'production'`).

Setting the filename hash in development mode may cause HMR to fail (especially for CSS files). This happens because each time the file content changes, the hash value changes, preventing the bundler from reading the latest file content.
:::

## Filename placeholders

In `output.filename`, you can use filename placeholders to dynamically generate file names.

Common filename placeholders include:

* `[name]` - entry name, which is the key of [source.entry](/config/source/entry.md).
* `[contenthash]` - hash value generated based on file content.
* `[contenthash:<length>]` - hash value generated based on file content, with specified hash length.
* `[ext]` - file extension, including the dot.

> For more filename placeholders, refer to [Rspack - Filename placeholders](https://rspack.rs/config/filename-placeholders).

:::tip

* `filename.html` can only use certain filename placeholders like `[name]` and `[contenthash:<length>]`.
* `filename.js` and `filename.css` do not support `[ext]`.

:::

## Filename of async modules

When you import a module via dynamic import, the module will be bundled into a separate file using these default naming rules:

* In development mode, the filename will be generated based on the module path, such as `dist/static/js/async/src_add_ts.js`.
* In production mode, it will be a random numeric id, such as `dist/static/js/async/798.27e3083e.js`. This is to avoid leaking the source code path in production mode, and the number of characters is also less.

```js title="src/index.ts"
const { add } = await import('./add.ts');
```

To specify a fixed name for the async module, use the [magic comments](https://rspack.rs/api/runtime-api/module-methods#magic-comments) supported by Rspack. Use `webpackChunkName` to specify the module name:

```js title="src/index.ts"
const { add } = await import(
  /* webpackChunkName: "my-chunk-name" */ './add.ts'
);
```

After specifying the module name as shown above, the generated file will be `dist/static/js/async/my-chunk-name.js`.

## Using function

You can pass a function to dynamically set the filename based on the file information.

The function receives two parameters:

* `pathData`: An object containing file path information.
* `assetInfo`: An optional object containing additional assets information.

Dynamically set the filename for JavaScript files:

```ts title="rsbuild.config.ts"
const isProd = process.env.NODE_ENV === 'production';

export default {
  output: {
    filename: {
      js: (pathData, assetInfo) => {
        console.log(pathData); // You can check the contents of pathData here

        if (pathData.chunk?.name === 'index') {
          return isProd ? '[name].[contenthash:8].js' : '[name].js';
        }
        return '/some-path/[name].js';
      },
    },
  },
};
```

Dynamically set the filename for CSS files:

```ts title="rsbuild.config.ts"
const isProd = process.env.NODE_ENV === 'production';

export default {
  output: {
    filename: {
      css: (pathData, assetInfo) => {
        if (pathData.chunk?.name === 'index') {
          return isProd ? '[name].[contenthash:8].css' : '[name].css';
        }
        return '/some-path/[name].css';
      },
    },
  },
};
```

Dynamically set the filename for image files:

```ts title="rsbuild.config.ts"
export default {
  output: {
    filename: {
      image: (pathData) => {
        if (pathData.filename?.includes('foo')) {
          return '/foo/[name][ext]';
        }
        return '/bar/[name][ext]';
      },
    },
  },
};
```

:::tip
`output.filename.html` does not support using functions yet.
:::

## Query hash

To generate hash values on the URL query of assets, refer to:

```ts title="rsbuild.config.ts"
const isProd = process.env.NODE_ENV === 'production';

export default {
  output: {
    filename: {
      js: isProd ? '[name].js?v=[contenthash:8]' : `[name].js`,
      css: isProd ? '[name].css?v=[contenthash:8]' : `[name].css`,
    },
  },
};
```

In this case, the filenames of JS and CSS will not include a hash, but the URLs in the HTML will contain a hash query.

```html
<!DOCTYPE html>
<html>
  <head>
    <script defer src="/static/js/index.js?v=b8565050"></script>
    <link href="/static/css/index.css?v=02d157ca" rel="stylesheet" />
  </head>
</html>
```

---

# Source: https://rsbuild.dev/guide/faq/general.md

# General FAQ

### What is the relationship between Rsbuild and Rspack?

Rspack is the underlying bundler for Rsbuild. The goal of Rsbuild is to provide out-of-the-box build capabilities for Rspack users, so developers can start a web project with zero configuration.

The main differences between Rspack and Rsbuild are:

* Rspack projects need to be configured from scratch, while Rsbuild provides default best practice configurations and supports extending Rspack configurations.
* Rspack projects require integration with loaders and plugins from the community to support different scenarios, while Rsbuild provides official plugins and default support for common frontend frameworks and build capabilities.
* The capabilities of the Rspack CLI are comparable to the webpack CLI but more streamlined, while Rsbuild provides a more powerful CLI and a more complete dev server.

***

### Can Rsbuild be used to build libraries or UI components?

Rsbuild is designed for building web applications out of the box.

For libraries and UI components, we recommend using [Rslib](https://github.com/web-infra-dev/rslib), a library development tool based on Rsbuild that reuses Rsbuild's configuration and plugins.

---

# Source: https://rsbuild.dev/guide/start/glossary.md

# Glossary

## Bundler

Module bundlers like [Rspack](https://rspack.rs/) and [webpack](https://webpack.js.org/).

The main goal of bundlers is to combine JavaScript, CSS, and other files so the output can run in the browser, Node.js, or other environments. When bundlers process web applications, they build a dependency graph and combine each module into one or more bundles.

## CSR

CSR stands for "Client-Side Rendering". It means the page is rendered in the browser using JavaScript, and logic such as data fetching, templates, and routing runs on the client rather than the server.

In CSR, the server sends an empty HTML shell and JavaScript to the browser, and the browser fetches data from the server's API and renders dynamic content.

## Environment

The runtime environment for build outputs. See [Multi-environment builds](/guide/advanced/environments.md).

## Micro-frontend

Micro-frontend (MFE) is an architecture style similar to microservices. It is composed of multiple independently delivered frontend applications that form a cohesive whole. MFE decomposes frontend applications into smaller, simpler applications that can be developed, tested, and deployed independently while still appearing as a single product to users.

It primarily solves two problems:

* Maintaining large, complex applications becomes difficult over time.
* Cross-team collaboration becomes inefficient.

## Modern.js

[Modern.js](https://github.com/web-infra-dev/modern.js) is an open-source web engineering system from ByteDance that provides multiple solutions to help developers solve problems in different development scenarios.

## 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](/guide/advanced/module-federation.md) for more details.

## Rspack

[Rspack](https://rspack.rs/) is a high-performance JavaScript bundler written in Rust. It offers strong compatibility with the webpack ecosystem, so it can replace webpack seamlessly while delivering lightning-fast build speeds.

## Rspress

[Rspress](https://github.com/web-infra-dev/rspress) is a fast static site generator based on Rsbuild.

## SSR

SSR stands for "Server-Side Rendering". It means that the HTML of the web page is generated by the server and sent to the client, rather than sending only an empty HTML shell and relying on JavaScript to generate the page content.

See [Server-side rendering (SSR)](/guide/advanced/ssr.md) for more details.

## SWC

SWC (Speedy Web Compiler) is a transformer and minifier for JavaScript and TypeScript written in Rust.

See [Configure SWC](/guide/configuration/swc.md) for more details.

## More

See additional glossary terms in [Rspack - Glossary](https://rspack.rs/misc/glossary).

---

# Source: https://rsbuild.dev/config/server/headers.md

# server.headers

* **Type:** `Record<string, string | string[]>`
* **Default:** `undefined`

Adds headers to all responses sent from Rsbuild server. This configuration directly leverages Node.js [response.setHeader()](https://nodejs.org/api/http.html#responsesetheadername-value) method under the hood.

If the header already exists in the to-be-sent headers, its value will be overwritten.

:::tip

To set CORS headers like `Access-Control-Allow-Origin`, use [server.cors](/config/server/cors.md) option.

If both `server.headers` and `server.cors` are used, `server.headers` will override `server.cors`.

:::

## Usage

The `server.headers` option accepts an object where:

* Keys are header names (case-insensitive)
* Values are either a string or an array of strings

```ts title="rsbuild.config.ts"
export default {
  server: {
    headers: {
      'X-Custom-Foo': 'bar',
    },
  },
};
```

## Multiple values

Use an array of strings to send multiple headers with the same name.

```ts title="rsbuild.config.ts"
export default {
  server: {
    headers: {
      // Multiple Set-Cookie headers
      'Set-Cookie': ['type=ninja', 'language=javascript'],
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/server/history-api-fallback.md

# server.historyApiFallback

* **Type:** `boolean | HistoryApiFallbackOptions`
* **Default:** `false`

`historyApiFallback` is used to support routing based on the [history API](https://developer.mozilla.org/en-US/docs/Web/API/History_API). When a user visits a path that does not exist, it will automatically return a specified HTML file to avoid a 404 error.

When Rsbuild's default [page routing](/guide/basic/server.md#page-routing) behavior cannot meet your needs, for example, if you want to be able to access `main.html` when accessing `/`, you can achieve this through the `server.historyApiFallback` configuration.

:::tip
The `server.historyApiFallback` option has a higher priority than [server.htmlFallback](/config/server/html-fallback.md).
:::

## Example

When `server.historyApiFallback` is set to `true`, all HTML GET requests that do not match an actual resource will return `index.html`. This ensures that routing in single-page applications works correctly.

```ts title="rsbuild.config.ts"
export default {
  server: {
    historyApiFallback: true,
  },
};
```

Rsbuild will change the requested location to the [index](#index) you specify whenever there is a request which fulfills the following criteria:

* The request is a `GET` or `HEAD` request
* The request accepts `text/html`
* The requested path does not contain a `.` (dot), meaning it is not a direct file request
* The requested path does not match any pattern defined in [rewrites](#rewrites)

## Options

`server.historyApiFallback` also supports passing an object to customize its behavior.

### index

* **Type:** `string`
* **Default:** `'index.html'`

Specifies the default HTML file to return when the History API fallback is enabled.

For example, if you set `historyApiFallback.index` to `main.html`, the server will automatically serve `main.html` as the fallback page when users access any unmatched routes.

```ts title="rsbuild.config.ts"
export default {
  source: {
    entry: {
      main: './src/index.ts',
    },
  },
  server: {
    historyApiFallback: {
      index: '/main.html',
    },
  },
};
```

### rewrites

* **Type:**

```ts
type Rewrites = Array<{
  from: RegExp;
  to: string | ((context: HistoryApiFallbackContext) => string);
}>;
```

* **Default:** `[]`

`rewrites` lets you customize how request paths are mapped to HTML files when a History API fallback occurs.

These rules only apply when no static asset matches the request, meaning it has entered the fallback stage. Each rule is evaluated in order until a match is found and executed.

```ts title="rsbuild.config.ts"
export default {
  server: {
    historyApiFallback: {
      rewrites: [
        // Redirect the root path to the landing page
        { from: /^\/$/, to: '/views/landing.html' },
        // Return subpage.html for any path starting with /subpage
        { from: /^\/subpage/, to: '/views/subpage.html' },
        // Return a custom 404 page for all other paths
        { from: /./, to: '/views/404.html' },
      ],
    },
  },
};
```

:::tip
If you want to modify or forward requests outside of the fallback scenario, use the [server.proxy](/config/server/proxy.md) option to define proxy rules.
:::

### htmlAcceptHeaders

* **Type:** `string[]`
* **Default:** `['text/html', '*/*']`

Override the default `Accepts:` headers that are queried when matching HTML content requests.

```ts title="rsbuild.config.ts"
export default {
  server: {
    historyApiFallback: {
      htmlAcceptHeaders: ['text/html', 'application/xhtml+xml'],
    },
  },
};
```

### disableDotRule

* **Type:** `boolean`
* **Default:** `false`

By default, requests containing a dot (`.`) in the path are treated as direct file requests and are not redirected.

Setting `disableDotRule` to `true` will disable this behavior and allow such requests to be redirected as well.

```ts title="rsbuild.config.ts"
export default {
  server: {
    historyApiFallback: {
      disableDotRule: true,
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/dev/hmr.md

# Source: https://rsbuild.dev/guide/faq/hmr.md

# Source: https://rsbuild.dev/guide/advanced/hmr.md

# Hot module replacement

Hot Module Replacement (HMR) exchanges, adds, or removes modules while an application is running, without a full page reload. This significantly speeds up development in several ways:

* Preserves application state that would be lost during a full reload.
* Saves valuable development time by updating only what changed.
* Instantly updates the browser when modifying CSS/JS in source code, similar to changing styles directly in the browser's dev tools.

## HMR toggle

Rsbuild has built-in support for HMR, which is enabled by default in development mode.

If you don't need HMR, set [dev.hmr](/config/dev/hmr.md) to `false`. This disables HMR and React Refresh, and Rsbuild falls back to [dev.liveReload](/config/dev/live-reload.md).

```ts title="rsbuild.config.ts"
export default {
  dev: {
    hmr: false,
  },
};
```

To disable both HMR and live reload, set [dev.hmr](/config/dev/hmr.md) and [dev.liveReload](/config/dev/live-reload.md) to `false`. This prevents WebSocket requests to the dev server, and the page won't refresh automatically when files change.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    hmr: false,
    liveReload: false,
  },
};
```

## Specify HMR URL

By default, Rsbuild uses the host and port number of the current page to construct the WebSocket URL for HMR.

If the HMR connection fails, specify the WebSocket URL using the [dev.client](/config/dev/client.md) config.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    client: {
      host: 'localhost',
      protocol: 'ws',
    },
  },
};
```

## File watching

By default, Rsbuild doesn't watch files in the `.git/` and `node_modules/` directories. Changes to these files won't trigger a rebuild, which reduces memory usage and improves build performance.

To watch these directories, configure Rspack's [watchOptions.ignored](https://rspack.rs/config/watch#watchoptionsignored) to override the default behavior.

For example, to watch the `node_modules/` directory while ignoring `.git/`:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: {
      watchOptions: {
        ignored: /\.git/,
      },
    },
  },
};
```

## FAQ

Refer to [HMR FAQ](/guide/faq/hmr.md).

---

# Source: https://rsbuild.dev/plugins/dev/hooks.md

# Plugin hooks

This page outlines the plugin hooks available for Rsbuild plugins.

## Overview

### Common hooks

* [modifyRsbuildConfig](#modifyrsbuildconfig): Modify the configuration passed to Rsbuild.
* [modifyEnvironmentConfig](#modifyenvironmentconfig): Modify the Rsbuild configuration of a specific environment.
* [modifyRspackConfig](#modifyrspackconfig): Modify the configuration passed to Rspack.
* [modifyBundlerChain](#modifybundlerchain): Modify the configuration of Rspack through the chain API.
* [modifyHTMLTags](#modifyhtmltags): Modify the tags that are injected into the HTML.
* [modifyHTML](#modifyhtml): Modify the final HTML content.
* [onBeforeCreateCompiler](#onbeforecreatecompiler): Called before creating a compiler instance.
* [onAfterCreateCompiler](#onaftercreatecompiler): Called after creating a compiler instance and before building.
* [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile): Called before the compilation of a single environment.
* [onAfterEnvironmentCompile](#onafterenvironmentcompile): Called after the compilation of a single environment. You can get the build result information.
* [onExit](#onexit): Called when the process is about to exit.

### Dev hooks

Called when running the `rsbuild dev` command or the `rsbuild.startDevServer()` method:

* [onBeforeStartDevServer](#onbeforestartdevserver): Called before starting the dev server.
* [onAfterStartDevServer](#onafterstartdevserver): Called after starting the dev server.
* [onBeforeDevCompile](#onbeforedevcompile): Called before each build in development mode.
* [onAfterDevCompile](#onafterdevcompile): Called after each build in development mode.
* [onCloseDevServer](#onclosedevserver): Called when the dev server is closed.

### Build hooks

Called when running the `rsbuild build` command or the `rsbuild.build()` method:

* [onBeforeBuild](#onbeforebuild): Called before running the production build.
* [onAfterBuild](#onafterbuild): Called after running the production build. You can get the build result information.
* [onCloseBuild](#onclosebuild): Called when the build is closed.

### Preview hooks

Called when running the `rsbuild preview` command or the `rsbuild.preview()` method:

* [onBeforeStartProdServer](#onbeforestartprodserver): Called before starting the production server.
* [onAfterStartProdServer](#onafterstartprodserver): Called after starting the production server.

## Hooks order

### Dev hooks

When the `rsbuild dev` command or `rsbuild.startDevServer()` method is executed, Rsbuild will execute the following hooks in order:

* [modifyRsbuildConfig](#modifyrsbuildconfig)
* [modifyEnvironmentConfig](#modifyenvironmentconfig)
* [onBeforeStartDevServer](#onbeforestartdevserver)
* [modifyBundlerChain](#modifybundlerchain)
* [modifyRspackConfig](#modifyrspackconfig)
* [onBeforeCreateCompiler](#onbeforecreatecompiler)
* [onAfterCreateCompiler](#onaftercreatecompiler)
* [onBeforeDevCompile](#onbeforedevcompile)
* [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
* [onAfterStartDevServer](#onafterstartdevserver)
* [modifyHTMLTags](#modifyhtmltags)
* [modifyHTML](#modifyhtml)
* [onAfterEnvironmentCompile](#onafterenvironmentcompile)
* [onAfterDevCompile](#onafterdevcompile)
* [onCloseDevServer](#onclosedevserver)
* [onExit](#onexit)

When rebuilding, the following hooks will be triggered again:

* [onBeforeDevCompile](#onbeforedevcompile)
* [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
* [modifyHTMLTags](#modifyhtmltags)
* [modifyHTML](#modifyhtml)
* [onAfterEnvironmentCompile](#onafterenvironmentcompile)
* [onAfterDevCompile](#onafterdevcompile)

### Build hooks

When the `rsbuild build` command or `rsbuild.build()` method is executed, Rsbuild will execute the following hooks in order:

* [modifyRsbuildConfig](#modifyrsbuildconfig)
* [modifyEnvironmentConfig](#modifyenvironmentconfig)
* [modifyBundlerChain](#modifybundlerchain)
* [modifyRspackConfig](#modifyrspackconfig)
* [onBeforeCreateCompiler](#onbeforecreatecompiler)
* [onAfterCreateCompiler](#onaftercreatecompiler)
* [onBeforeBuild](#onbeforebuild)
* [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
* [modifyHTMLTags](#modifyhtmltags)
* [modifyHTML](#modifyhtml)
* [onAfterEnvironmentCompile](#onafterenvironmentcompile)
* [onAfterBuild](#onafterbuild)
* [onCloseBuild](#onclosebuild)
* [onExit](#onexit)

When rebuilding, the following hooks will be triggered again:

* [onBeforeBuild](#onbeforebuild)
* [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
* [modifyHTMLTags](#modifyhtmltags)
* [modifyHTML](#modifyhtml)
* [onAfterEnvironmentCompile](#onafterenvironmentcompile)
* [onAfterBuild](#onafterbuild)

### Preview hooks

When executing the `rsbuild preview` command or `rsbuild.preview()` method, Rsbuild will execute the following hooks in order:

* [modifyRsbuildConfig](#modifyrsbuildconfig)
* [modifyEnvironmentConfig](#modifyenvironmentconfig)
* [onBeforeStartProdServer](#onbeforestartprodserver)
* [onAfterStartProdServer](#onafterstartprodserver)
* [onExit](#onexit)

## Global hooks vs environment hooks

In Rsbuild, some plugin hooks are global. These hooks relate to Rsbuild's startup process or other shared logic and run across all environments. For example:

* `modifyRsbuildConfig` is used to modify the basic configuration of Rsbuild. The basic configuration will eventually be merged with the environment configuration;
* `onBeforeStartDevServer` and `onAfterStartDevServer` are related to the Rsbuild dev server startup process, all environments share Rsbuild's dev server, middleware, and WebSocket.

Correspondingly, there are some plugin hooks that are related to the current environment. These hooks are executed with a specific environment context and are triggered multiple times depending on the environment.

### Global hooks

* [modifyRsbuildConfig](#modifyrsbuildconfig)
* [onBeforeStartDevServer](#onbeforestartdevserver)
* [onBeforeCreateCompiler](#onbeforecreatecompiler)
* [onAfterCreateCompiler](#onaftercreatecompiler)
* [onAfterStartDevServer](#onafterstartdevserver)
* [onBeforeDevCompile](#onbeforedevcompile)
* [onAfterDevCompile](#onafterdevcompile)
* [onCloseDevServer](#onclosedevserver)
* [onBeforeBuild](#onbeforebuild)
* [onAfterBuild](#onafterbuild)
* [onCloseBuild](#onclosebuild)
* [onBeforeStartProdServer](#onbeforestartprodserver)
* [onAfterStartProdServer](#onafterstartprodserver)
* [onExit](#onexit)

### Environment hooks

* [modifyEnvironmentConfig](#modifyenvironmentconfig)
* [modifyBundlerChain](#modifybundlerchain)
* [modifyRspackConfig](#modifyrspackconfig)
* [modifyHTMLTags](#modifyhtmltags)
* [modifyHTML](#modifyhtml)
* [onBeforeEnvironmentCompile](#onbeforeenvironmentcompile)
* [onAfterEnvironmentCompile](#onafterenvironmentcompile)

## Callback order

### Default behavior

If multiple plugins register the same hook, the callback functions of the hook will execute in the order in which they were registered.

In the following example, the console will output `'1'` and `'2'` in sequence:

```ts
const plugin1 = () => ({
  setup(api) {
    api.modifyRsbuildConfig(() => console.log('1'));
  },
});

const plugin2 = () => ({
  setup(api) {
    api.modifyRsbuildConfig(() => console.log('2'));
  },
});

rsbuild.addPlugins([plugin1, plugin2]);
```

### `order` Field

When registering a hook, you can declare the order of hook through the `order` field.

```ts
type HookDescriptor<T extends (...args: any[]) => any> = {
  handler: T;
  order: 'pre' | 'post' | 'default';
};
```

In the following example, the console will sequentially output `'2'` and `'1'`, because `order` was set to `pre` when plugin2 called `modifyRsbuildConfig`.

```ts
const plugin1 = () => ({
  setup(api) {
    api.modifyRsbuildConfig(() => console.log('1'));
  },
});

const plugin2 = () => ({
  setup(api) {
    api.modifyRsbuildConfig({
      handler: () => console.log('2'),
      order: 'pre',
    });
  },
});

rsbuild.addPlugins([plugin1, plugin2]);
```

## Common hooks

### modifyRsbuildConfig

Modify the config passed to the Rsbuild, you can directly modify the config object, or return a new object to replace the previous object.

:::warning
`modifyRsbuildConfig` is a global hook. To add support for your plugin as an [environment-specific plugin](/guide/advanced/environments.md#add-plugins-for-specified-environment), you should use [modifyEnvironmentConfig](/plugins/dev/hooks.md#modifyenvironmentconfig) instead of `modifyRsbuildConfig`.
:::

* **Type:**

```ts
type ModifyRsbuildConfigUtils = {
  mergeRsbuildConfig: typeof mergeRsbuildConfig;
};

function ModifyRsbuildConfig(
  callback: (
    config: RsbuildConfig,
    utils: ModifyRsbuildConfigUtils,
  ) => MaybePromise<RsbuildConfig | void>,
): void;
```

* **Example:** Setting a default value for a specific config option:

```ts
const myPlugin = () => ({
  setup(api) {
    api.modifyRsbuildConfig((config) => {
      config.html ||= {};
      config.html.title = 'My Default Title';
    });
  },
});
```

* **Example:** Using `mergeRsbuildConfig` to merge config objects, and return the merged object.

```ts
import type { RsbuildConfig } from '@rsbuild/core';

const myPlugin = () => ({
  setup(api) {
    api.modifyRsbuildConfig((userConfig, { mergeRsbuildConfig }) => {
      const extraConfig: RsbuildConfig = {
        source: {
          // ...
        },
        output: {
          // ...
        },
      };

      // extraConfig will override fields in userConfig,
      // If you do not want to override the fields in userConfig,
      // you can adjust to `mergeRsbuildConfig(extraConfig, userConfig)`
      return mergeRsbuildConfig(userConfig, extraConfig);
    });
  },
});
```

:::tip
`modifyRsbuildConfig` cannot be used to register additional Rsbuild plugins. This is because at the time `modifyRsbuildConfig` is executed, Rsbuild has already initialized all plugins and started executing the callbacks of the hooks.

For details, please refer to [Plugin registration phase](/config/plugins.md#plugin-registration-phase).
:::

### modifyEnvironmentConfig

Modify the Rsbuild configuration of a specific environment.

In the callback function, the config object in the parameters has already been merged with the common Rsbuild configuration. You can directly modify this config object, or you can return a new object to replace it.

* **Type:**

```ts
type ArrayAtLeastOne<A, B> = [A, ...Array<A | B>] | [...Array<A | B>, A];

type ModifyEnvironmentConfigUtils = {
  /** Current environment name */
  name: string;
  mergeEnvironmentConfig: (
    ...configs: ArrayAtLeastOne<MergedEnvironmentConfig, EnvironmentConfig>
  ) => EnvironmentConfig;
};

function ModifyEnvironmentConfig(
  callback: (
    config: EnvironmentConfig,
    utils: ModifyEnvironmentConfigUtils,
  ) => MaybePromise<EnvironmentConfig | void>,
): void;
```

* **Example:** Set a default value for the Rsbuild config of a specified environment:

```ts
const myPlugin = () => ({
  setup(api) {
    api.modifyEnvironmentConfig((config, { name }) => {
      if (name !== 'web') {
        return config;
      }
      config.html.title = 'My Default Title';
    });
  },
});
```

* **Example:** Using `mergeEnvironmentConfig` to merge config objects, and return the merged object.

```ts
import type { EnvironmentConfig } from '@rsbuild/core';

const myPlugin = () => ({
  setup(api) {
    api.modifyEnvironmentConfig((userConfig, { mergeEnvironmentConfig }) => {
      const extraConfig: EnvironmentConfig = {
        source: {
          // ...
        },
        output: {
          // ...
        },
      };

      // extraConfig will override fields in userConfig,
      // If you do not want to override the fields in userConfig,
      // you can adjust to `mergeEnvironmentConfig(extraConfig, userConfig)`
      return mergeEnvironmentConfig(userConfig, extraConfig);
    });
  },
});
```

### modifyRspackConfig

To modify the Rspack config, you can directly modify the config object, or return a new object to replace the previous object.

:::tip
`modifyRspackConfig` is executed earlier than [tools.rspack](/config/tools/rspack.md). Therefore, the modifications made by `tools.rspack` cannot be obtained in `modifyRspackConfig`.
:::

* **Type:**

```ts
type ModifyRspackConfigUtils = {
  environment: EnvironmentContext;
  env: string;
  isDev: boolean;
  isProd: boolean;
  target: RsbuildTarget;
  isServer: boolean;
  isWebWorker: boolean;
  rspack: Rspack;
  HtmlPlugin: typeof import('html-rspack-plugin');
  // more...
};

function ModifyRspackConfig(
  callback: (
    config: Rspack.Configuration,
    utils: ModifyRspackConfigUtils,
  ) => Promise<RspackConfig | void> | Rspack.Configuration | void,
): void;
```

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.modifyRspackConfig((config, utils) => {
      if (utils.env === 'development') {
        config.devtool = 'eval-cheap-source-map';
      }
    });
  },
});
```

The second parameter `utils` of the callback function is an object, which contains some utility functions and properties, see [tools.rspack - Utils](/config/tools/rspack.md#utils) for more details.

### modifyBundlerChain

import RspackChain from '@en/shared/rspackChain.mdx';

<RspackChain />

`modifyBundlerChain` allows you to modify the Rspack configuration using the `rspack-chain` API, providing the same functionality as [tools.bundlerChain](/config/tools/bundler-chain.md).

* **Type:**

```ts
type ModifyBundlerChainUtils = {
  environment: EnvironmentContext;
  env: string;
  isDev: boolean;
  isProd: boolean;
  target: RsbuildTarget;
  isServer: boolean;
  isWebWorker: boolean;
  CHAIN_ID: ChainIdentifier;
  HtmlPlugin: typeof import('html-rspack-plugin');
  bundler: {
    // some Rspack built-in plugins
  };
};

function ModifyBundlerChain(
  callback: (
    chain: RspackChain,
    utils: ModifyBundlerChainUtils,
  ) => Promise<void> | void,
): void;
```

* **Example:**

```ts
import { BundleAnalyzerPlugin } from 'webpack-bundle-analyzer';

const myPlugin = () => ({
  setup(api) {
    api.modifyBundlerChain((chain, utils) => {
      if (utils.env === 'development') {
        chain.devtool('eval');
      }

      chain.plugin('bundle-analyze').use(BundleAnalyzerPlugin);
    });
  },
});
```

The second parameter `utils` of the callback function is an object, which contains some utility functions and properties, see [tools.bundlerChain - Utils](/config/tools/bundler-chain.md#utils) for more details.

### modifyHTML

Modify the final HTML content. The hook receives an HTML string and a context object, and you can return a new HTML string to replace the original one.

This hook is triggered after the `modifyHTMLTags` hook.

* **Type:**

```ts
type Context = {
  /**
   * The Compiler object of Rspack.
   */
  compiler: Rspack.Compiler;
  /**
   * The Compilation object of Rspack.
   */
  compilation: Rspack.Compilation;
  /**
   * The name of the HTML file, relative to the dist directory.
   * @example 'index.html'
   */
  filename: string;
  /**
   * The environment context for current build.
   */
  environment: EnvironmentContext;
};

function ModifyHTML(
  callback: (html: string, context: Context) => MaybePromise<string>,
): void;
```

* **Version:** Added in v1.3.15
* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.modifyHTML((html) => {
      return html.replace('foo', 'bar');
    });
  },
});
```

Modify HTML content based on `filename`:

```ts
const myPlugin = () => ({
  setup(api) {
    api.modifyHTML((html, { filename }) => {
      if (filename === 'foo.html') {
        return html.replace('foo', 'bar');
      }
      return html;
    });
  },
});
```

Instead of directly manipulating the HTML string, you can use [cheerio](https://github.com/cheeriojs/cheerio) or [htmlparser2](https://github.com/fb55/htmlparser2) to modify the HTML content more conveniently.

For example, `cheerio` provides a jQuery-like API for HTML manipulation:

```ts
import cheerio from 'cheerio';

const myPlugin = () => ({
  setup(api) {
    api.modifyHTML((html) => {
      const $ = cheerio.load(html);
      $('h2.title').text('Hello there!');
      $('h2').addClass('welcome');
      return $.html();
    });
  },
});
```

### modifyHTMLTags

Modify the tags that are injected into the HTML.

* **Type:**

```ts
type HtmlBasicTag = {
  // Tag name
  tag: string;
  // Attributes of the tag
  attrs?: Record<string, string | boolean | null | undefined>;
  // innerHTML of the tag
  children?: string;
  // additional metadata
  metadata?: Record<string, any>;
};

type HTMLTags = {
  // Tags group inserted into <head>
  headTags: HtmlBasicTag[];
  // Tags group inserted into <body>
  bodyTags: HtmlBasicTag[];
};

type Context = {
  /**
   * The Compiler object of Rspack.
   */
  compiler: Rspack.Compiler;
  /**
   * The Compilation object of Rspack.
   */
  compilation: Rspack.Compilation;
  /**
   * URL prefix of assets.
   * @example 'https://example.com/'
   */
  assetPrefix: string;
  /**
   * The name of the HTML file, relative to the dist directory.
   * @example 'index.html'
   */
  filename: string;
  /**
   * The environment context for current build.
   */
  environment: EnvironmentContext;
};

function ModifyHTMLTags(
  callback: (tags: HTMLTags, context: Context) => MaybePromise<HTMLTags>,
): void;
```

* **Example:**

```ts
const tagsPlugin = () => ({
  name: 'tags-plugin',
  setup(api) {
    api.modifyHTMLTags(({ headTags, bodyTags }) => {
      // Inject a tag into <head>, before other tags
      headTags.unshift({
        tag: 'script',
        attrs: { src: 'https://example.com/foo.js' },
      });

      // Inject a tag into <head>, after other tags
      headTags.push({
        tag: 'script',
        attrs: { src: 'https://example.com/bar.js' },
      });

      // Inject a tag into <body>, before other tags
      bodyTags.unshift({
        tag: 'div',
        children: 'before other body tags',
      });

      // Inject a tag into <body>, after other tags
      bodyTags.push({
        tag: 'div',
        children: 'after other body tags',
      });

      return { headTags, bodyTags };
    });
  },
});
```

See [html.tags](/config/html/tags.md) for more details on how to define tags.

:::tip

When using `modifyHTML`, `modifyHTMLTags`, and `html.tags` options together, the execution order is as follows:

1. [modifyHTML](#modifyhtml)
2. [modifyHTMLTags](#modifyhtmltags)
3. [html.tags](/config/html/tags.md)

:::

### onBeforeCreateCompiler

import OnBeforeCreateCompiler from '@en/shared/onBeforeCreateCompiler.mdx';

<OnBeforeCreateCompiler />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onBeforeCreateCompiler(({ bundlerConfigs }) => {
      console.log('the bundler configs are ', bundlerConfigs);
    });
  },
});
```

### onAfterCreateCompiler

import OnAfterCreateCompiler from '@en/shared/onAfterCreateCompiler.mdx';

<OnAfterCreateCompiler />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onAfterCreateCompiler(({ compiler }) => {
      console.log('the compiler is ', compiler);
    });
  },
});
```

### onBeforeEnvironmentCompile

import OnBeforeEnvironmentCompile from '@en/shared/onBeforeEnvironmentCompile.mdx';

<OnBeforeEnvironmentCompile />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onBeforeEnvironmentCompile(({ bundlerConfig, environment }) => {
      console.log(
        `the bundler config for the ${environment.name} is `,
        bundlerConfig,
      );
    });
  },
});
```

### onAfterEnvironmentCompile

import OnAfterEnvironmentCompile from '@en/shared/onAfterEnvironmentCompile.mdx';

<OnAfterEnvironmentCompile />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onAfterEnvironmentCompile(({ isFirstCompile, stats }) => {
      console.log(stats?.toJson(), isFirstCompile);
    });
  },
});
```

## Build hooks

### onBeforeBuild

import OnBeforeBuild from '@en/shared/onBeforeBuild.mdx';

<OnBeforeBuild />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onBeforeBuild(({ bundlerConfigs }) => {
      console.log('the bundler configs are ', bundlerConfigs);
    });
  },
});
```

### onAfterBuild

import OnAfterBuild from '@en/shared/onAfterBuild.mdx';

<OnAfterBuild />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onAfterBuild(({ isFirstCompile, stats }) => {
      console.log(stats?.toJson(), isFirstCompile);
    });
  },
});
```

### onCloseBuild

import OnCloseBuild from '@en/shared/onCloseBuild.mdx';

<OnCloseBuild />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onCloseBuild(() => {
      console.log('close build!');
    });
  },
});
```

## Dev hooks

### onBeforeStartDevServer

import OnBeforeStartDevServer from '@en/shared/onBeforeStartDevServer.mdx';

<OnBeforeStartDevServer />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onBeforeStartDevServer(({ server, environments }) => {
      console.log('before starting dev server.');
      console.log('the server is ', server);
      console.log('the environments contexts are: ', environments);
    });
  },
});
```

#### Register middleware

A common usage scenario is to register custom middleware in `onBeforeStartDevServer`:

```ts
const myPlugin = () => ({
  setup(api) {
    api.onBeforeStartDevServer(({ server }) => {
      server.middlewares.use((req, res, next) => {
        next();
      });
    });
  },
});
```

When `onBeforeStartDevServer` is called, the default middleware of Rsbuild are not registered yet, so the middleware you add will run before the default middleware.

`onBeforeStartDevServer` allows you to return a callback function, which will be called when the default middleware of Rsbuild are registered. The middleware you register in the callback function will run after the default middleware.

```ts
const myPlugin = () => ({
  setup(api) {
    api.onBeforeStartDevServer(({ server }) => {
      // the returned callback will be called when the default
      // middleware are registered
      return () => {
        server.middlewares.use((req, res, next) => {
          next();
        });
      };
    });
  },
});
```

#### Store server instance

If you need to access `server` in other hooks, you can store the `server` instance through `api.onBeforeStartDevServer`, and then access it in the hooks executed later. Note that you cannot access `server` in hooks that are executed earlier than `onBeforeStartDevServer`.

```ts
import type { RsbuildDevServer } from '@rsbuild/core';

const myPlugin = () => ({
  setup(api) {
    let devServer: RsbuildDevServer | null = null;

    api.onBeforeStartDevServer(({ server, environments }) => {
      devServer = server;
    });

    api.transform({ test: /\.foo$/ }, ({ code }) => {
      if (devServer) {
        // access server API
      }
      return code;
    });

    api.onCloseDevServer(() => {
      devServer = null;
    });
  },
});
```

### onAfterStartDevServer

import OnAfterStartDevServer from '@en/shared/onAfterStartDevServer.mdx';

<OnAfterStartDevServer />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onAfterStartDevServer(({ port, routes }) => {
      console.log('this port is: ', port);
      console.log('this routes is: ', routes);
    });
  },
});
```

### onBeforeDevCompile

import OnBeforeDevCompile from '@en/shared/onBeforeDevCompile.mdx';

<OnBeforeDevCompile />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onBeforeDevCompile(({ bundlerConfigs }) => {
      console.log('the bundler configs are ', bundlerConfigs);
    });
  },
});
```

### onAfterDevCompile

import OnAfterDevCompile from '@en/shared/onAfterDevCompile.mdx';

<OnAfterDevCompile />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onAfterDevCompile(({ isFirstCompile }) => {
      if (isFirstCompile) {
        console.log('first compile!');
      } else {
        console.log('re-compile!');
      }
    });
  },
});
```

### onCloseDevServer

import OnCloseDevServer from '@en/shared/onCloseDevServer.mdx';

<OnCloseDevServer />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onCloseDevServer(async () => {
      console.log('close dev server!');
    });
  },
});
```

## Preview hooks

### onBeforeStartProdServer

import OnBeforeStartProdServer from '@en/shared/onBeforeStartProdServer.mdx';

<OnBeforeStartProdServer />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onBeforeStartProdServer(() => {
      console.log('before start!');
    });
  },
});
```

### onAfterStartProdServer

import OnAfterStartProdServer from '@en/shared/onAfterStartProdServer.mdx';

<OnAfterStartProdServer />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onAfterStartProdServer(({ port, routes }) => {
      console.log('this port is: ', port);
      console.log('this routes is: ', routes);
    });
  },
});
```

## Other hooks

### onExit

import OnExit from '@en/shared/onExit.mdx';

<OnExit />

* **Example:**

```ts
const myPlugin = () => ({
  setup(api) {
    api.onExit(({ exitCode }) => {
      console.log('exit: ', exitCode);
    });
  },
});
```

---

# Source: https://rsbuild.dev/config/server/host.md

# server.host

* **Type:** `string`
* **Default:** `0.0.0.0`

Specify the host that the Rsbuild server listens to.

By default, the Rsbuild server will listen to `0.0.0.0`, which means listening to all IPv4 network interfaces, including `localhost` and public network addresses.

You can use `server.host` or the `--host` CLI param to set the host (The priority of `--host` option is higher than `server.host`).

If you want the Rsbuild server to listen only on `localhost`, you can set it to:

```ts title="rsbuild.config.ts"
export default {
  server: {
    host: 'localhost',
  },
};
```

## IPv6 Support

If you want the Rsbuild server to listen all IPv6 network interfaces, you can set it to:

```ts title="rsbuild.config.ts"
export default {
  server: {
    host: '::',
  },
};
```

If you want the Rsbuild server to listen a specified IPv6 host, you can set it to:

```ts title="rsbuild.config.ts"
export default {
  server: {
    host: '::1',
  },
};
```

At this point, you can access the page via `http://[::1]:3000/`.

---

# Source: https://rsbuild.dev/config/server/html-fallback.md

# server.htmlFallback

* **Type:** `false | 'index'`
* **Default:** `'index'`

Whether to enable HTML fallback.

## Default behavior

By default, when the request meets the following conditions and the corresponding resource is not found, it will fallback to `index.html`:

* The request is a `GET` or `HEAD` request
* Which accepts `text/html` (the request header accept type is `text/html` or `*/*`)

```ts title="rsbuild.config.ts"
export default {
  server: {
    htmlFallback: 'index',
  },
};
```

## Disable

If you do not want to enable HTML fallback, you can set `server.htmlFallback` to `false`.

```ts title="rsbuild.config.ts"
export default {
  server: {
    htmlFallback: false,
  },
};
```

## Customize

If `server.htmlFallback` cannot meet your needs, you can use [server.historyApiFallback](/config/server/history-api-fallback.md) for more flexible settings.

---

# Source: https://rsbuild.dev/config/tools/html-plugin.md

# tools.htmlPlugin

* **Type:** `boolean | Object | Function`
* **Default:**

```js
const defaultOptions = {
  meta, // Corresponds to `html.meta` config
  title, // Corresponds to `html.title` config
  inject, // Corresponds to `html.inject` config
  favicon, // Corresponds to `html.favicon` config
  template, // Corresponds to `html.template` config
  filename, // Generated based on `output.distPath` and `entryName`
  templateParameters, // Corresponds to `html.templateParameters` config
  chunks: [entryName],
};
```

The configs of [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin) can be modified through `tools.htmlPlugin`.

Rsbuild internally implements HTML-related features based on [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin). It is a fork of [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin), with the same features and options.

:::tip
If you need to modify options such as `title`, `template`, `templateParameters`, `meta`, it is recommended to use the corresponding HTML configurations provided by Rsbuild first, such as [html.title](/config/html/title.md), [html.template](/config/html/template.md) etc.

This is because Rsbuild provides some internal optimization processing for these HTML configurations. For example, if the HTML template used by the current project already contains the `<title>` tag, then `html.title` will not take effect.
:::

## Object type

When `tools.htmlPlugin` is `Object` type, the value will be merged with the default config via `Object.assign`.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    htmlPlugin: {
      scriptLoading: 'blocking',
    },
  },
};
```

## Function type

When `tools.htmlPlugin` is a Function:

* The first parameter is the default config, which can be modified directly.
* The second parameter is also an object, containing the entry name and the entry value.
* The Function can return a new object as the final config.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    htmlPlugin(config, { entryName, entryValue }) {
      if (entryName === 'main') {
        config.scriptLoading = 'blocking';
      }
    },
  },
};
```

## Disable HTML

Setting `tools.htmlPlugin` to `false` can disable the built-in `html-rspack-plugin` in Rsbuild, and no HTML files will be generated.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    htmlPlugin: false,
  },
};
```

## Example

### Modify HTML file name

The `filename` option can be used to modify the file name of the HTML output.

For example, in production mode, a `hash` can be added to the file name:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    htmlPlugin(config, { entryName }) {
      if (process.env.NODE_ENV === 'production') {
        config.filename = `${entryName}.[contenthash:8].html`;
      }
    },
  },
};
```

## HTML minification

Rsbuild currently does not minify HTML files. To minify HTML files, use the [rsbuild-plugin-html-minifier-terser plugin](https://github.com/rstackjs/rsbuild-plugin-html-minifier-terser).

---

# Source: https://rsbuild.dev/config/server/https.md

# server.https

* **Type:**

```ts
import type { ServerOptions } from 'node:https';
import type { SecureServerSessionOptions } from 'node:http2';

type Https = ServerOptions | SecureServerSessionOptions;
```

* **Default:** `undefined`

Configure HTTPS options to enable HTTPS server. When enabled, HTTP server will be disabled.

HTTP:

```
  ➜ Local: http://localhost:3000/
  ➜ Network: http://192.168.0.1:3000/
```

HTTPS:

```
  ➜ Local: https://localhost:3000/
  ➜ Network: https://192.168.0.1:3000/
```

:::tip
When HTTPS is enabled, Rsbuild uses an HTTP/2 server by default. However, if you enable [server.proxy](/config/server/proxy.md), the dev server falls back to HTTP/1 because its underlying dependency, [http-proxy](https://www.npmjs.com/package/http-proxy), does not support HTTP/2.
:::

## Set certificate

You can manually pass in the certificate and the private key required in the `server.https` option. This parameter will be directly passed to the `createServer` method of the https module in Node.js.

For details, please refer to [https.createServer](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener).

```ts
import fs from 'node:fs';

export default {
  server: {
    https: {
      key: fs.readFileSync('certificates/private.pem'),
      cert: fs.readFileSync('certificates/public.pem'),
    },
  },
};
```

:::tip
The certificates used for local development are typically generated using [mkcert](https://github.com/FiloSottile/mkcert). Please read ["How to use HTTPS for local development"](https://web.dev/articles/how-to-use-local-https?hl=en) to learn how to use it.
:::

## Self-signed Certificate

For basic configuration requirements, you can add the [@rsbuild/plugin-basic-ssl](https://github.com/rstackjs/rsbuild-plugin-basic-ssl) plugin, which will automatically create a self-signed certificate and set `server.https` option by default.

```ts
import { pluginBasicSsl } from '@rsbuild/plugin-basic-ssl';

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

---

# Source: https://rsbuild.dev/config/source/include.md

# source.include

* **Type:** [Rspack.RuleSetCondition](https://rspack.rs/config/module-rules#condition)

Specify additional JavaScript files that need to be compiled by [SWC](/guide/configuration/swc.md).

## Default value

By default, Rsbuild's built-in [swc-loader](https://rspack.rs/guide/features/builtin-swc-loader) compiles the following files:

* TypeScript and JSX files in any directory, matching file extensions `.ts`, `.tsx`, `.jsx`, `.mts`, `.cts`.
* JavaScript files that are not in the `node_modules` directory, matching file extensions `.js`, `.mjs`, `.cjs`.

The default value of `source.include` can be expressed as:

```ts
const defaultInclude = [
  { not: /[\\/]node_modules[\\/]/ },
  /\.(?:ts|tsx|jsx|mts|cts)$/,
];
```

## Usage

Through the `source.include` configuration, you can specify directories or modules that need to be compiled by Rsbuild. The usage of `source.include` is consistent with [rules\[\].include](https://rspack.rs/config/module-rules#rulesinclude) in Rspack, which supports passing in strings or regular expressions to match the module path.

For example:

```ts title="rsbuild.config.ts"
import path from 'node:path';

export default {
  source: {
    include: [path.resolve(__dirname, '../other-dir')],
  },
};
```

## Compile npm packages

A typical usage scenario is to compile npm packages under node\_modules, because some third-party dependencies have ESNext syntax, which may cause them to fail to run on older browsers. You can solve this problem by using this configuration to specify the dependencies that need to be compiled.

:::tip
If you are unsure which third-party dependencies in node\_modules contain ESNext syntax, you can use the [@rsbuild/plugin-check-syntax](https://github.com/rstackjs/rsbuild-plugin-check-syntax) for checking. The plugin can help you find the modules that contain ESNext syntax.
:::

Take `query-string` as an example, you can add the following configuration:

```ts title="rsbuild.config.ts"
import path from 'node:path';

export default {
  source: {
    include: [
      // Method 1:
      // Match by regular expression
      // All paths containing `node_modules/query-string/` will be matched
      /node_modules[\\/]query-string[\\/]/,
      // Method 2:
      // First get the path of the module by require.resolve
      // Then pass path.dirname to point to the corresponding directory
      path.dirname(require.resolve('query-string')),
    ],
  },
};
```

The above two methods match the absolute paths of files using "path prefixes" and "regular expressions" respectively. It is worth noting that all referenced modules in the project will be matched. Therefore, you should avoid using overly loose values for matching to prevent compilation performance issues or compilation errors.

:::tip
In the regular expression example, we use `[\\/]` to match the path separator because different operating systems use different path separators. Using `[\\/]` ensures that the paths can be matched on macOS, Linux and Windows.
:::

## Compile sub dependencies

When you compile an npm package via `source.include`, Rsbuild will only compile the matching module by default, not the **Sub Dependencies** of the module.

Take `query-string` for example, it depends on the `decode-uri-component` package, which also has ESNext code, so you need to add the `decode-uri-component` package to `source.include` as well.

```ts title="rsbuild.config.ts"
export default {
  source: {
    include: [
      /node_modules[\\/]query-string[\\/]/,
      /node_modules[\\/]decode-uri-component[\\/]/,
    ],
  },
};
```

## Matching symlink

If you match a module that is symlinked to the current project, then you need to match the **real path** of the module, not the symlinked path.

For example, if you symlink the `packages/foo` path in Monorepo to the `node_modules/foo` path of the current project, you need to match the `packages/foo` path, not the `node_modules/foo` path.

## Compile node\_modules

In general, `source.include` should not be used to compile the entire `node_modules` directory. For example, the following configuration is not recommended:

```ts title="rsbuild.config.ts"
export default {
  source: {
    include: [/[\\/]node_modules[\\/]/],
  },
};
```

This is because most of the npm packages in `node_modules` are already compiled, and it is usually unnecessary to recompile them. Compiling the entire `node_modules` will increase compilation time and may cause unexpected errors in certain npm packages, such as `core-js`, which may result in runtime exceptions after compilation.

If you are willing to accept the increase in compilation time, you can use the following configuration to compile all JavaScript files but exclude \`core-js':

```ts title="rsbuild.config.ts"
export default {
  source: {
    include: [{ not: /[\\/]core-js[\\/]/ }],
  },
};
```

---

# Source: https://rsbuild.dev/community/releases/index.md

# Source: https://rsbuild.dev/community/index.md

# Source: https://rsbuild.dev/api/start/index.md

# Source: https://rsbuild.dev/plugins/dev/index.md

# Source: https://rsbuild.dev/plugins/list/index.md

# Source: https://rsbuild.dev/config/index.md

# Source: https://rsbuild.dev/guide/start/index.md

# Introduction

Rsbuild is a high-performance build tool powered by Rspack. It provides carefully designed defaults for an out-of-the-box development experience while fully leveraging Rspack's performance.

Rsbuild provides a [rich set of build features](/guide/start/features.md), including support for TypeScript, JSX, Sass, Less, CSS Modules, Wasm, and more. It also supports Module Federation, image compression, type checking, PostCSS, Lightning CSS, and additional features.

## 🚀 Performance

Powered by Rspack's Rust-based architecture, Rsbuild delivers blazing-fast performance to speed up your development workflow.

⚡️ **Build 1000 React components:**

import { BenchmarkGraph } from '@components/Benchmark';

<BenchmarkGraph />

> 📊 Benchmark results from [build-tools-performance](https://github.com/rstackjs/build-tools-performance).

## 💡 Comparisons

Rsbuild is comparable to [Vite](https://vitejs.dev/), [Create React App](https://github.com/facebook/create-react-app), and [Vue CLI](https://github.com/vuejs/vue-cli). Each of these tools includes a built-in dev server, command-line tools, and sensible defaults for an out-of-the-box experience.

![](https://assets.rspack.rs/rsbuild/assets/rsbuild-1-0-build-tools.png)

### CRA / Vue CLI

You can think of Rsbuild as a modernized version of Create React App or Vue CLI, with these key differences:

* The underlying bundler has been switched from webpack to Rspack, delivering 5 to 10 times better build performance.
* It's decoupled from frontend UI frameworks and supports all frameworks via [plugins](/plugins/list/index.md), including React, Vue, Svelte, Solid, and more.
* It is more extensible. You can extend Rsbuild through [configurations](/config/index.md), the [Plugin API](/plugins/dev/index.md), and the [JavaScript API](/api/start/index.md).

### Vite

Rsbuild has many similarities to Vite, as both aim to improve the frontend development experience. The main differences are:

* **Production consistency**: Rsbuild uses Rspack for bundling in both development and production builds, ensuring high consistency between development and production outputs. Vite uses ESM during development for faster startup, but this approach can introduce inconsistencies between development and production outputs.
* **Ecosystem compatibility**: Rsbuild is compatible with most webpack plugins and all Rspack plugins, while Vite is compatible with Rollup plugins. If you're using many plugins and loaders from the webpack ecosystem, migration to Rsbuild is more straightforward.
* **Module Federation**: The Rsbuild team works closely with the [Module Federation](/guide/advanced/module-federation.md) development team, providing first-class support for Module Federation to help you develop large web applications with micro-frontend architecture.

## 🔥 Features

Rsbuild has the following features:

* **Easy to configure**: One of Rsbuild's goals is to give Rspack users out-of-the-box build capabilities so they can start web projects with zero configuration. Rsbuild also provides a semantic build configuration API to reduce the Rspack learning curve.

* **Performance-focused**: Rsbuild integrates high-performance Rust-based tools from the community, including [Rspack](https://rspack.rs), [SWC](https://swc.rs/), and [Lightning CSS](https://lightningcss.dev/), delivering first-class build speed and development experience.

* **Plugin ecosystem**: Rsbuild has a lightweight plugin system and includes a range of high-quality official plugins. It is also compatible with most webpack plugins and all Rspack plugins, allowing you to use existing community or in-house plugins without rewriting code.

* **Stable artifacts**: Rsbuild places a strong focus on build artifact stability. It ensures consistent artifacts in development and production builds, and automatically handles syntax downgrading and polyfill injection. Rsbuild also provides plugins for type checking and artifact syntax validation to prevent quality and compatibility issues from reaching production code.

* **Framework agnostic**: Rsbuild is not coupled to any frontend UI framework. It supports frameworks like React, Vue, Svelte, Solid, and Preact through plugins, with plans to support more UI frameworks from the community in the future.

## 🦀 Rstack

Rstack is a unified JavaScript toolchain centered on Rspack, with high performance and consistent architecture.

<img src="https://assets.rspack.rs/rstack/rstack-overview.png" alt="Rstack" width="820" />

Rstack includes the following tools:

| 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 showcasing Rstack tools.
* [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.

## ✨ Next step

Next, you may want to:

import NextSteps from '@components/NextSteps';
import Step from '@components/Step';

<NextSteps>
  <Step href="/guide/start/quick-start" title="Quick start" description="Learn how to use Rsbuild" />

  <Step href="/guide/start/features" title="All features" description="Learn all features of Rsbuild" />

  <Step href="https://github.com/web-infra-dev/rsbuild" title="Support Rsbuild" description="Support us with a star ⭐️" />
</NextSteps>

---

# Source: https://rsbuild.dev/config/output/inject-styles.md

# output.injectStyles

* **Type:** `boolean`
* **Default:** `false`

Whether to inject styles into DOM.

By default, Rsbuild will extract CSS into a separate `.css` file and output it to the dist directory. When this option is set to `true`, CSS files will be inlined into JS files and inserted on the page at runtime via `<style>` tags. This feature is implemented based on [style-loader](https://npmjs.com/package/style-loader).

### Example

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

## Configure style-loader

When `output.injectStyles` is enabled, you can modify the options of `style-loader` through [tools.styleLoader](/config/tools/style-loader.md).

### Usage scenario

We recommend enabling the `injectStyles` option only in development.

For production builds, we recommend using Rsbuild's default behavior, which extracts CSS into separate bundles so browsers can load CSS and JS assets in parallel.

For example:

```ts title="rsbuild.config.ts"
export default {
  output: {
    injectStyles: process.env.NODE_ENV === 'development',
  },
};
```

---

# Source: https://rsbuild.dev/guide/optimization/inline-assets.md

# Inline static assets

Inlining static assets refers to embedding the content of a static asset directly in an HTML or JS file instead of linking to an external file. This can improve website performance by reducing the number of HTTP requests the browser needs to make to load the page.

However, inlining static assets has some disadvantages, such as increasing the size of a single file, which may lead to slower loading. Decide whether to inline assets based on your specific situation.

Rsbuild automatically inlines static assets smaller than 4KiB. Sometimes you may need to manually control whether assets are inlined. This document explains how to precisely control the inlining behavior of static assets.

## Automatic inlining

By default, Rsbuild inlines assets when the file size is less than a threshold (default is 4KiB). When inlined, the asset is converted to a Base64 encoded string and no longer requires a separate HTTP request. When the file size is greater than this threshold, it is loaded as a separate file with its own HTTP request.

```js
import smallImage from './static/smallImage.png';

console.log(smallImage); // "data:image/png;base64,iVBORw0KGgo..."
```

You can modify the threshold with the [output.dataUriLimit](/config/output/data-uri-limit.md) config. For example, set the threshold for images to 5000 bytes and disable inlining for media assets:

```ts
export default {
  output: {
    dataUriLimit: {
      image: 5000,
      media: 0,
    },
  },
};
```

## Force inlining

You can force an asset to be inlined by adding the `inline` query parameter when importing it, regardless of the asset's size.

```tsx
import React from 'react';
import img from './foo.png?inline';

export default function Foo() {
  return <img src={img} />;
}
```

In the above example, the `foo.png` image will always be inlined, regardless of the image size.

### Referenced from CSS file

When you reference a static asset in your CSS file, you can also force it to inline with the `inline` query parameter.

```css
.foo {
  background-image: url('./icon.png?inline');
}
```

:::tip Impact of forcing inlining
Inlining large assets will significantly increase the first paint time or first contentful paint time of a page, degrading user experience. If you inline a static asset multiple times in a CSS file, the base64 content will be injected repeatedly, increasing bundle size. Use forced inlining with caution.
:::

## Disable inlining

To prevent assets from being inlined and ensure they're always loaded as separate files (regardless of their size), add the `url` query parameter.

```tsx
import React from 'react';
import img from './foo.png?url';

export default function Foo() {
  return <img src={img} />;
}
```

In the above example, the `foo.png` image will always be loaded as a separate file, even if it's smaller than the threshold.

### Referenced from CSS file

When you reference a static asset in your CSS file, you can also prevent inlining with the `url` query parameter.

```css
.foo {
  background-image: url('./icon.png?url');
}
```

:::tip Impact of disabling inlining
Disabling asset inlining will increase the number of assets the web application needs to load. This will reduce loading efficiency in weak network environments or scenarios where HTTP/2 is not enabled. Use with caution.
:::

## Inline JS files

In addition to inlining static assets into JS files, Rsbuild also supports inlining JS files into HTML files.

Enable the [output.inlineScripts](/config/output/inline-scripts.md) config, and the generated JS files will not be written to the output directory but will be directly inlined in the HTML file.

```ts
export default {
  output: {
    inlineScripts: true,
  },
};
```

:::tip
Inline JS files may cause the HTML file to become too large and will break HTTP caching. Use with caution.
:::

## Inline CSS files

You can also inline CSS files into HTML files.

Just enable the [output.inlineStyles](/config/output/inline-styles.md) config, and the generated CSS file will not be written to the output directory, but will be directly inlined in the HTML file.

```ts
export default {
  output: {
    inlineStyles: true,
  },
};
```

## Type declaration

When you use URL queries such as `?inline` and `?url` in TypeScript code, TypeScript may prompt that the module is missing a type definition:

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

To fix this, you can add type declarations for these URL queries. Create a `src/env.d.ts` file and add the following type declarations:

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

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

* Method 2: Manually add the required type declarations:

```ts
declare module '*?url' {
  const content: string;
  export default content;
}
declare module '*?inline' {
  const content: string;
  export default content;
}
```

---

# Source: https://rsbuild.dev/api/javascript-api/instance.md

# Rsbuild instance

This section describes all the properties and methods on the Rsbuild instance object.

## rsbuild.context

`rsbuild.context` is a read-only object that provides some context information, which can be accessed in two ways:

1. Access through the `context` property of the Rsbuild instance:

```ts
import { createRsbuild } from '@rsbuild/core';

const rsbuild = createRsbuild({
  // ...
});

console.log(rsbuild.context);
```

2. Access through the [api.context](/plugins/dev/core.md#apicontext) of the Rsbuild plugin:

```ts
export const myPlugin = {
  name: 'my-plugin',
  setup(api) {
    console.log(api.context);
  },
};
```

### context.version

The version of `@rsbuild/core` currently in use.

* **Type:**

```ts
type Version = string;
```

### context.rootPath

The root path of the current build, corresponding to the `cwd` option of the [createRsbuild](/api/javascript-api/core.md#creatersbuild) method.

* **Type:**

```ts
type RootPath = string;
```

### context.distPath

The absolute path of the output directory, corresponding to the [output.distPath.root](/config/output/dist-path.md) config in `RsbuildConfig`.

When multiple environments exist, Rsbuild attempts to find the parent distPath of all environments as `context.distPath`.

To get the absolute path to a specific environment's output directory, use [environment.distPath](/api/javascript-api/environment-api.md#distpath).

* **Type:**

```ts
type DistPath = string;
```

### context.cachePath

The absolute path of the build cache files.

* **Type:**

```ts
type CachePath = string;
```

### context.callerName

The name of the framework or tool that is currently invoking Rsbuild, the same as the [callerName](/api/javascript-api/core.md#specify-caller-name) option in the [createRsbuild](/api/javascript-api/core.md#creatersbuild) method.

* **Type:** `string`
* **Default:** `'rsbuild'`
* **Example:**

```ts title="myPlugin.ts"
export const myPlugin = {
  name: 'my-plugin',
  setup(api) {
    const { callerName } = api.context;

    if (callerName === 'rslib') {
      // ...
    } else if (callerName === 'rsbuild') {
      // ...
    }
  },
};
```

Here are some tools based on Rsbuild that have already set the `callerName` value:

| Name                                                | callerName  |
| --------------------------------------------------- | ----------- |
| [Rslib](https://github.com/web-infra-dev/rslib)     | `'rslib'`   |
| [Rstest](https://github.com/web-infra-dev/rstest)   | `'rstest'`  |
| [Rspress](https://github.com/web-infra-dev/rspress) | `'rspress'` |
| [Rspeedy](https://lynxjs.org/rspeedy)               | `'rspeedy'` |

### context.devServer

Dev server information when running in dev mode. Available after the dev server has been created.

* **Type:**

```ts
type DevServer = {
  /** The hostname the server is running on. */
  hostname: string;
  /** The actual port number the server is listening on. */
  port: number;
  /** Whether the server is using HTTPS protocol. */
  https: boolean;
};
```

* **Example:**

```ts
import { createRsbuild } from '@rsbuild/core';

async function main() {
  const rsbuild = createRsbuild({
    // ...
  });
  await rsbuild.startDevServer();

  // { hostname: 'localhost', port: 3000, https: false }
  console.log(rsbuild.context.devServer);
}
```

### context.action

The current action type.

* **Type:**

```ts
type Action = 'dev' | 'build' | 'preview' | undefined;
```

`context.action` is set when running CLI commands or calling Rsbuild instance methods:

* `dev`: set when running [rsbuild dev](/guide/basic/cli.md#rsbuild-dev) or [rsbuild.startDevServer()](/api/javascript-api/instance.md#rsbuildstartdevserver)
* `build`: set when running [rsbuild build](/guide/basic/cli.md#rsbuild-build) or [rsbuild.build()](/api/javascript-api/instance.md#rsbuildbuild)
* `preview`: set when running [rsbuild preview](/guide/basic/cli.md#rsbuild-preview) or [rsbuild.preview()](/api/javascript-api/instance.md#rsbuildpreview)

For example:

```ts
if (rsbuild.context.action === 'dev') {
  // do something
}
```

### context.bundlerType

The bundler type for the current build.

* **Type:**

```ts
type bundlerType = 'rspack' | 'webpack';
```

> Rsbuild internally supports switching to webpack for comparative testing, so this field is provided for differentiation. Usually, you do not need to use this field.

## rsbuild.build

Runs a production build, generating optimized production bundles and writing them to the output directory.

* **Type:**

```ts
type BuildOptions = {
  /**
   * 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
import { logger } from '@rsbuild/core';

// Example 1: run build
await rsbuild.build();

// Example 2: build and handle the error
try {
  await rsbuild.build();
} catch (err) {
  logger.error('Failed to build.');
  logger.error(err);
  process.exit(1);
}

// Example 3: build and get all assets
const { stats } = await rsbuild.build();

if (stats) {
  const { assets } = stats.toJson({
    // exclude unused fields to improve performance
    all: false,
    assets: true,
  });
  console.log(assets);
}
```

### Monitor file changes

To watch file changes and re-build, set the `watch` option to `true`.

```ts
await rsbuild.build({
  watch: true,
});
```

### Close build

`rsbuild.build()` returns a `close()` method that stops the build process.

In watch mode, calling the `close()` method will stop watching:

```ts
const buildResult = await rsbuild.build({
  watch: true,
});
await buildResult.close();
```

In non-watch mode, also call the `close()` method to end the build, which triggers the [onCloseBuild](/plugins/dev/hooks.md#onclosebuild) hook for cleanup operations.

```ts
const buildResult = await rsbuild.build();
await buildResult.close();
```

### Stats object

In non-watch mode, `rsbuild.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 rsbuild.build();
const { stats } = result;

if (stats) {
  const { assets } = stats.toJson({
    // exclude unused fields to improve performance
    all: false,
    assets: true,
  });
  console.log(assets);
}
```

## rsbuild.startDevServer

Starts the local dev server. This method will:

1. Start a development server to serve your application
2. Watch for file changes and trigger recompilation

* **Type:**

```ts
type StartDevServerOptions = {
  /**
   * Whether to get port silently and not print any logs.
   * @default false
   */
  getPortSilently?: boolean;
};

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 StartDevServer(
  options?: StartDevServerOptions,
): Promise<StartServerResult>;
```

* **Example:**

Start dev server:

```ts
import { logger } from '@rsbuild/core';

// Start dev server
await rsbuild.startDevServer();

// Start dev server and handle the error
try {
  await rsbuild.startDevServer();
} catch (err) {
  logger.error('Failed to start dev server.');
  logger.error(err);
  process.exit(1);
}
```

Once the dev server starts successfully, these logs appear:

```
  ➜ Local:    http://localhost:3000
  ➜ Network:  http://192.168.0.1:3000
```

`startDevServer` returns these parameters:

* `urls`: URLs to access dev server.
* `port`: The actual listening port number.
* `server`: Server instance object.

```ts
const { urls, port } = await rsbuild.startDevServer();
console.log(urls); // ['http://localhost:3000', 'http://192.168.0.1:3000']
console.log(port); // 3000
```

### Close server

Call the `close()` method to close the dev server, trigger the [onCloseDevServer](/plugins/dev/hooks.md#onclosedevserver) hook, and perform cleanup operations.

```ts
const { server } = await rsbuild.startDevServer();
await server.close();
```

### Get port silently

When the default startup port is occupied, Rsbuild automatically increments the port number until it finds an available one. This process outputs a prompt log. To suppress this log, set `getPortSilently` to `true`.

```ts
await rsbuild.startDevServer({
  getPortSilently: true,
});
```

## rsbuild.createDevServer

Rsbuild includes a built-in dev server designed to improve the development experience. When you run the `rsbuild dev` command, the server starts automatically and provides features such as page preview, routing, and hot module reloading.

* To integrate the Rsbuild dev server into a custom server, you can use the `createDevServer` method to create a dev server instance. Please refer to [Dev server API](/api/javascript-api/dev-server-api.md) for all available APIs.
* To use Rsbuild dev server to start the project directly, you can use the [rsbuild.startDevServer](#rsbuildstartdevserver) method directly. `rsbuild.startDevServer` is actually syntactic sugar for the following code:

```ts
const server = await rsbuild.createDevServer();
await server.listen();
```

## rsbuild.preview

Starts a server to preview the production build locally. This method should be executed after [rsbuild.build](#rsbuildbuild).

* **Type:**

```ts
type PreviewOptions = {
  /**
   * Whether to get port silently
   * @default false
   */
  getPortSilently?: boolean;
  /**
   * Whether to check if the dist directory exists and is not empty.
   * @default true
   */
  checkDistDir?: boolean;
};

type StartServerResult = {
  /**
   * The URLs that server is listening on.
   */
  urls: string[];
  /**
   * The actual port used by the server.
   */
  port: number;
  server: {
    /**
     * Close the server.
     */
    close: () => Promise<void>;
  };
};

function preview(options?: PreviewOptions): Promise<StartServerResult>;
```

* **Example:**

Start the server:

```ts
import { logger } from '@rsbuild/core';

// Start preview server
await rsbuild.preview();

// Start preview server and handle the error
try {
  await rsbuild.preview();
} catch (err) {
  logger.error('Failed to start preview server.');
  logger.error(err);
  process.exit(1);
}
```

`preview` returns the following parameters:

* `urls`: URLs to access server.
* `port`: The actual listening port number.
* `server`: Server instance object.

```ts
const { urls, port } = await rsbuild.preview();
console.log(urls); // ['http://localhost:3000', 'http://192.168.0.1:3000']
console.log(port); // 3000
```

### Close server

Calling the `close()` method will close the preview server.

```ts
const { server } = await rsbuild.preview();
await server.close();
```

## rsbuild.createCompiler

Creates an Rspack [Compiler](https://rspack.rs/api/javascript-api/compiler) instance. If there are multiple [environments](/config/environments.md) for this build, the return value is [MultiCompiler](https://rspack.rs/api/javascript-api/compiler#multicompiler).

* **Type:**

```ts
function CreateCompiler(): Promise<Compiler | MultiCompiler>;
```

* **Example:**

```ts
const compiler = await rsbuild.createCompiler();
```

> You do not need to use this API unless you need to custom the dev server or other advanced scenarios.

## rsbuild.addPlugins

Registers one or more Rsbuild plugins, which can be called multiple times.

This method needs to be called before compiling. If it is called after compiling, it will not affect the compilation result.

* **Type:**

```ts
type AddPluginsOptions = { before?: string; environment?: string };

function AddPlugins(
  plugins: Array<RsbuildPlugin | Falsy>,
  options?: AddPluginsOptions,
): void;
```

* **Example:**

```ts
rsbuild.addPlugins([pluginFoo(), pluginBar()]);

// Insert before the bar plugin
rsbuild.addPlugins([pluginFoo()], { before: 'bar' });

// Add plugin for node environment
rsbuild.addPlugins([pluginFoo()], { environment: 'node' });
```

## rsbuild.getPlugins

Gets all the Rsbuild plugins registered in the current Rsbuild instance.

* **Type:**

```ts
function GetPlugins(options?: {
  /**
   * Get the plugins in the specified environment.
   * If environment is not specified, get the global plugins.
   */
  environment: string;
}): RsbuildPlugin[];
```

* **Example:**

```ts
// get all plugins
console.log(rsbuild.getPlugins());

// get plugins in `web` environment
console.log(rsbuild.getPlugins({ environment: 'web' }));
```

## rsbuild.removePlugins

Removes one or more Rsbuild plugins, which can be called multiple times.

This method needs to be called before compiling. If it is called after compiling, it will not affect the compilation result.

* **Type:**

```ts
function RemovePlugins(pluginNames: string[]): void;
```

* **Example:**

```ts
// add plugin
const pluginFoo = pluginFoo();
rsbuild.addPlugins(pluginFoo);

// remove plugin
rsbuild.removePlugins([pluginFoo.name]);
```

## rsbuild.isPluginExists

import IsPluginExists from '@en/shared/isPluginExists.mdx';

<IsPluginExists />

* **Example:**

```ts
const pluginFoo = {
  name: 'plugin-foo',
  setup(api) {
    // ...
  },
};

const rsbuild = createRsbuild({
  config: {
    plugins: [pluginFoo],
  },
});

rsbuild.isPluginExists(pluginFoo.name); // true
```

Or check if a plugin exists in a specified environment:

```ts
const rsbuild = createRsbuild({
  config: {
    environments: {
      web: {
        plugins: [pluginFoo],
      },
    },
  },
});

rsbuild.isPluginExists(pluginFoo.name, {
  environment: 'web',
}); // true
```

## rsbuild.initConfigs

Initialize and return the internal Rspack configurations used by Rsbuild. This method processes all plugins and configurations to generate the final Rspack configs.

> Note: You typically do not need to call this method directly since it is automatically invoked by methods like [rsbuild.build](#rsbuildbuild) and [rsbuild.startDevServer](#rsbuildstartdevserver).

* **Type:**

```ts
type InitConfigsOptions = {
  /**
   * The current action type.
   * - dev: will be set when running `rsbuild dev` or `rsbuild.startDevServer()`
   * - build: will be set when running `rsbuild build` or `rsbuild.build()`
   * - preview: will be set when running `rsbuild preview` or `rsbuild.preview()`
   */
  action?: 'dev' | 'build' | 'preview';
};

function InitConfigs(options?: InitConfigsOptions): Promise<{
  rspackConfigs: Rspack.Configuration[];
}>;
```

* **Example:**

```ts
const rspackConfigs = await rsbuild.initConfigs();

console.log(rspackConfigs);

const buildConfigs = await rsbuild.initConfigs({
  action: 'build',
});

console.log(buildConfigs);
```

## rsbuild.inspectConfig

Inspects and debugs Rsbuild's internal configurations. It provides access to:

* 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 = {
  /**
   * Inspect the config in the specified mode.
   * Available options: 'development' or 'production'.
   * @default 'development'
   */
  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;
  /**
   * Extra configurations to be output.
   * - key: The name of the configuration
   * - value: The configuration object
   */
  extraConfigs?: Record<string, unknown>;
};

async function InspectConfig(options?: InspectConfigOptions): Promise<{
  rsbuildConfig: string;
  bundlerConfigs: string[];
  environmentConfigs: string[];
  origin: {
    rsbuildConfig: RsbuildConfig;
    environmentConfigs: Record<string, EnvironmentConfig>;
    bundlerConfigs: BundlerConfigs[];
  };
}>;
```

:::tip
To view the Rsbuild and Rspack configurations during the build process, use [debug mode](/guide/debug/debug-mode.md), or obtain them through hooks such as [onBeforeBuild](#rsbuildonbeforebuild), [onBeforeCreateCompile](#rsbuildonbeforecreatecompiler).
:::

### Example

Get the content of configs in string format:

```ts
const { rsbuildConfig, bundlerConfigs } = await rsbuild.inspectConfig();

console.log(rsbuildConfig, bundlerConfigs);
```

Write the config content to disk:

```ts
await rsbuild.inspectConfig({
  writeToDisk: true,
});
```

### Output path

You can set the output path using `outputPath`. The default value is [output.distPath.root](/config/output/dist-path.md).

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 rsbuild.inspectConfig({
  writeToDisk: true,
  outputPath: path.join(__dirname, 'custom-dir'),
});
```

## rsbuild.onBeforeCreateCompiler

> Provides the same functionality as the [onBeforeCreateCompiler](/plugins/dev/hooks.md#onbeforecreatecompiler) plugin hook.

import OnBeforeCreateCompiler from '@en/shared/onBeforeCreateCompiler.mdx';

<OnBeforeCreateCompiler />

* **Example:**

```ts
rsbuild.onBeforeCreateCompiler(({ bundlerConfigs }) => {
  console.log('the Rspack config is ', bundlerConfigs);
});
```

## rsbuild.onAfterCreateCompiler

> Provides the same functionality as the [onAfterCreateCompiler](/plugins/dev/hooks.md#onaftercreatecompiler) plugin hook.

import OnAfterCreateCompiler from '@en/shared/onAfterCreateCompiler.mdx';

<OnAfterCreateCompiler />

* **Example:**

```ts
rsbuild.onAfterCreateCompiler(({ compiler }) => {
  console.log('the compiler is ', compiler);
});
```

## rsbuild.onBeforeBuild

> Provides the same functionality as the [onBeforeBuild](/plugins/dev/hooks.md#onbeforebuild) plugin hook.

import OnBeforeBuild from '@en/shared/onBeforeBuild.mdx';

<OnBeforeBuild />

* **Example:**

```ts
rsbuild.onBeforeBuild(({ bundlerConfigs }) => {
  console.log('the Rspack config is ', bundlerConfigs);
});
```

## rsbuild.onAfterBuild

> Provides the same functionality as the [onAfterBuild](/plugins/dev/hooks.md#onafterbuild) plugin hook.

import OnAfterBuild from '@en/shared/onAfterBuild.mdx';

<OnAfterBuild />

* **Example:**

```ts
rsbuild.onAfterBuild(({ stats }) => {
  console.log(stats?.toJson());
});
```

## rsbuild.onCloseBuild

> Provides the same functionality as the [onCloseBuild](/plugins/dev/hooks.md#onclosebuild) plugin hook.

import OnCloseBuild from '@en/shared/onCloseBuild.mdx';

<OnCloseBuild />

* **Example:**

```ts
rsbuild.onCloseBuild(async () => {
  console.log('close build!');
});
```

## rsbuild.onBeforeStartDevServer

> Provides the same functionality as the [onBeforeStartDevServer](/plugins/dev/hooks.md#onbeforestartdevserver) plugin hook.

import OnBeforeStartDevServer from '@en/shared/onBeforeStartDevServer.mdx';

<OnBeforeStartDevServer />

* **Example:**

```ts
rsbuild.onBeforeStartDevServer(({ server, environments }) => {
  console.log('before starting dev server.');
  console.log('the server is ', server);
  console.log('the environments contexts are: ', environments);
});
```

> See [Plugin hooks - onBeforeStartDevServer](/plugins/dev/hooks.md#onbeforestartdevserver) for more details.

## rsbuild.onAfterStartDevServer

> Provides the same functionality as the [onAfterStartDevServer](/plugins/dev/hooks.md#onafterstartdevserver) plugin hook.

import OnAfterStartDevServer from '@en/shared/onAfterStartDevServer.mdx';

<OnAfterStartDevServer />

* **Example:**

```ts
rsbuild.onAfterStartDevServer(({ port, routes }) => {
  console.log('this port is: ', port);
  console.log('this routes is: ', routes);
});
```

## rsbuild.onCloseDevServer

> Provides the same functionality as the [onCloseDevServer](/plugins/dev/hooks.md#onclosedevserver) plugin hook.

import OnCloseDevServer from '@en/shared/onCloseDevServer.mdx';

<OnCloseDevServer />

* **Example:**

```ts
rsbuild.onCloseDevServer(async () => {
  console.log('close dev server!');
});
```

## rsbuild.onBeforeStartProdServer

> Provides the same functionality as the [onBeforeStartProdServer](/plugins/dev/hooks.md#onbeforestartprodserver) plugin hook.

import OnBeforeStartProdServer from '@en/shared/onBeforeStartProdServer.mdx';

<OnBeforeStartProdServer />

* **Example:**

```ts
rsbuild.onBeforeStartProdServer(() => {
  console.log('before start!');
});
```

## rsbuild.onAfterStartProdServer

> Provides the same functionality as the [onAfterStartProdServer](/plugins/dev/hooks.md#onafterstartprodserver) plugin hook.

import OnAfterStartProdServer from '@en/shared/onAfterStartProdServer.mdx';

<OnAfterStartProdServer />

* **Example:**

```ts
rsbuild.onAfterStartProdServer(({ port, routes }) => {
  console.log('this port is: ', port);
  console.log('this routes is: ', routes);
});
```

## rsbuild.onBeforeDevCompile

> Provides the same functionality as the [onBeforeDevCompile](/plugins/dev/hooks.md#onbeforedevcompile) plugin hook.

import OnBeforeDevCompile from '@en/shared/onBeforeDevCompile.mdx';

<OnBeforeDevCompile />

* **Example:**

```ts
rsbuild.onBeforeDevCompile(({ bundlerConfigs }) => {
  console.log('the Rspack configs are ', bundlerConfigs);
});
```

## rsbuild.onAfterDevCompile

> Provides the same functionality as the [onAfterDevCompile](/plugins/dev/hooks.md#onafterdevcompile) plugin hook.

import OnAfterDevCompile from '@en/shared/onAfterDevCompile.mdx';

<OnAfterDevCompile />

* **Example:**

```ts
rsbuild.onAfterDevCompile(({ isFirstCompile }) => {
  if (isFirstCompile) {
    console.log('first compile!');
  } else {
    console.log('re-compile!');
  }
});
```

## rsbuild.onBeforeEnvironmentCompile

> Provides the same functionality as the [onBeforeEnvironmentCompile](/plugins/dev/hooks.md#onbeforeenvironmentcompile) plugin hook.

* **Version:** Added in v1.5.7
* **Example:**

```ts
rsbuild.onBeforeEnvironmentCompile(({ bundlerConfig, environment }) => {
  console.log(
    `the bundler config for the ${environment.name} is `,
    bundlerConfig,
  );
});
```

## rsbuild.onAfterEnvironmentCompile

> Provides the same functionality as the [onAfterEnvironmentCompile](/plugins/dev/hooks.md#onafterenvironmentcompile) plugin hook.

* **Version:** Added in v1.5.7
* **Example:**

```ts
rsbuild.onAfterEnvironmentCompile(({ isFirstCompile, stats }) => {
  console.log(stats?.toJson(), isFirstCompile);
});
```

## rsbuild.onExit

> Provides the same functionality as the [onExit](/plugins/dev/hooks.md#onexit) plugin hook.

import OnExit from '@en/shared/onExit.mdx';

<OnExit />

* **Example:**

```ts
rsbuild.onExit(({ exitCode }) => {
  console.log('exit: ', exitCode);
});
```

## rsbuild.getRsbuildConfig

> Provides the same functionality as the [getRsbuildConfig](/plugins/dev/core.md#apigetrsbuildconfig) plugin API.

import GetRsbuildConfig from '@en/shared/getRsbuildConfig.mdx';

<GetRsbuildConfig />

* **Example:**

```ts
rsbuild.onBeforeBuild(() => {
  const config = rsbuild.getRsbuildConfig();
  console.log(config.html?.title);
});
```

## rsbuild.getNormalizedConfig

> Provides the same functionality as the [getNormalizedConfig](/plugins/dev/core.md#apigetnormalizedconfig) plugin API.

import GetNormalizedConfig from '@en/shared/getNormalizedConfig.mdx';

<GetNormalizedConfig />

* **Example:**

```ts
rsbuild.onBeforeBuild(() => {
  const config = rsbuild.getNormalizedConfig();
  console.log(config.html.title);
});
```

## rsbuild.expose

> Provides the same functionality as the [expose](/plugins/dev/core.md#apiexpose) plugin API.

* **Version:** Added in v1.5.0
* **Example:**

```ts
rsbuild.expose('my-id', {
  value: 1,
  double: (val: number) => val * 2,
});
```

## rsbuild.modifyRsbuildConfig

> Provides the same functionality as the [modifyRsbuildConfig](/plugins/dev/hooks.md#modifyrsbuildconfig) plugin API.

* **Version:** Added in v1.5.0
* **Example:**

```ts
rsbuild.modifyRsbuildConfig((config) => {
  config.html ||= {};
  config.html.title = 'My Default Title';
});
```

## rsbuild.modifyEnvironmentConfig

> Provides the same functionality as the [modifyEnvironmentConfig](/plugins/dev/hooks.md#modifyenvironmentconfig) plugin API.

* **Version:** Added in v1.5.0
* **Example:**

```ts
rsbuild.modifyEnvironmentConfig((config, { name }) => {
  if (name !== 'web') {
    return config;
  }
  config.html.title = 'My Default Title';
});
```

---

# Source: https://rsbuild.dev/guide/basic/json-files.md

# JSON

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

## JSON file

You can import JSON files directly in JavaScript files.

### Example

```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

Rsbuild also supports importing JSON files using named imports:

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

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

## YAML file

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

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

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

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

### Example

```yaml title="example.yaml"
---
hello: world
foo:
  bar: baz
```

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

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

## TOML file

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

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

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

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

### Example

```toml title="example.toml"
hello = "world"

[foo]
bar = "baz"
```

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

console.log(example.hello); // 'world';
console.log(example.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 `@rsbuild/core` package is installed, you can reference the [preset types](/guide/basic/typescript.md#preset-types) provided by `@rsbuild/core`:

```ts title="src/env.d.ts"
/// <reference types="@rsbuild/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;
}
```

---

# Source: https://rsbuild.dev/config/dev/lazy-compilation.md

# dev.lazyCompilation

* **Type:**

```ts
type LazyCompilationOptions =
  | boolean
  | {
      /**
       * Enable lazy compilation for entries.
       */
      entries?: boolean;
      /**
       * Enable lazy compilation for dynamic imports.
       */
      imports?: boolean;
      /**
       * Specify which imported modules should be lazily compiled.
       */
      test?: RegExp | ((m: Module) => boolean);
      /**
       * The path to a custom runtime code that overrides the default lazy compilation client.
       */
      client?: string;
      /**
       * Tells the client the server URL that needs to be requested.
       */
      serverUrl?: string;
      /**
       * Customize the prefix used for lazy compilation endpoint.
       * @default "/lazy-compilation-using-"
       */
      prefix?: string;
    };
```

* **Default:**

```js
const defaultOptions = {
  imports: true,
  entries: false,
};
```

Enable lazy compilation (compilation on demand), implemented based on Rspack's [lazy compilation](https://rspack.rs/guide/features/lazy-compilation) feature.

## Introduction

Although Rspack itself has good performance, the overall build time can still be less than ideal when building applications with a large number of modules. This is because the modules in the application need to be compiled by various loaders, such as `postcss-loader`, `sass-loader`, `vue-loader`, etc., which introduce additional compilation overhead.

Lazy compilation is an effective strategy to improve the startup performance of the development phase. Instead of compiling all modules at initialization, it compiles modules on demand as they are needed. This means that developers can quickly see the application running when starting the dev server, and build the required modules in batches. By compiling on demand, unnecessary compilation time can be reduced. As the project scales up, compilation time does not significantly increase, which greatly enhances the development experience.

:::tip
Lazy compilation is only effective for dev builds and does not affect production builds.
:::

## Example

### Enable lazy compilation

By default, Rsbuild already enables `imports` option, which means lazy compilation of dynamic imported modules.

To enable full lazy compilation functionality, set `lazyCompilation` option to `true`:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    lazyCompilation: true,
  },
};
```

This is equivalent to the following configuration:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    lazyCompilation: {
      imports: true,
      // If there is only one entry, Rsbuild will not enable the entries option by default
      entries: true,
    },
  },
};
```

### Disable lazy compilation

To disable lazy compilation, set `lazyCompilation` to `false`:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    lazyCompilation: false,
  },
};
```

### Entry modules

Use `lazyCompilation.entries` to control whether to lazily compile entry modules:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    lazyCompilation: {
      entries: true,
    },
  },
};
```

With the `entries` option enabled, Rsbuild will not compile all pages when you start the dev server. Instead, it will only compile a specific page when you visit it.

When lazily compiling entry modules, please note:

* It only applies to multi-page applications (MPA) and does not optimize single-page applications (SPA).
* When you visit a page, you need to wait for the page to finish compiling before you can see its content.

### Async modules

Use `lazyCompilation.imports` to control whether to lazily compile [dynamic imported](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) modules.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    lazyCompilation: {
      imports: true,
    },
  },
};
```

When the `imports` option is enabled, all async modules will only be compiled when requested. If your project is a single-page application (SPA) and you have split the routes using dynamic import, this will significantly speed up the startup time.

### Server URL

Use [lazyCompilation.serverUrl](https://rspack.rs/config/experiments#lazycompilationserverurl) to tell the client the server URL that needs to be requested.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    lazyCompilation: {
      serverUrl: 'http://localhost:<port>',
    },
  },
};
```

:::tip
Rsbuild will replace the `<port>` placeholder with the actual port number the server is listening on.
:::

## Version history

| Version | Changes                                                                   |
| ------- | ------------------------------------------------------------------------- |
| v1.3.0  | Added this option                                                         |
| v1.5.0  | Changed default value from `false` to `{ imports: true, entries: false }` |

---

# Source: https://rsbuild.dev/config/output/legal-comments.md

# output.legalComments

* **Type:** `'linked' | 'inline' | 'none'`
* **Default:** `'linked'`

Controls how legal comments are handled in the build output.

## What are legal comments?

A "legal comment" is any statement-level comment in JS or rule-level comment in CSS that contains @license or @preserve, or that starts with //! or /\*!. These comments are preserved in output files by default since that follows the intent of the original authors of the code.

For example, the `LICENSE` comment in React:

```js
/**
 * @license React
 * react.production.js
 *
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */
```

## Optional values

You can control how legal comments are handled using these options:

### `linked`

Extracts all legal comments to `*.LICENSE.txt` files and links to them with a comment.

```js title="rsbuild.config.js"
export default {
  output: {
    legalComments: 'linked',
  },
};
```

`.LICENSE.txt` files are not loaded by the page, so they will not affect the page's performance.

### `inline`

Preserves all legal comments in their original position. This may increase the size of the output bundles.

```js title="rsbuild.config.js"
export default {
  output: {
    legalComments: 'inline',
  },
};
```

### `none`

Removes all legal comments.

```js title="rsbuild.config.js"
export default {
  output: {
    legalComments: 'none',
  },
};
```

:::tip
Removing license comments may violate the terms of some software licenses. Please ensure you have the right to remove these comments before using this option.
:::

---

# Source: https://rsbuild.dev/config/tools/lightningcss-loader.md

# tools.lightningcssLoader

* **Type:** `Rspack.LightningcssLoaderOptions | Function | boolean`
* **Default:**

```ts
const defaultOptions = {
  errorRecovery: true,
  // use current project's browserslist config
  targets: browserslist,
  // minify is enabled when output.injectStyles is true and in production mode
  minify: config.mode === 'production' && config.output.injectStyles,
};
```

You can set the options for [builtin:lightningcss-loader](https://rspack.rs/guide/features/builtin-lightningcss-loader) through `tools.lightningcssLoader`.

## Object type

When `tools.lightningcssLoader` is an object, it will be merged with the default configuration using `Object.assign`.

For example, you can disable the addition of vendor prefixes through `tools.lightningcssLoader.exclude`. In this case, you can use PostCSS's autoprefixer plugin to add vendor prefixes.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    lightningcssLoader: {
      exclude: {
        vendorPrefixes: true,
      },
    },
  },
};
```

## Function type

When `tools.lightningcssLoader` is a function, the default options will be passed in as the first parameter. You can directly modify this object or return a new object as the final options to be used. For example:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    lightningcssLoader: (config) => {
      config.exclude = {
        vendorPrefixes: true,
      };
      return config;
    },
  },
};
```

## Disable loader

Set `tools.lightningcssLoader` to `false` to disable the built-in `lightningcss-loader` in Rsbuild:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    lightningcssLoader: false,
  },
};
```

:::tip
Set `tools.lightningcssLoader` to `false` only disables the `lightningcss-loader`. If you need to disable the full functionality of Lightning CSS, please refer to [Disabling Lightning CSS](/guide/styling/css-usage.md#disabling-lightning-css).
:::

---

# Source: https://rsbuild.dev/config/dev/live-reload.md

# dev.liveReload

* **Type:** `boolean`
* **Default:** `true`

Whether to reload the page when source files are changed.

By default, Rsbuild uses HMR as the preferred method to update modules. If HMR is disabled or cannot be used in certain scenarios, it will automatically fallback to liveReload.

Please refer to [Hot Module Replacement](/guide/advanced/hmr.md) for more information.

## Disabling live reload

To disable live reload, set both `dev.hmr` and `dev.liveReload` to `false`. Then, no WebSocket requests will be made to the dev server on the page, and the page will not automatically refresh when files change.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    hmr: false,
    liveReload: false,
  },
};
```

---

# Source: https://rsbuild.dev/config/log-level.md

# logLevel

* **Type:** `'info' | 'warn' | 'error' | 'silent'`
* **Default:** `'info'`
* **Version:** `>= 1.4.0`

Sets the Rsbuild log level. Defaults to `info`.

:::tip
This option also affects Rsbuild's log output in the browser. You can override this behavior through the [client.logLevel](/config/dev/client.md#loglevel) option.
:::

## Example

When `logLevel` is set to `warn`, Rsbuild only outputs warning and error logs:

```ts title="rsbuild.config.ts"
export default {
  logLevel: 'warn',
};
```

When `logLevel` is set to `error`, Rsbuild only outputs error logs:

```ts title="rsbuild.config.ts"
export default {
  logLevel: 'error',
};
```

## Optional values

* `info`: Output all logs.
* `warn`: Output warning and error logs.
* `error`: Output error logs.
* `silent`: Do not output any logs.

::: note
In [debug mode](/guide/debug/debug-mode.md), Rsbuild always outputs all logs.
:::

## Limitations

Rsbuild currently cannot set different log levels per instance because all instances share a global [logger](/api/javascript-api/core.md#logger).

---

# Source: https://rsbuild.dev/config/resolve/main-fields.md

# resolve.mainFields

* **Type:** `string[]`
* **Version:** `>= 1.5.9`

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.

:::tip
`resolve.mainFields` is provided by Rspack, see [Rspack - resolve.mainFields](https://rspack.rs/config/resolve#resolvemainfields) to learn more.
:::

## Default values

* If [output.target](/config/output/target.md) is `'web'`, `'web-worker'`, or not specified, the default value is `["browser", "module", "main"]`.
* If [output.target](/config/output/target.md) is `'node'`, the default value is `["module", "main"]`.

## Basic example

The value of `resolve.mainFields` overrides the default value of Rsbuild:

```js title="rsbuild.config.ts"
export default {
  resolve: {
    mainFields: ['custom', 'module', 'main'],
  },
};
```

## Multi-environments

Configure different `mainFields` for different [environments](/config/environments.md):

```js title="rsbuild.config.ts"
export default {
  environments: {
    web: {
      resolve: {
        mainFields: ['custom', 'browser', 'module', 'main'],
      },
    },
    node: {
      resolve: {
        mainFields: ['custom', 'module', 'main'],
      },
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/output/manifest.md

# output.manifest

* **Type:** `string | boolean`
* **Default:** `false`

Configure how to generate the manifest file.

* `true`: Generate a manifest file named `manifest.json` in the output directory.
* `false`: Do not generate the manifest file.
* `string`: Generate a manifest file with the specified filename or path.
* `object`: Generate a manifest file with the specified options.

The manifest file contains information about all assets and the mapping between [entry modules](/config/source/entry.md) and assets.

## Basic example

Enable the asset manifest:

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

After building, Rsbuild will generate a `dist/manifest.json` file:

```json title="dist/manifest.json"
{
  "allFiles": [
    "/static/css/index.[hash].css",
    "/static/js/index.[hash].js",
    "/static/images/logo.[hash].png",
    "/index.html"
  ],
  "entries": {
    "index": {
      "initial": {
        "js": ["/static/js/index.[hash].js"],
        "css": ["/static/css/index.[hash].css"]
      },
      "assets": ["/static/images/logo.[hash].png"],
      "html": ["/index.html"]
    }
  }
}
```

## Manifest structure

The manifest file will be output with the following structure by default:

```ts
type FilePath = string;

type ManifestList = {
  /**
   * A flat list of all emitted asset files.
   */
  allFiles: FilePath[];
  /**
   * Maps each entry name to its associated output files.
   */
  entries: {
    [entryName: string]: {
      /**
       * Files that are required during the initial load of the entry.
       */
      initial?: {
        /** Initial JavaScript files for this entry. */
        js?: FilePath[];
        /** Initial CSS files for this entry. */
        css?: FilePath[];
      };
      /**
       * Files that may be loaded asynchronously.
       * Usually code-split chunks or lazily loaded chunks.
       */
      async?: {
        /** Async JavaScript files for this entry. */
        js?: FilePath[];
        /** Async CSS files for this entry. */
        css?: FilePath[];
      };
      /** HTML files generated for this entry, if any. */
      html?: FilePath[];
      /**
       * Additional assets associated with this entry.
       * For example images、fonts、source maps and other non JS or CSS files.
       */
      assets?: FilePath[];
    };
    /**
     * Subresource Integrity (SRI) hashes for emitted assets.
     * The key is the asset file path, and the value is its integrity hash.
     * This field is available only when the `security.sri` option is enabled.
     */
    integrity: Record<string, string>;
  };
};
```

## Access via hooks

You can access the generated manifest data through Rsbuild's [hooks](/plugins/dev/hooks.md) and [Environment API](/api/javascript-api/environment-api.md).

For example:

```ts
api.onAfterBuild(({ environments }) => {
  console.log(environments.web.manifest);
});
```

> See [Environment API - manifest](/api/javascript-api/environment-api.md#manifest) for more details.

## SRI

When the [`security.sri`](/config/security/sri.md) option is enabled, the manifest file includes an `integrity` field that stores the SRI hash for assets that support Subresource Integrity, such as JavaScript and CSS files.

```ts title="rsbuild.config.ts"
export default {
  security: {
    sri: {
      enable: 'auto',
    },
  },
  output: {
    manifest: true,
  },
};
```

```json title="dist/manifest.json"
{
  "allFiles": ["/static/js/index.[hash].js", "/index.html"],
  "integrity": {
    "/static/js/index.[hash].js": "sha384-[sri-hash]"
  }
}
```

## Options

`output.manifest` can be an object, here are all the options:

### filename

* **Type:** `string`
* **Default:** `'manifest.json'`

Specify the name or path of the manifest file.

`filename` can be a path relative to the `dist` directory, for example, output to `dist/static/my-manifest.json`:

```ts title="rsbuild.config.ts"
export default {
  output: {
    manifest: {
      filename: './static/my-manifest.json',
    },
  },
};
```

This can be simplified as:

```ts title="rsbuild.config.ts"
export default {
  output: {
    manifest: './static/my-manifest.json',
  },
};
```

### generate

* **Type:**

```ts
type ManifestGenerate = (params: {
  files: FileDescriptor[];
  manifestData: ManifestData;
}) => Record<string, unknown>;
```

* **Default:** `undefined`
* **Version:** `>= 1.2.0`

With the `manifest.generate` function, you can customize the content of the manifest file. The function receives the following parameters:

* `files`: The description information of all output files.
* `manifestData`: The default manifest data.

For example, only keep the `allAssets` field:

```ts title="rsbuild.config.ts"
export default {
  output: {
    manifest: {
      generate: ({ manifestData }) => {
        return {
          allAssets: manifestData.allFiles,
        };
      },
    },
  },
};
```

You can also customize the manifest file content based on `files`. The `files` structure:

```ts
interface FileDescriptor {
  name: string;
  path: string;
  isAsset: boolean;
  isChunk: boolean;
  isInitial: boolean;
  isModuleAsset: boolean;
  chunk?: import('@rspack/core').Chunk;
}
```

Here is an example of `files`:

```ts
const files = [
  {
    name: 'index.js',
    path: '/static/js/index.[hash].js',
    isAsset: false,
    isChunk: true,
    isInitial: true,
    isModuleAsset: false,
    chunk: {
      // Chunk info...
    },
  },
  {
    name: 'index.html',
    path: '/index.html',
    isAsset: true,
    isChunk: false,
    isInitial: false,
    isModuleAsset: false,
  },
];
```

### prefix

* **Type:** `boolean`
* **Default:** `true`

Controls whether the generated manifest includes the static asset prefix in file paths. The prefix is taken from [dev.assetPrefix](/config/dev/asset-prefix.md) and [output.assetPrefix](/config/output/asset-prefix.md).

When `prefix` is set to `true` (the default), the manifest will include the full asset prefix.

```ts title="rsbuild.config.ts"
export default {
  output: {
    assetPrefix: 'https://example.com/',
    manifest: true,
  },
};
```

Example of the generated manifest:

```json title="dist/manifest.json"
{
  "allFiles": [
    "https://example.com/static/js/index.[hash].js",
    "https://example.com/index.html"
  ],
  "entries": {
    "index": {
      "initial": {
        "js": ["https://example.com/static/js/index.[hash].js"]
      }
    }
  }
}
```

If `prefix` is set to `false`, the manifest will keep the file paths relative and no asset prefix will be added.

```ts title="rsbuild.config.ts"
export default {
  output: {
    assetPrefix: 'https://example.com/',
    manifest: {
      prefix: false,
    },
  },
};
```

Example of the generated manifest:

```json title="dist/manifest.json"
{
  "allFiles": ["static/js/index.[hash].js", "index.html"],
  "entries": {
    "index": {
      "initial": {
        "js": ["static/js/index.[hash].js"]
      }
    }
  }
}
```

### filter

* **Type:**

```ts
type ManifestFilter = (file: FileDescriptor) => boolean;
```

* **Default:** `file => !file.name.endsWith('.LICENSE.txt')`
* **Version:** `>= 1.2.0`

Allows you to filter the files included in the manifest. The function receives a `file` parameter and returns `true` to keep the file, or `false` to exclude it.

By default, `*.LICENSE.txt` files are excluded from the manifest, as these license files are only used to declare open source licenses and are not used at runtime.

For example, to only keep `*.js` files:

```ts title="rsbuild.config.ts"
export default {
  output: {
    manifest: {
      filter: (file) => file.name.endsWith('.js'),
    },
  },
};
```

The generated manifest file will only include `*.js` files:

```json title="dist/manifest.json"
{
  "allFiles": ["/static/js/index.[hash].js"],
  "entries": {
    "index": {
      "initial": {
        "js": ["/static/js/index.[hash].js"]
      }
    }
  }
}
```

Or include all files:

```ts title="rsbuild.config.ts"
export default {
  output: {
    manifest: {
      filter: () => true,
    },
  },
};
```

## Multiple environments

When using [environments](/config/environments.md) with multiple environments, please specify a unique `manifest.filename` value for each environment to prevent manifest files from different environments from overwriting each other.

For example, use the default `manifest.json` for the `web` environment and use `manifest-node.json` for the `node` environment:

```ts title="rsbuild.config.ts"
export default {
  environments: {
    web: {
      output: {
        manifest: true,
      },
    },
    node: {
      output: {
        target: 'node',
        manifest: {
          filename: 'manifest-node.json',
        },
      },
    },
  },
};
```

You can also choose to generate the manifest file only for specific environments:

```ts title="rsbuild.config.ts"
export default {
  environments: {
    web: {
      output: {
        manifest: true,
      },
    },
    node: {
      output: {
        target: 'node',
      },
    },
  },
};
```

## Version history

| Version | Changes                 |
| ------- | ----------------------- |
| v1.6.8  | Added `integrity` field |
| v1.6.12 | Added `prefix` option   |

---

# Source: https://rsbuild.dev/config/html/meta.md

# html.meta

* **Type:** `Object | Function`
* **Default:**

```ts
const defaultMeta = {
  // <meta charset="utf-8" />
  charset: {
    charset: 'utf-8',
  },
  // <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  viewport: 'width=device-width, initial-scale=1.0',
};
```

Configures the `<meta>` tags of the HTML.

:::tip
If the HTML template used in the current project already contains the charset or viewport meta tags, then the tags in the HTML template take precedence.
:::

## String type

* **Type:**

```ts
type MetaOptions = {
  [name: string]: string;
};
```

When the `value` of a `meta` object is a string, the `key` of the object is automatically mapped to `name`, and the `value` is mapped to `content`.

To set a description, for example:

```ts title="rsbuild.config.ts"
export default {
  html: {
    meta: {
      description: 'a description of the page',
    },
  },
};
```

The generated `meta` tag in HTML is:

```html
<meta name="description" content="a description of the page" />
```

## Object type

* **Type:**

```ts
type MetaOptions = {
  [name: string]:
    | string
    | false
    | {
        [attr: string]: string | boolean;
      };
};
```

When the `value` of a `meta` object is an object, the `key: value` of the object is mapped to the attribute of the `meta` tag.

In this case, the `name` and `content` properties will not be set by default.

### Charset tag

To generate `charset` tag, for example:

```ts title="rsbuild.config.ts"
export default {
  html: {
    meta: {
      charset: {
        charset: 'utf-8',
      },
    },
  },
};
```

The `meta` tag in HTML is:

```html
<meta charset="utf-8" />
```

### Open Graph tags

Generate [Open Graph tags](https://ogp.me/):

```ts title="rsbuild.config.ts"
export default {
  html: {
    meta: {
      'og:title': {
        property: 'og:title',
        content: 'Example Title',
      },
      'og:image': {
        property: 'og:image',
        content: 'https://example.com/og.png',
      },
    },
  },
};
```

The generated `meta` tags in the final HTML will look like:

```html
<meta property="og:title" content="Example Title" />
<meta property="og:image" content="https://example.com/og.png" />
```

## Function usage

* **Type:**

```ts
type MetaFunction = ({
  value: MetaOptions,
  entryName: string,
}) => MetaOptions | void;
```

When `html.meta` is of type `Function`, the function receives an object as an argument with the following properties:

* `value`: the default meta configuration of Rsbuild.
* `entryName`: the name of the current entry.

You can directly modify the configuration object and not return anything, or you can return an object as the final configuration.

For example, you can directly modify the built-in `meta` configuration object:

```ts title="rsbuild.config.ts"
export default {
  html: {
    meta({ value }) {
      value.description = 'this is my page';
      return value;
    },
  },
};
```

In the MPA (Multi-Page Application) scenario, you can return different `meta` configurations based on the entry name, thus generating different `meta` tags for each page:

```ts title="rsbuild.config.ts"
export default {
  html: {
    meta({ entryName }) {
      switch (entryName) {
        case 'foo':
          return {
            description: 'this is foo page',
          };
        case 'bar':
          return {
            description: 'this is bar page',
          };
        default:
          return {
            description: 'this is other pages',
          };
      }
    },
  },
};
```

## Remove default value

Setting the `value` of the `meta` object to `false` means the meta tag will not be generated.

To remove the `viewport`, for example:

```ts title="rsbuild.config.ts"
export default {
  html: {
    meta: {
      viewport: false,
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/server/middleware-mode.md

# server.middlewareMode

* **Type:** `boolean`
* **Default:** `false`
* **Version:** `>= 1.2.12`

Whether to create Rsbuild's server in middleware mode, which is useful for integrating with other servers.

When this option is enabled, Rsbuild will not create an HTTP server. This option is usually only needed when using the [JavaScript API](/api/start/index.md) of Rsbuild.

## Examples

### Enable middleware mode

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

const rsbuild = await createRsbuild({
  config: {
    server: {
      middlewareMode: true,
    },
  },
});
```

### Integrate with a custom server

A typical use case is that you want to integrate the Rsbuild server into a custom server. You can achieve this by combining `server.middlewareMode` and [rsbuild.createDevServer](/api/javascript-api/instance.md#rsbuildcreatedevserver).

```ts
import { createRsbuild } from '@rsbuild/core';
import express from 'express';

async function startDevServer() {
  // Initialize Rsbuild in middleware mode
  const rsbuild = await createRsbuild({
    config: {
      server: {
        middlewareMode: true,
      },
    },
  });

  const app = express();

  // Create Rsbuild dev server instance
  const rsbuildServer = await rsbuild.createDevServer();

  // Apply Rsbuild's built-in middleware
  app.use(rsbuildServer.middlewares);
}
```

> See [Integrate with custom server](/api/javascript-api/dev-server-api.md#integrate-with-custom-server) for more details.

---

# Source: https://rsbuild.dev/config/output/minify.md

# output.minify

* **Type:**

```ts
type Minify =
  | boolean
  | {
      js?: boolean;
      jsOptions?: Rspack.SwcJsMinimizerRspackPluginOptions;
      css?: boolean;
      cssOptions?: Rspack.LightningcssMinimizerRspackPluginOptions;
    };
```

* **Default:** `true`

Controls code minification in production mode and configures minimizer options.

JavaScript and CSS code are automatically minified in production mode to improve page performance. To disable minification entirely, set `minify` to `false`. Control specific minification behavior using the detailed `minify` options:

:::tip
Rsbuild uses [SWC](/guide/configuration/swc.md) to minify JavaScript code and [Lightning CSS](/guide/styling/css-usage.md#lightning-css) to minify CSS code by default.
:::

## Example

### Disable minification

Set `minify` to `false` to disable JavaScript and CSS code minification:

```ts title="rsbuild.config.ts"
export default {
  output: {
    minify: false,
  },
};
```

:::tip
This helps with debugging and troubleshooting. We don't recommend disabling code minification in production builds, as it significantly impacts page performance.
:::

## Options

### minify.js

* **Type:** `boolean | 'always'`
* **Default:** `true`

Whether to enable minification for JavaScript bundles:

* `true`: Enabled in production mode.
* `false`: Disabled in all modes.
* `'always'`: Enabled in all modes.

For example, to disable JavaScript minification:

```ts title="rsbuild.config.ts"
export default {
  output: {
    minify: {
      js: false,
    },
  },
};
```

To enable JavaScript minification in both development and production mode:

```ts title="rsbuild.config.ts"
export default {
  output: {
    minify: {
      js: 'always',
    },
  },
};
```

### minify.jsOptions

* **Type:** `Rspack.SwcJsMinimizerRspackPluginOptions`
* **Default:** `{}`

`output.minify.jsOptions` configures SWC's minification options. See [SwcJsMinimizerRspackPlugin](https://rspack.rs/plugins/rspack/swc-js-minimizer-rspack-plugin) for detailed configuration options.

For example, disable the mangle feature:

```ts title="rsbuild.config.ts"
export default {
  output: {
    minify: {
      jsOptions: {
        minimizerOptions: {
          mangle: false,
        },
      },
    },
  },
};
```

> Refer to [Configure SWC](/guide/configuration/swc.md) for more details.

### minify.css

* **Type:** `boolean | 'always'`
* **Default:** `true`

Whether to enable minification for CSS bundles:

* `true`: Enabled in production mode.
* `false`: Disabled in all modes.
* `'always'`: Enabled in all modes.

For example, disable CSS minification:

```ts title="rsbuild.config.ts"
export default {
  output: {
    minify: {
      css: false,
    },
  },
};
```

Enable CSS minification in both development and production mode:

```ts title="rsbuild.config.ts"
export default {
  output: {
    minify: {
      css: 'always',
    },
  },
};
```

### minify.cssOptions

* **Type:** `Rspack.LightningcssMinimizerRspackPluginOptions`
* **Default:** inherit from [tools.lightningcssLoader](/config/tools/lightningcss-loader.md)

`output.minify.cssOptions` configures Lightning CSS's minification options. See [LightningCssMinimizerRspackPlugin Documentation](https://rspack.rs/plugins/rspack/lightning-css-minimizer-rspack-plugin) for detailed configuration options.

For example, disable error recovery:

```ts title="rsbuild.config.ts"
export default {
  output: {
    minify: {
      cssOptions: {
        minimizerOptions: {
          errorRecovery: false,
        },
      },
    },
  },
};
```

:::tip
When you configure options in [tools.lightningcssLoader](/config/tools/lightningcss-loader.md), `output.minify.cssOptions` will automatically inherit these options, ensuring that CSS code transformation behavior in the development build is consistent with the production build.
:::

## Switching minifier

### JS minifier

If the default SWC minifier doesn't meet your needs, you can switch to other minifiers using the [tools.bundlerChain](/config/tools/bundler-chain.md) option.

For example, use [terser-webpack-plugin](https://github.com/terser/terser-webpack-plugin) to switch to Terser or esbuild.

* Use [terser](https://github.com/terser/terser) to minify JS code:

```ts title="rsbuild.config.ts"
import TerserPlugin from 'terser-webpack-plugin';

export default {
  tools: {
    bundlerChain(chain, { CHAIN_ID }) {
      chain.optimization.minimizer(CHAIN_ID.MINIMIZER.JS).use(TerserPlugin, [
        {
          // options
        },
      ]);
    },
  },
};
```

* Use [esbuild](https://github.com/evanw/esbuild) to minify JS code, you need to install the `esbuild` package and set `esbuildMinify`:

```ts title="rsbuild.config.ts"
import TerserPlugin from 'terser-webpack-plugin';

export default {
  tools: {
    bundlerChain(chain, { CHAIN_ID }) {
      chain.optimization.minimizer(CHAIN_ID.MINIMIZER.JS).use(TerserPlugin, [
        {
          minify: TerserPlugin.esbuildMinify,
        },
      ]);
    },
  },
};
```

:::tip
When using a custom JS minifier, the `minify.jsOptions` option will no longer take effect.
:::

---

# Source: https://rsbuild.dev/config/mode.md

# mode

* **Type:** `'production' | 'development' | 'none'`
* **Version:** `>= 1.0.0`

Sets the Rsbuild build mode. Each mode applies different defaults and optimizations; for example, `production` minifies code by default.

The Rsbuild `mode` value is also passed to Rspack's [mode](https://rspack.rs/config/mode) configuration.

:::tip
The `mode` value does not change which `.env` file loads because `.env` files resolve before the Rsbuild config file.

Use the `--env-mode` option in the Rsbuild CLI to specify the env mode. See ["Env mode"](/guide/advanced/env-vars.md#env-mode) for details.
:::

## Default values

The default value of `mode` depends on the `process.env.NODE_ENV` environment variable:

* If `NODE_ENV` is `production`, the default value is `production`.
* If `NODE_ENV` is `development`, the default value is `development`.
* If `NODE_ENV` has any other value, the default value is `none`.

If you set `mode`, the `NODE_ENV` value will be ignored.

```ts title="rsbuild.config.ts"
export default {
  mode: 'production',
};
```

### Command line

When using the Rsbuild CLI:

* `rsbuild dev` will set the default values of `NODE_ENV` and `mode` to `development`.
* `rsbuild build` and `rsbuild preview` will set the default values of `NODE_ENV` and `mode` to `production`.

### JavaScript API

When using the Rsbuild JavaScript API:

* [rsbuild.startDevServer](/api/javascript-api/instance.md#rsbuildstartdevserver) and [rsbuild.createDevServer](/api/javascript-api/instance.md#rsbuildcreatedevserver) will set the default values of `NODE_ENV` and `mode` to `development`.
* [rsbuild.build](/api/javascript-api/instance.md#rsbuildbuild) and [rsbuild.preview](/api/javascript-api/instance.md#rsbuildpreview) will set the default values of `NODE_ENV` and `mode` to `production`.

## Development mode

If `mode` is `development`:

* Enable HMR and register the [HotModuleReplacementPlugin](https://rspack.rs/plugins/webpack/hot-module-replacement-plugin).
* Generate JavaScript source maps, but do not generate CSS source maps. See [output.sourceMap](/config/output/source-map.md) for details.
* The `process.env.NODE_ENV` in the source code will be replaced with `'development'`.
* The `import.meta.env.MODE` in the source code will be replaced with `'development'`.
* The `import.meta.env.DEV` in the source code will be replaced with `true`.
* The `import.meta.env.PROD` in the source code will be replaced with `false`.
* Use [dev.assetPrefix](/config/dev/asset-prefix.md) as the URL prefix for static assets.

## Production mode

If `mode` is `production`:

* Enable JavaScript code minification and register the [SwcJsMinimizerRspackPlugin](https://rspack.rs/plugins/rspack/swc-js-minimizer-rspack-plugin).
* Enable CSS code minification and register the [LightningCssMinimizerRspackPlugin](https://rspack.rs/plugins/rspack/lightning-css-minimizer-rspack-plugin).
* JavaScript and CSS filenames include hash suffixes. See [output.filenameHash](/config/output/filename-hash.md).
* CSS Modules class names are shorter. See [cssModules.localIdentName](/config/output/css-modules.md#cssmoduleslocalidentname).
* JavaScript and CSS source maps are disabled. See [output.sourceMap](/config/output/source-map.md).
* The `process.env.NODE_ENV` in the source code will be replaced with `'production'`.
* The `import.meta.env.MODE` in the source code will be replaced with `'production'`.
* The `import.meta.env.DEV` in the source code will be replaced with `false`.
* The `import.meta.env.PROD` in the source code will be replaced with `true`.
* Use [output.assetPrefix](/config/output/asset-prefix.md) as the URL prefix for static assets.

## None mode

If `mode` is `none`:

* Do not enable any optimizations.
* The `process.env.NODE_ENV` in the source code will not be replaced.
* The `import.meta.env.MODE` in the source code will be replaced with `'none'`.
* The `import.meta.env.DEV` in the source code will be replaced with `false`.
* The `import.meta.env.PROD` in the source code will be replaced with `false`.
* Use [output.assetPrefix](/config/output/asset-prefix.md) as the URL prefix for static assets.

---

# Source: https://rsbuild.dev/guide/migration/modern-builder.md

# Modern.js Builder

This chapter introduces how to migrate a Modern.js Builder (or EdenX Builder) project to Rsbuild.

## Key differences

Rsbuild is the new version of Modern.js Builder, with the following key differences:

* Rsbuild has better performance. When using Rspack simultaneously, **the startup speed and build speed of Rsbuild are 1.5 to 2 times faster than Builder**.
* Rsbuild only supports Rspack as the bundler and no longer supports webpack.
* Rsbuild's CLI tool and dev server are more powerful and support more features.

## Installing dependencies

First, you need to replace the npm dependencies related to Builder with Rsbuild's dependencies.

import { PackageManagerTabs } from '@theme';

* Remove Builder's dependencies:

<PackageManagerTabs command="remove @modern-js/builder-cli @modern-js/builder-webpack-provider @modern-js/builder-rspack-provider" />

* Install Rsbuild's dependencies:

<PackageManagerTabs command="add @rsbuild/core -D" />

## Updating npm scripts

Next, you need to update the npm scripts in the package.json to Rsbuild's CLI commands.

```json title="package.json"
{
  "scripts": {
    "dev": "builder dev", // [!code --]
    "build": "builder build", // [!code --]
    "serve": "builder serve", // [!code --]
    "dev": "rsbuild dev", // [!code ++]
    "build": "rsbuild build", // [!code ++]
    "preview": "rsbuild preview" // [!code ++]
  }
}
```

## Modifying configuration files

* Rename `builder.config.ts` to `rsbuild.config.ts`.
* Change the import of the `defineConfig` method from `@modern-js/builder-cli` to `@rsbuild/core`.
* Change the `builderPlugins` field to `plugins`.

```ts title="rsbuild.config.ts"
import { defineConfig } from '@modern-js/builder-cli'; // [!code --]
import { defineConfig } from '@rsbuild/core'; // [!code ++]

export default defineConfig({
  builderPlugins: [], // [!code --]
  plugins: [], // [!code ++]
});
```

## Replacing plugins

Rsbuild and Builder have incompatible plugin systems, so you need to replace Builder's plugins with Rsbuild's plugins.

The following table shows the correspondence between Builder plugins and Rsbuild plugins:

| Builder                                  | Rsbuild                                                                                     |
| ---------------------------------------- | ------------------------------------------------------------------------------------------- |
| @modern-js/builder-plugin-vue            | [@rsbuild/plugin-vue](/plugins/list/plugin-vue.md)                                             |
| @modern-js/builder-plugin-vue2           | [@rsbuild/plugin-vue2](https://github.com/rstackjs/rsbuild-plugin-vue2)                     |
| @modern-js/builder-plugin-stylus         | [@rsbuild/plugin-stylus](/plugins/list/plugin-stylus.md)                                       |
| @modern-js/builder-plugin-node-polyfill  | [@rsbuild/plugin-node-polyfill](https://github.com/rstackjs/rsbuild-plugin-node-polyfill)   |
| @modern-js/builder-plugin-image-compress | [@rsbuild/plugin-image-compress](https://github.com/rstackjs/rsbuild-plugin-image-compress) |
| @modern-js/builder-plugin-swc            | Enabled by default, no need to use                                                          |
| @modern-js/builder-plugin-esbuild        | No longer supported                                                                         |

For example, if you were using `@modern-js/builder-plugin-vue`, you need to first install `@rsbuild/plugin-vue`, then import the plugin in `rsbuild.config.ts` and add it to the `plugins` field.

```ts title="rsbuild.config.ts"
import { builderPluginVue } from '@modern-js/builder-plugin-vue'; // [!code --]
import { pluginVue } from '@rsbuild/plugin-vue'; // [!code ++]

export default defineConfig({
  builderPlugins: [builderPluginVue()], // [!code --]
  plugins: [pluginVue()], // [!code ++]
});
```

## Add React-related plugins

Rsbuild is not coupled with any front-end UI framework. Therefore, if you are a React project, you need to manually add [React Plugin](/plugins/list/plugin-react.md):

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

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

If you are using SVGR in your current project, you also need to register [SVGR Plugin](/plugins/list/plugin-svgr.md):

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

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

If you are a user of other frameworks, you can refer to [Rsbuild Plugin List](/plugins/list/index.md) to select the corresponding framework plugin.

## Config migration

Most configs in Rsbuild and Builder are consistent, with only a few adjustments.

You can refer to the [Rsbuild options](/config/index.md) to view the configs of Rsbuild.

It is worth noting that, compared to Builder, **there are some differences in default values and behaviors in Rsbuild**:

* **Browserslist:** The default is minimum compatible with browsers that support [Native ES Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules), refer to [Default Browserslist](/guide/advanced/browserslist.md#default-browserslist).
* **HTML file output path:** default output to the root of the dist directory, refer to [Default Directory Structure](/guide/basic/output-files.md#default-directory-structure).
* **Polyfill injection method:** Inject on demand by default, refer to [output.polyfill](/config/output/polyfill.md).
* **TypeScript type check:** not enabled by default, you need to manually register the [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check).
* **Modify DevServer configuration:** Modify `dev` and `server` configuration instead.

## Validating results

After completing the above steps, you have migrated from Modern.js Builder to Rsbuild. You can now try starting the dev server by running the `npm run dev` command.

If you encounter any issues during the build process, please debug according to the error logs.

## 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 pull request 🤝.

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

---

# Source: https://rsbuild.dev/guide/advanced/module-federation.md

# Module Federation

Module Federation is an architectural pattern for decomposing JavaScript applications. Similar to server-side microservices, it lets multiple JavaScript applications (or micro-frontends) share code and resources.

The Rspack team works closely with the Module Federation maintainers to deliver first-class support.

## Use cases

Module Federation has several typical use cases, including:

* Allowing independent applications (called "micro-frontends" in micro-frontend architecture) to share modules without recompiling the entire application.
* Enabling different teams to work on different parts of the same application without needing to recompile the entire application.
* Providing 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 applications
* Improve application performance

## How to use

Module Federation (MF) currently offers multiple major versions; choose the one that fits your needs.

The key characteristics of each version are:

| Version | Description                                                            | Features                                                                                                                                                                                                                                                                  | Use Cases                                                 |
| ------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| MF v2.0 | Enhanced version of Module Federation, built on Module Federation v1.5 | - Provides additional out-of-the-box features such as dynamic TS type hints, Chrome DevTools, preloading, etc.<br />- Better suited for micro-frontend architecture supporting large-scale web applications <br />- Includes all features of Module Federation 1.5 <br /> | Projects that need MF 2.0's advanced capabilities         |
| MF v1.5 | Version built into Rspack                                              | - Supports module export, module loading, dependency sharing capabilities of Module Federation v1.0<br />- Added runtime plugin functionality, enabling users to extend the behavior and functionality of module federation <br />                                        | Projects that don't need the extra capabilities of MF 2.0 |

### Module Federation v2.0

[Module Federation 2.0](https://module-federation.io/blog/announcement.html) provides additional out-of-the-box features based on Module Federation, such as dynamic TS type hints, Chrome DevTools, Runtime plugins, and preloading, making it better suited for large-scale micro-frontend architectures.

You need to install the additional [@module-federation/rsbuild-plugin](https://npmjs.com/package/@module-federation/rsbuild-plugin) plugin to use Module Federation v2.0.

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

export default defineConfig({
  plugins: {
    pluginModuleFederation({
      name: 'remote',
     // other options
    }),
  },
});
```

Please refer to the [Module Federation v2.0 official documentation](https://module-federation.io/) for detailed usage.

### Module Federation v1.5

This is the version built into Rspack. In addition to supporting Module Federation v1.0's capabilities such as module export, module loading, and dependency sharing, it also adds runtime plugin functionality, letting you extend the behavior and functionality of module federation.

You can enable it through Rsbuild's [moduleFederation.options](/config/module-federation/options.md) without installing additional plugins.

```ts title="rsbuild.config.ts"
export default defineConfig({
  moduleFederation: {
    options: {
      name: 'remote',
      // other options
    },
  },
});
```

## Example repositories

Rsbuild provides Module Federation example projects you can explore:

* [Module Federation v2.0 Example](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/module-federation-enhanced)
* [Module Federation v1.5 Example](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/module-federation)

---

# Source: https://rsbuild.dev/config/output/module.md

# output.module

* **Type:** `boolean`
* **Default:** `false`

Whether to output JavaScript files in ES modules format.

:::tip

* This feature is currently experimental and only available when [output.target](/config/output/target.md) is `'web'` or `'node'`.
* If you need to build JavaScript libraries in ESM format, we recommend using [Rslib](https://rslib.rs), which is an out-of-the-box library development tool built on top of Rsbuild.

:::

## Web applications

When building a web application, Rsbuild generates the output in the IIFE format by default.

If you want to output ES Modules instead, set `output.module` to `true`:

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

:::tip
When `output.module` is enabled, Rsbuild automatically adds `type="module"` to the generated `<script>` tags, meaning [html.scriptLoading](/config/html/script-loading.md) is set to `module`.
:::

## Node.js applications

When building Node.js applications, Rsbuild outputs CommonJS format by default. You can set `output.module` to `true` to output ES modules format:

```ts title="rsbuild.config.ts"
export default {
  output: {
    target: 'node',
    module: true,
  },
};
```

### Running ESM bundles

To properly run ESM bundles in Node.js, you can choose either of the following approaches:

1. Set the `type` field in package.json to `'module'`:

```json title="package.json"
{
  "type": "module"
}
```

2. Change the output JavaScript file extension to `.mjs`:

```ts title="rsbuild.config.ts"
export default {
  output: {
    filename: {
      js: '[name].mjs',
    },
  },
};
```

## Version history

| Version | Changes                     |
| ------- | --------------------------- |
| v1.5.0  | Added this option           |
| v1.6.0  | Support for `target: 'web'` |

---

# Source: https://rsbuild.dev/config/html/mount-id.md

# html.mountId

* **Type:** `string`
* **Default:** `'root'`

By default, the `root` element is included in the HTML template for component mounting. The element id can be modified through `mountId`.

```html
<body>
  <div id="root"></div>
</body>
```

## Example

Set the `id` to `app`:

```ts title="rsbuild.config.ts"
export default {
  html: {
    mountId: 'app',
  },
};
```

After compilation:

```html
<body>
  <div id="app"></div>
</body>
```

## Notes

### Update relevant code

After modifying `mountId`, if there is logic in your code to obtain the `root` root node, please update the corresponding value:

```ts
const domNode = document.getElementById('root'); // [!code --]
const domNode = document.getElementById('app'); // [!code ++]

ReactDOM.createRoot(domNode).render(<App />);
```

### Custom templates

If you've customized the HTML template, please make sure that the template contains `<div id="<%= mountId %>"></div>`, otherwise the `mountId` config will not take effect.

---

# Source: https://rsbuild.dev/config/security/nonce.md

# security.nonce

* **Type:**

```ts
type Nonce = string;
```

* **Default:** `undefined`

Adds a `nonce` attribute to script resources injected into HTML. This lets the browser decide whether inline scripts with matching nonce values can be executed.

## What is nonce

The nonce mechanism is a key part of Content Security Policy (CSP) and enhances webpage security. It lets developers define a unique, random string (the nonce) for inline `<script>` and `<style>` tags within CSP.

When the browser parses inline scripts with a matching nonce, it allows them to run; otherwise, CSP blocks them. This effectively prevents potential Cross-Site Scripting (XSS) attacks. It's worth noting that a new nonce value should be generated each time the page is accessed.

For more information about nonce, you can refer to:

* [nonce - MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce)
* [webpack - Content Security Policies](https://webpack.js.org/guides/csp/)

## Example

Rsbuild does not enable `nonce` by default. You can define this value based on your needs:

```ts title="rsbuild.config.ts"
export default {
  security: {
    nonce: 'CSP_NONCE_PLACEHOLDER',
  },
};
```

Typically, you can define a placeholder value in the project, then have downstream servers such as Nginx, web servers, or gateways replace it with a random string.

## Scope of effect

The `security.nonce` config adds the nonce attribute to the following tags:

* All `<script>` tags generated by Rsbuild
* All `<style>` tags generated by Rsbuild
* All [`<link rel="preload" as="script">`](/config/performance/preload.md) tags generated by Rsbuild
* Dynamic `<script>` tags generated by Rspack (implemented by the [\_\_webpack\_nonce\_\_](https://rspack.rs/api/runtime-api/module-variables#__webpack_nonce__) variable)

For `<script>` or `<style>` tags that already exist in the HTML template file, Rsbuild will not modify them. You can directly add the `nonce` attribute in the template.

For `<script>` or `<style>` tags inserted dynamically via JavaScript, you also need to set the `nonce` attribute yourself.

---

# Source: https://rsbuild.dev/config/server/open.md

# server.open

* **Type:**

```ts
type Open =
  | boolean
  | string
  | string[]
  | {
      target?: string | string[];
      before?: () => Promise<void> | void;
    };
```

* **Default:** `undefined`

`server.open` configures which page URLs Rsbuild should automatically open in the browser after starting the server.

> You can also use the [--open](/guide/basic/cli.md#opening-page) option of Rsbuild CLI to open the pages. When using `server.open` and `--open` at the same time, `--open` takes precedence.

## Example

`server.open` can be set to the following values.

* Open the project's default preview page (`http://localhost:<port>`, or `http://<host>:<port>` if [server.host](/config/server/host.md) is configured):

```ts title="rsbuild.config.ts"
export default {
  server: {
    open: true,
  },
};
```

* Open the specified page:

```ts title="rsbuild.config.ts"
export default {
  server: {
    open: 'http://localhost:3000',
  },
};
```

* Open the specified path, equivalent to `http://localhost:<port>/home`:

```ts title="rsbuild.config.ts"
export default {
  server: {
    open: '/home',
  },
};
```

* Open multiple pages:

```ts title="rsbuild.config.ts"
export default {
  server: {
    open: ['/', '/about'],
  },
};
```

* Open a non-localhost URL (used with proxy):

```ts title="rsbuild.config.ts"
export default {
  server: {
    open: 'http://www.example.com',
  },
};
```

## Port placeholder

The port number that Rsbuild server listens on may change. For example, if the port is already in use, Rsbuild will automatically increment the port number until it finds an available port.

To avoid `server.open` becoming invalid due to port changes, you can use one of the following methods:

* Enable [server.strictPort](/config/server/strict-port.md).
* Use the `<port>` placeholder to refer to the current port number. Rsbuild will replace the placeholder with the actual port number it is listening on.

```ts title="rsbuild.config.ts"
export default {
  server: {
    open: 'http://localhost:<port>/home',
  },
};
```

## Specify browser

By default, Rsbuild opens pages in the system's default browser. You can specify which browser to use via the `BROWSER` environment variable.

### Browser name

Rsbuild uses the [open](https://github.com/sindresorhus/open) library to open browsers, and supports opening Chrome, Edge, and Firefox:

```bash
# Chrome
BROWSER=chrome npx rsbuild dev

# Edge
BROWSER=edge npx rsbuild dev

# Firefox
BROWSER=firefox npx rsbuild dev
```

On Windows, use [cross-env](https://npmjs.com/package/cross-env) to set the environment variable:

```bash
npm i cross-env -D
cross-env BROWSER=chrome npx rsbuild dev
```

You can also refer to the [app option](https://github.com/sindresorhus/open?tab=readme-ov-file#app) documentation from `open` for additional `BROWSER` values, such as OS-specific browser names:

```bash
# macOS
BROWSER="google chrome" npx rsbuild dev

# Linux
BROWSER="google-chrome" npx rsbuild dev
```

### Browser arguments

Pass browser arguments through `BROWSER_ARGS`, separating multiple arguments with spaces:

```bash
BROWSER=chrome BROWSER_ARGS="--incognito" npx rsbuild dev
```

### AppleScript

On macOS, Rsbuild also supports opening the browser through AppleScript, which allows you to reuse existing browser tabs to open pages.

The following are the browser names supported by AppleScript:

* Google Chrome Canary
* Google Chrome Dev
* Google Chrome Beta
* Google Chrome
* Microsoft Edge
* Brave Browser
* Vivaldi
* Chromium

For example:

```bash
BROWSER="Google Chrome Canary" npx rsbuild dev
```

### Configure environment variable

You can set the `BROWSER` environment variable in your local [.env.local](/guide/advanced/env-vars.md#env-file) file. This way, you don't need to set it manually each time you start the dev server, and it won't affect other developers on the project.

```bash
# .env.local
BROWSER=chrome
```

## Callback

By using `open.before`, you can trigger a callback function before opening the page.

```ts title="rsbuild.config.ts"
export default {
  server: {
    open: {
      before: async () => {
        await doSomeThing();
      },
    },
  },
};
```

When using `open.before`, the page URLs can be configured via `open.target`.

```ts title="rsbuild.config.ts"
export default {
  server: {
    open: {
      target: ['/', '/about'],
      before: async () => {
        await doSomeThing();
      },
    },
  },
};
```

---

# Source: https://rsbuild.dev/guide/optimization/optimize-bundle.md

# Bundle size optimization

Bundle size optimization is critical for production builds because it directly affects user experience. This document covers common bundle size optimization methods in Rsbuild.

## Reduce duplicate dependencies

Web applications commonly bundle multiple versions of third-party dependencies. Duplicate dependencies increase bundle size and slow down builds.

### Detect duplicate dependencies

You can use [Rsdoctor](https://rsdoctor.rs) to detect duplicate dependencies in your project. Rsdoctor analyzes the build, identifies duplicate bundled dependencies, and displays them visually:

![](https://assets.rspack.rs/rsbuild/assets/rsdoctor-duplicated-packages.png)

For more details, see [Rsdoctor - Duplicate Dependency Problem](https://rsdoctor.rs/blog/topic/duplicate-pkg-problem).

### Eliminate duplicate dependencies

You can eliminate duplicate dependencies using your package manager.

* Rsbuild provides the [resolve.dedupe](/config/resolve/dedupe.md) config, which forces specified packages to resolve from the project root directory, removing duplicate packages.

* If you are using `pnpm >= 7.26.0`, you can use the [pnpm dedupe](https://pnpm.io/cli/dedupe) command to upgrade and eliminate duplicate dependencies.

```bash
pnpm dedupe
```

* If you are using `pnpm < 7.26.0`, you can use [pnpm-deduplicate](https://github.com/ocavue/pnpm-deduplicate) to analyze duplicate dependencies, then update dependencies or declare [pnpm overrides](https://pnpm.io/package_json#pnpmoverrides) to merge them.

```bash
npx pnpm-deduplicate --list
```

* If you are using `yarn`, you can use [yarn-deduplicate](https://github.com/scinos/yarn-deduplicate) to automatically merge duplicate dependencies:

```bash
npx yarn-deduplicate && yarn
```

## Use lightweight libraries

We recommend using lightweight libraries in your project, such as replacing [moment](https://momentjs.com/) with [day.js](https://day.js.org/).

To identify the largest third-party libraries in your project, analyze bundle size with Rsdoctor. For more details, see [Using Rsdoctor](/guide/debug/rsdoctor.md).

## Adjust browserslist

Rsbuild compiles code based on your project's browserslist config and injects polyfills. If your project doesn't need to support legacy browsers, adjust the browserslist to drop older targets, reducing compilation overhead for syntax transforms and polyfills.

Rsbuild's default Browserslist config is:

```js
['chrome >= 87', 'edge >= 88', 'firefox >= 78', 'safari >= 14'];
```

For example, if you only need to be compatible with browsers above Chrome 100, you can change it to:

```js
['Chrome >= 100'];
```

:::tip
For more details on configuring Browserslist, see [Browserslist](/guide/advanced/browserslist.md).
:::

## Use polyfill on demand

If your project's [output.polyfill](/config/output/polyfill.md) is set to `'entry'` and you're certain that third-party dependencies don't require additional polyfills, switch it to `usage`.

In `usage` mode, Rsbuild analyzes your source code and injects only the required polyfills, reducing polyfill size.

```js
export default {
  output: {
    polyfill: 'usage',
  },
};
```

:::tip
For more details on polyfill usage, see [Browser compatibility](/guide/advanced/browser-compatibility.md).
:::

## Image compression

In typical front-end projects, images often account for a large portion of the total bundle size. Reducing image size can meaningfully lower the overall bundle size. Enable image compression by registering a plugin in Rsbuild:

```ts title="rsbuild.config.ts"
import { pluginImageCompress } from '@rsbuild/plugin-image-compress';

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

See details in [@rsbuild/plugin-image-compress](https://github.com/rstackjs/rsbuild-plugin-image-compress).

## Split chunk

A good chunk splitting strategy improves application loading performance. It leverages browser caching to reduce the number of requests and improve loading speed.

Several [chunk splitting strategies](/guide/optimization/code-splitting.md) are built into Rsbuild. These should cover most applications. You can also customize the chunk splitting config to suit your use case.

For example, split the `axios` library under node\_modules into `axios.js`:

```js
export default {
  performance: {
    chunkSplit: {
      strategy: 'split-by-experience',
      forceSplitting: {
        axios: /node_modules[\\/]axios/,
      },
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/module-federation/options.md

# moduleFederation.options

* **Type:** [Rspack.ModuleFederationPluginOptions](https://rspack.rs/plugins/webpack/module-federation-plugin#options)
* **Default:** `undefined`

Used to configure the Rspack's Module Federation plugin (Module Federation v1.5).

:::tip
There are several versions of Module Federation implementations. Before using `moduleFederation.options`, please read the [Module Federation guide](/guide/advanced/module-federation.md) to understand the differences between different versions and how to make choices.
:::

## Introduction

When using Module Federation, it is recommended that you use the `moduleFederation.options` option provided by Rsbuild. This option will automatically adjust some related configurations to ensure that the module federation application can run correctly.

When you set the `moduleFederation.options` option, Rsbuild will take the following actions:

* Automatically register the [ModuleFederationPlugin](https://rspack.rs/plugins/webpack/module-federation-plugin) plugin, and pass the value of `options` to the plugin.
* Set the default value of the provider's [dev.assetPrefix](/config/dev/asset-prefix.md) configuration to `true`. This will ensure that the static asset URL is correct for remote modules.
* Set the default value of Rspack's [output.uniqueName](https://rspack.rs/config/output#outputuniquename) configuration to `moduleFederation.options.name`, this allows HMR to work as expected.
* Turn off the `split-by-experience` rules in Rsbuild's [performance.chunkSplit](/config/performance/chunk-split.md) as it may conflict with shared modules, refer to [#3161](https://github.com/module-federation/module-federation-examples/issues/3161).

## Usage

The type of `moduleFederation.options` is exactly the same as the ModuleFederationPlugin plugin of Rspack:

```ts title="rsbuild.config.ts"
export default defineConfig({
  moduleFederation: {
    options: {
      name: 'remote',
      // other options
    },
  },
});
```

Please refer to the [ModuleFederationPlugin](https://rspack.rs/plugins/webpack/module-federation-plugin) document for all available options.

## Example

Here is a minimal example:

* Remote App

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

export default defineConfig({
  server: {
    port: 3002,
  },
  moduleFederation: {
    options: {
      name: 'remote',
      exposes: {
        './Button': './src/Button',
      },
      filename: 'remoteEntry.js',
    },
  },
});
```

* Host App

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

export default defineConfig({
  server: {
    port: 3002,
  },
  moduleFederation: {
    options: {
      name: 'host',
      remotes: {
        remote: 'remote@http://localhost:3002/remoteEntry.js',
      },
    },
  },
});
```

For more examples, please see:

* [Rsbuild - module-federation example](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/module-federation)
* [module-federation/module-federation-examples](https://github.com/module-federation/module-federation-examples)

---

# Source: https://rsbuild.dev/guide/basic/output-files.md

# Output files

This section covers the output file directory structure and how to control output directories for different file types.

To learn about deploying Rsbuild build outputs as a static site, see [Deploy Static Site](/guide/basic/static-deploy.md).

## Default directory structure

The default output directory structure is shown below. Output files are written to the `dist` directory at your project root.

```bash
dist
├── static
│   ├── css
│   │   ├── [name].[hash].css
│   │   └── [name].[hash].css.map
│   │
│   └── js
│       ├── [name].[hash].js
│       ├── [name].[hash].js.LICENSE.txt
│       └── [name].[hash].js.map
│
└── [name].html
```

The most common output files are HTML, JS, and CSS files:

* HTML files: written to the root of the dist directory by default.
* JS files: written to the `static/js` directory by default.
* CSS files: written to the `static/css` directory by default.

Additional files may be generated alongside JS and CSS files:

* License files: contain open-source license information, written to the same directory as JS files with a `.LICENSE.txt` suffix.
* Source map files: contain source mapping information, written to the same directory as JS and CSS files with a `.map` suffix.

In the filename, `[name]` represents the entry name for this file, such as `index` or `main`. `[hash]` is a hash value generated based on the file content.

## Development mode output

In development mode, Rsbuild stores build outputs in memory on the dev server by default rather than writing them to disk. This reduces file system overhead. See [View static assets](/guide/basic/server.md#view-static-assets) to view all static assets generated during the current build.

To write output files to disk (useful for inspecting build artifacts or configuring proxy rules), set [dev.writeToDisk](/config/dev/write-to-disk.md) to `true`:

```ts
export default {
  dev: {
    writeToDisk: true,
  },
};
```

## Modify the output directory

Rsbuild provides several options to customize output directories or filenames:

* Use [output.filename](/config/output/filename.md) to modify the filename.
* Use [output.distPath](/config/output/dist-path.md) to modify the output path.
* Use [output.legalComments](/config/output/legal-comments.md) to modify the license file output.
* Use [output.sourceMap](/config/output/source-map.md) to modify source map output.
* Use [html.outputStructure](/config/html/output-structure.md) to modify the output structure of HTML files.

## Static assets

Static assets imported in your code (images, SVG, fonts, media, etc.) are written to the `dist/static` directory and automatically organized by file type:

```bash
dist
└── static
    ├── image
    │   └── foo.[hash].png
    │
    ├── svg
    │   └── bar.[hash].svg
    │
    ├── font
    │   └── baz.[hash].woff2
    │
    └── media
        └── qux.[hash].mp4
```

Configure [output.distPath](/config/output/dist-path.md) to write static assets to a single directory. For example, to place them all in an `assets` directory:

```ts
export default {
  output: {
    distPath: {
      image: 'assets',
      svg: 'assets',
      font: 'assets',
      media: 'assets',
    },
  },
};
```

This configuration generates the following directory structure:

```bash
dist
└── assets
    ├── foo.[hash].png
    ├── bar.[hash].svg
    ├── baz.[hash].woff2
    └── qux.[hash].mp4
```

## Node.js output directory

With [output.target](/config/output/target.md) set to `'node'`, Rsbuild generates output files for Node.js:

```bash
dist
├── static
└── [name].js
```

Node.js outputs typically contain only JS files, without HTML or CSS. JS filenames do not include hash values.

You can modify the output path for Node.js files using the [environments](/config/environments.md) configuration.

For example, to write Node.js files to the `server` directory:

```ts
export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
        distPath: {
          root: 'dist/server',
        },
      },
    },
  },
};
```

## Flatten directories

To create a flatter directory structure, set any directory path to an empty string.

For example:

```ts
export default {
  output: {
    distPath: {
      js: '',
      css: '',
    },
  },
};
```

This configuration generates the following directory structure:

```bash
dist
├── [name].[hash].css
├── [name].[hash].css.map
├── [name].[hash].js
├── [name].[hash].js.map
└── [name].html
```

---

# Source: https://rsbuild.dev/config/html/output-structure.md

# html.outputStructure

* **Type:** `'flat' | 'nested'`
* **Default:** `'flat'`

Define the directory structure of the HTML output files.

## Example

By default, the structure of HTML files in the `dist` directory is `flat`:

```bash
/dist
 └── [name].html
```

You can set `html.outputStructure` to `nested`:

```ts title="rsbuild.config.ts"
export default {
  html: {
    outputStructure: 'nested',
  },
};
```

After rebuild, the directory structure of the HTML files is:

```bash
/dist
 └── [name]
     └── index.html
```

> If you want to set the parent path of the HTML files, use the [output.distPath.html](/config/output/dist-path.md) config.

---

# Source: https://rsbuild.dev/config/output/override-browserslist.md

# output.overrideBrowserslist

* **Type:** `string[]`
* **Default:** `undefined`

Specifies the range of target browsers that the project is compatible with.

This value will be used by tools such as [SWC](https://github.com/swc-project/swc) and [Lightning CSS](https://github.com/parcel-bundler/lightningcss) to identify the JavaScript syntax that needs to be transformed and the CSS browser prefixes that need to be added.

## Priority

The `overrideBrowserslist` config will override the `.browserslistrc` config file in the project and the `browserslist` field in package.json.

In most cases, it is recommended to use the `.browserslistrc` file rather than the `overrideBrowserslist` config. Because the `.browserslistrc` file is the official config file, it is more general and can be recognized by other libraries in the community.

> For more details, see [Browserslist](/guide/advanced/browserslist.md).

## Default value

If there is no `browserslist` configs defined in the project, nor `overrideBrowserslist` defined, then Rsbuild will set the default browserslist to:

```js
['chrome >= 87', 'edge >= 88', 'firefox >= 78', 'safari >= 14'];
```

## Example

An example of mobile web applications:

```ts title="rsbuild.config.ts"
export default {
  output: {
    overrideBrowserslist: [
      'iOS >= 9',
      'Android >= 4.4',
      'last 2 versions',
      '> 0.2%',
      'not dead',
    ],
  },
};
```

Check out the [browserslist documentation](https://github.com/browserslist/browserslist) to learn more about browserslist.

## Set by environment

When you build for multiple [environments](/config/environments.md), you can set different browserslist for each environment:

For example, set different browserslist for `web` and `node` environments:

```ts title="rsbuild.config.ts"
export default {
  environments: {
    web: {
      output: {
        target: 'web',
        overrideBrowserslist: ['iOS >= 9', 'Android >= 4.4'],
      },
    },
    node: {
      output: {
        target: 'node',
        overrideBrowserslist: ['node >= 20'],
      },
    },
  },
};
```

---

# Source: https://rsbuild.dev/plugins/list/plugin-babel.md

# Babel plugin

import { SourceCode } from '@theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-babel" />

Rsbuild uses SWC transpilation by default. When existing functions cannot meet the requirements, and some Babel presets or plugins need to be added for additional processing, you can use Rsbuild's Babel Plugin.

## Quick start

### Install plugin

You can install the plugin using the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-babel -D" />

### Register plugin

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

```ts title="rsbuild.config.ts"
import { pluginBabel } from '@rsbuild/plugin-babel';

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

## Compilation cache

After using the Babel plugin, Rsbuild will perform the Babel transpilation in addition to the standard SWC transpilation, which adds additional compilation overhead. This can cause a noticeable decrease in build speed.

To reduce the overhead of Babel transpilation, the `@rsbuild/plugin-babel` enables Babel compilation cache by default. If you want to disable the cache, you can set [performance.buildCache](/config/performance/build-cache.md) to `false`:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    buildCache: false,
  },
};
```

## Options

### babelLoaderOptions

These options are passed to `babel-loader`. For details, see the [babel-loader documentation](https://github.com/babel/babel-loader).

* **Type:** `Object | Function`
* **Default:**

```ts
const defaultOptions = {
  babelrc: false,
  compact: false,
  configFile: false,
  plugins: [
    ['@babel/plugin-proposal-decorators', config.source.decorators],
    ...(isLegacyDecorators ? ['@babel/plugin-transform-class-properties'] : []),
  ],
  presets: [
    [
      '@babel/preset-typescript',
      {
        allExtensions: true,
        allowDeclareFields: true,
        allowNamespaces: true,
        isTSX: true,
        optimizeConstEnums: true,
      },
    ],
  ],
};
```

#### Function type

When configuration is of type `Function`, the default Babel configuration will be passed as the first parameter. You can directly modify the configuration object or return an object as the final `babel-loader` configuration.

```js
pluginBabel({
  babelLoaderOptions: (config) => {
    // Add a Babel plugin
    // note: the plugin have been added to the default config to support antd load on demand
    config.plugins ||= [];
    config.plugins.push([
      'babel-plugin-import',
      {
        libraryName: 'my-components',
        libraryDirectory: 'es',
        style: true,
      },
    ]);
  },
});
```

The second parameter of the function provides some more convenient utility functions. Please continue reading the documentation below.

:::tip
The above example is just for reference, usually you do not need to manually configure `babel-plugin-import`, because the Rsbuild already provides a more general `source.transformImport` configuration.
:::

#### Object type

When configuration's type is `Object`, the config will be shallow merged with default config by `Object.assign`.

:::caution
Note that `Object.assign` is a shallow copy and will completely overwrite the built-in `presets` or `plugins` array, please use it with caution.
:::

```js
pluginBabel({
  babelLoaderOptions: {
    plugins: [
      [
        'babel-plugin-import',
        {
          libraryName: 'my-components',
          libraryDirectory: 'es',
          style: true,
        },
      ],
    ],
  },
});
```

#### Util functions

When configuration is a Function, the tool functions available for the second parameter are as follows:

##### addPlugins

* **Type:** `(plugins: BabelPlugin[]) => void`

Add some Babel plugins. For example:

```js
pluginBabel({
  babelLoaderOptions: (config, { addPlugins }) => {
    addPlugins([
      [
        'babel-plugin-import',
        {
          libraryName: 'my-components',
          libraryDirectory: 'es',
          style: true,
        },
      ],
    ]);
  },
});
```

##### addPresets

* **Type:** `(presets: BabelPlugin[]) => void`

Add Babel preset configuration. (No need to add presets in most cases)

```js
pluginBabel({
  babelLoaderOptions: (config, { addPresets }) => {
    addPresets(['@babel/preset-env']);
  },
});
```

##### removePlugins

* **Type:** `(plugins: string | string[]) => void`

To remove the Babel plugin, just pass in the name of the plugin to be removed, you can pass in a single string or an array of strings.

```js
pluginBabel({
  babelLoaderOptions: (config, { removePlugins }) => {
    removePlugins('babel-plugin-import');
  },
});
```

##### removePresets

* **Type:** `(presets: string | string[]) => void`

To remove the Babel preset configuration, pass in the name of the preset to be removed, you can pass in a single string or an array of strings.

```js
pluginBabel({
  babelLoaderOptions: (config, { removePresets }) => {
    removePresets('@babel/preset-env');
  },
});
```

### include

* **Type:** `string | RegExp | (string | RegExp)[]`
* **Default:** `undefined`

Used to specify the files that need to be compiled by Babel.

Due to the performance overhead of Babel compilation, matching only certain files through `include` can reduce the number of modules compiled by Babel, thereby improving build performance.

For example, to only compile `.custom.js` files and ignore files under `node_modules`:

```js
pluginBabel({
  include: /\.custom\.js$/,
  // recommended to exclude the node_modules to improve build performance
  exclude: /[\\/]node_modules[\\/]/,
});
```

:::tip
When you configure the `include` or `exclude` options, Rsbuild will create a separate Rspack rule to apply babel-loader and swc-loader.

This separate rule is completely independent of the SWC rule built into Rsbuild and is not affected by [source.include](/config/source/include.md) and [source.exclude](/config/source/exclude.md).
:::

### exclude

* **Type:** `string | RegExp | (string | RegExp)[]`
* **Default:** `undefined`

Used to specify the files that do not need to be compiled by Babel.

Due to the performance overhead of Babel compilation, excluding certain files through `exclude` can reduce the number of modules compiled by Babel, thereby improving build performance.

## Execution order

After using `@rsbuild/plugin-babel`, Rsbuild will use both `babel-loader` and `builtin:swc-loader` to compile JavaScript files, with Babel running before SWC.

This means that if you are using some new ECMAScript features in your code, you may need to add Babel plugins to ensure that Babel can correctly compile these new features.

For example, add the [@babel/plugin-transform-private-methods](https://www.npmjs.com/package/@babel/plugin-transform-private-methods) plugin to enable Babel to correctly compile [private properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_properties):

```ts
pluginBabel({
  babelLoaderOptions: {
    plugins: ['@babel/plugin-transform-private-methods'],
  },
});
```

## Debugging configs

After modifying the `babel-loader` configuration, you can view the final generated configuration in [Rsbuild debug mode](/guide/debug/debug-mode.md).

First, enable debug mode by using the `DEBUG=rsbuild` option:

```bash
# Debug development mode
DEBUG=rsbuild pnpm dev

# Debug production mode
DEBUG=rsbuild pnpm build
```

Then open the generated `rspack.config.web.mjs` file and search for the `babel-loader` keyword to see the complete `babel-loader` configuration.

## FAQ

### Compilation freezes

After using the babel plugin, if the compilation progress bar is stuck, but there is no Error log on the terminal, it is usually because an exception occurred during the compilation. In some cases, when Error is caught by webpack or other modules, the error log cannot be output correctly. The most common scenario is that there is an exception in the Babel config, which is caught by webpack, and webpack swallows the Error in some cases.

**Solution:**

If this problem occurs after you modify the Babel config, it is recommended to check for the following incorrect usages:

1. You have configured a plugin or preset that does not exist, maybe the name is misspelled, or it is not installed correctly.

```ts
// wrong example
pluginBabel({
  babelLoaderOptions: (config, { addPlugins }) => {
    // The plugin has the wrong name or is not installed
    addPlugins('babel-plugin-not-exists');
  },
});
```

2. Whether multiple babel-plugin-imports are configured, but the name of each babel-plugin-import is not declared in the third item of the array.

```ts
// wrong example
pluginBabel({
  babelLoaderOptions: (config, { addPlugins }) => {
    addPlugins([
      ['babel-plugin-import', { libraryName: 'antd', libraryDirectory: 'es' }],
      [
        'babel-plugin-import',
        { libraryName: 'antd-mobile', libraryDirectory: 'es' },
      ],
    ]);
  },
});
```

```ts
// correct example
pluginBabel({
  babelLoaderOptions: (config, { addPlugins }) => {
    addPlugins([
      [
        'babel-plugin-import',
        { libraryName: 'antd', libraryDirectory: 'es' },
        'antd',
      ],
      [
        'babel-plugin-import',
        { libraryName: 'antd-mobile', libraryDirectory: 'es' },
        'antd-mobile',
      ],
    ]);
  },
});
```

---

# Source: https://rsbuild.dev/plugins/list/plugin-less.md

# Less plugin

import { SourceCode } from '@theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-less" />

Use [Less](https://lesscss.org/) as the CSS preprocessor, implemented based on [less-loader](https://github.com/webpack/less-loader).

## Quick start

### Install plugin

You can install the plugin using the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-less -D" />

:::tip

* The Less plugin only supports @rsbuild/core versions >= 0.7.0.
* If the @rsbuild/core version is lower than 0.7.0, it has built-in support for the Less plugin, you do not need to install it.

:::

### Register plugin

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

```ts title="rsbuild.config.ts"
import { pluginLess } from '@rsbuild/plugin-less';

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

After registering the plugin, you can import `*.less` or `*.module.less` files into the code without adding other configs.

## Options

To customize the compilation behavior of Less, use the following options.

### lessLoaderOptions

You can modify the config of [less-loader](https://github.com/webpack/less-loader) via `lessLoaderOptions`.

* **Type:** `Object | Function`
* **Default:**

```js
const defaultOptions = {
  lessOptions: {
    javascriptEnabled: true,
    paths: [path.join(rootPath, 'node_modules')],
  },
  implementation: require.resolve('less'),
  sourceMap: rsbuildConfig.output.sourceMap.css,
};
```

* **Example:**

If `lessLoaderOptions` is an object, it is merged with the default config through `Object.assign` in a shallow way. It should be noted that `lessOptions` is merged through deepMerge in a deep way.

```js
pluginLess({
  lessLoaderOptions: {
    lessOptions: {
      javascriptEnabled: false,
    },
  },
});
```

If `lessLoaderOptions` is a function, the default config is passed as the first parameter, which can be directly modified or returned as the final result.

```js
pluginLess({
  lessLoaderOptions(config) {
    config.lessOptions = {
      javascriptEnabled: false,
    };
  },
});
```

:::tip
The `lessLoaderOptions.lessOptions` config is passed to Less. See the [Less documentation](https://lesscss.org/usage/#command-line-usage-options) for all available options.
:::

### include

* **Type:** [Rspack.RuleSetCondition](https://rspack.rs/config/module-rules#condition)
* **Default:** `/\.less$/`
* **Version:** `>= 1.1.0`

Include some `.less` files, they will be transformed by `less-loader`. The value is the same as the [rules\[\].test](https://rspack.rs/config/module-rules#rulestest) option in Rspack.

For example:

```ts
pluginLess({
  include: /\.custom\.less$/,
});
```

### exclude

* **Type:** [Rspack.RuleSetCondition](https://rspack.rs/config/module-rules#condition)
* **Default:** `undefined`

Exclude some `.less` files, they will not be transformed by `less-loader`.

For example:

```ts
pluginLess({
  exclude: /some-folder[\\/]foo\.less/,
});
```

### parallel

* **Type:** `boolean`
* **Default:** `false`
* **Version:** Added in v1.4.0

Whether to enable parallel loader execution, running `less-loader` in worker threads. When enabled, this typically improves build performance when compiling large numbers of Less modules.

Note that this option is experimental and may not work if your Less options contain functions.

```ts
pluginLess({
  parallel: true,
});
```

> See [Rspack - Rule.use.parallel](https://rspack.rs/config/module-rules#rulesuseparallel) for more details.

## Modifying Less version

In some scenarios, if you need to use a specific version of Less instead of the built-in Less v4 in Rsbuild, you can install the desired Less version in your project and set it up using the `implementation` option of the `less-loader`.

```js
pluginLess({
  lessLoaderOptions: {
    implementation: require('less'),
  },
});
```

## Practices

### Configure multiple Less plugins

By using the `include` and `exclude` options, you can register multiple Less plugins and specify different options for each plugin.

For example:

```ts
export default {
  plugins: [
    pluginLess({
      exclude: /\.another\.less$/,
    }),
    pluginLess({
      include: /\.another\.less$/,
      lessLoaderOptions: {
        // some custom options
      },
    }),
  ],
};
```

## FAQ

### Division in Less file does not work?

The built-in Less version for `@rsbuild/plugin-less` is v4. Compared to v3, there are some differences in the division syntax in Less v4:

```less
// Less v3
.math {
  width: 2px / 2; // 1px
  width: 2px ./ 2; // 1px
  width: (2px / 2); // 1px
}

// Less v4
.math {
  width: 2px / 2; // 2px / 2
  width: 2px ./ 2; // 1px
  width: (2px / 2); // 1px
}
```

The division syntax in Less can be modified through configuration. For more details, see [Less - Math](https://lesscss.org/usage/#less-options-math).

---

# Source: https://rsbuild.dev/plugins/list/plugin-preact.md

# Preact plugin

import { SourceCode } from '@theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-preact" />

The Preact plugin provides support for Preact, integrating features such as JSX compilation and React aliasing.

## Quick start

### Install plugin

You can install the plugin using the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-preact -D" />

### Register plugin

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

```ts title="rsbuild.config.ts"
import { pluginPreact } from '@rsbuild/plugin-preact';

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

After registering the plugin, you can directly develop Preact.

## Options

### reactAliasesEnabled

Whether to aliases `react`, `react-dom` to `preact/compat`.

* **Type:** `boolean`
* **Default:** `true`
* **Example:** Disable aliases.

```ts
pluginPreact({
  reactAliasesEnabled: false,
});
```

### prefreshEnabled

Whether to inject [Prefresh](https://github.com/preactjs/prefresh) for HMR.

* **Type:** `boolean`
* **Default:** `true`
* **Version:** `>= v1.1.0`
* **Example:** Disable Prefresh.

```ts
pluginPreact({
  prefreshEnabled: false,
});
```

### include

Include files to be processed by the [@rspack/plugin-preact-refresh](https://github.com/rstackjs/rspack-plugin-preact-refresh) plugin. The value is the same as the [rules\[\].test](https://rspack.rs/config/module-rules#rulestest) option in Rspack.

* **Type:** [Rspack.RuleSetCondition](https://rspack.rs/config/module-rules#condition)
* **Default:** `/\.(?:js|jsx|mjs|cjs|ts|tsx|mts|cts)$/`
* **Version:** `>= v1.1.0`

```ts
pluginPreact({
  include: [/\.(?:js|jsx|mjs|cjs|ts|tsx|mts|cts)$/, /some-other-module/],
});
```

### exclude

Exclude files from being processed by the [@rspack/plugin-preact-refresh](https://github.com/rstackjs/rspack-plugin-preact-refresh) plugin. The value is the same as the [rules\[\].exclude](https://rspack.rs/config/module-rules#rulesexclude) option in Rspack.

* **Type:** [Rspack.RuleSetCondition](https://rspack.rs/config/module-rules#condition)
* **Default:** `/[\\/]node_modules[\\/]/`
* **Version:** `>= v1.1.0`

```ts
pluginPreact({
  exclude: [/[\\/]node_modules[\\/]/, /some-other-module/],
});
```

---

# Source: https://rsbuild.dev/plugins/list/plugin-react.md

# React plugin

import { SourceCode } from '@theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-react" />

The React plugin provides support for React, integrating features such as JSX compilation and React Refresh.

## Quick start

### Install plugin

Install the plugin using this command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-react -D" />

### Register plugin

Register the plugin in your `rsbuild.config.ts` file:

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

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

After registering the plugin, you can develop React directly.

## Options

### swcReactOptions

Configure the behavior of SWC to transform React code, the same as SWC's [jsc.transform.react](https://swc.rs/docs/configuration/compilation#jsctransformreact) option.

* **Type:**

```ts
interface ReactConfig {
  pragma?: string;
  pragmaFrag?: string;
  throwIfNamespace?: boolean;
  development?: boolean;
  refresh?:
    | boolean
    | {
        refreshReg?: string;
        refreshSig?: string;
        emitFullSignatures?: boolean;
      };
  runtime?: 'automatic' | 'classic' | 'preserve';
  importSource?: string;
}
```

* **Default:**

```ts
const isDev = process.env.NODE_ENV === 'development';
const defaultOptions = {
  development: isDev,
  refresh: isDev,
  runtime: 'automatic',
};
```

### swcReactOptions.runtime

Decides which runtime to use when transforming JSX.

* **Type:** `'automatic' | 'classic' | 'preserve'`
* **Default:** `'automatic'`

#### automatic

By default, Rsbuild uses `runtime: 'automatic'` to leverage the [new JSX runtime](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) introduced in React 17.

This approach eliminates the need to manually import React in every file that uses JSX.

:::tip
React 16.14.0 and later versions support the new JSX runtime.
:::

#### classic

For React versions prior to 16.14.0, set `runtime` to `'classic'`:

```ts
pluginReact({
  swcReactOptions: {
    runtime: 'classic',
  },
});
```

When using the classic JSX runtime, you must manually import React in your code:

```jsx title="App.jsx"
import React from 'react';

function App() {
  return <h1>Hello World</h1>;
}
```

#### preserve

Use `runtime: 'preserve'` to leave JSX syntax unchanged without transforming it, this is useful when you are building a library that expects JSX to be left as is.

```ts
pluginReact({
  swcReactOptions: {
    runtime: 'preserve',
  },
});
```

### swcReactOptions.importSource

* **Type:** `string`
* **Default:** `'react'`

With `runtime` set to `'automatic'`, you can specify the JSX runtime import path through `importSource`.

For example, when using [Emotion](https://emotion.sh/), you can set `importSource` to `'@emotion/react'`:

```ts
pluginReact({
  swcReactOptions: {
    importSource: '@emotion/react',
  },
});
```

> See [Customize JSX](/guide/framework/react.md#customize-jsx) for more details.

### swcReactOptions.refresh

* **Type:** `boolean`
* **Default:** based on [fastRefresh](#fastrefresh) and [dev.hmr](/config/dev/hmr.md)

Whether to enable [React Fast Refresh](https://npmjs.com/package/react-refresh).

Most of the time, you should use the plugin's [fastRefresh](#fastrefresh) option to enable or disable Fast Refresh.

### splitChunks

When [chunkSplit.strategy](/config/performance/chunk-split.md) set to `split-by-experience`, Rsbuild will automatically split `react` and `router` related packages into separate chunks by default:

* `lib-react.js`: includes `react`, `react-dom`, and their sub-dependencies (`scheduler`).
* `lib-router.js`: includes `react-router`, `react-router-dom`, and their sub-dependencies (`history`, `@remix-run/router`).

This option is used to control this behavior and determine whether the `react` and `router` related packages need to be split into separate chunks.

* **Type:**

```ts
type SplitChunks =
  | boolean
  | {
      react?: boolean;
      router?: boolean;
    };
```

* **Default:** `true` (equivalent to `{ react: true, router: true }`)

For example, to disable all chunk splitting:

```ts
pluginReact({ splitChunks: false });
```

Or to disable only the `router` chunk splitting:

```ts
pluginReact({
  splitChunks: {
    react: true,
    router: false,
  },
});
```

### enableProfiler

* **Type:** `boolean`
* **Default:** `false`

When set to `true`, enables the React Profiler for performance analysis in production builds. Use the React DevTools to examine profiling results and identify potential performance optimizations. Profiling adds a slight overhead, so it is disabled by default in production mode.

```ts title="rsbuild.config.ts"
pluginReact({
  // Only enable the profiler when REACT_PROFILER is true,
  // as the option will increase the build time and add some small additional overhead.
  enableProfiler: process.env.REACT_PROFILER === 'true',
});
```

Set `REACT_PROFILER=true` when running build script:

```json title="package.json"
{
  "scripts": {
    "build:profiler": "REACT_PROFILER=true rsbuild build"
  }
}
```

As Windows does not support the above usage, you can also use [cross-env](https://npmjs.com/package/cross-env) to set environment variables. This ensures compatibility across different systems:

```json title="package.json"
{
  "scripts": {
    "build:profiler": "cross-env REACT_PROFILER=true rsbuild build"
  },
  "devDependencies": {
    "cross-env": "^7.0.0"
  }
}
```

> See the [React docs](https://legacy.reactjs.org/docs/optimizing-performance.html#profiling-components-with-the-devtools-profiler) for details about profiling using the React DevTools.

### reactRefreshOptions

* **Type:**

```ts
type ReactRefreshOptions = {
  // @link https://rspack.rs/config/module-rules#condition
  test?: Rspack.RuleSetCondition;
  include?: Rspack.RuleSetCondition;
  exclude?: Rspack.RuleSetCondition;
  library?: string;
  forceEnable?: boolean;
};
```

* **Default:**

```js
const defaultOptions = {
  test: [/\.(?:js|jsx|mjs|cjs|ts|tsx|mts|cts)$/],
  include: [
    // Same as Rsbuild's `source.include` configuration
  ],
  exclude: [
    // Same as Rsbuild's `source.exclude` configuration
  ],
  resourceQuery: { not: /^\?raw$/ },
};
```

Set the options for [@rspack/plugin-react-refresh](https://github.com/rstackjs/rspack-plugin-react-refresh). The passed value will be shallowly merged with the default value.

* **Example:**

```js
pluginReact({
  reactRefreshOptions: {
    exclude: [/some-module-to-exclude/, /[\\/]node_modules[\\/]/],
  },
});
```

### fastRefresh

* **Type:** `boolean`
* **Default:** `true`

Whether to enable [React Fast Refresh](https://npmjs.com/package/react-refresh) in development mode.

If `fastRefresh` is set to `true`, `@rsbuild/plugin-react` will automatically register the [@rspack/plugin-react-refresh](https://github.com/rstackjs/rspack-plugin-react-refresh) plugin.

To disable Fast Refresh, set it to `false`:

```ts
pluginReact({
  fastRefresh: false,
});
```

---

# Source: https://rsbuild.dev/plugins/list/plugin-sass.md

# Sass plugin

import { SourceCode } from '@theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-sass" />

Use [Sass](https://sass-lang.com/) as the CSS preprocessor, implemented based on [sass-loader](https://github.com/webpack/sass-loader).

## Quick start

### Install plugin

Install the plugin using this command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-sass -D" />

:::tip

* The Sass plugin only supports @rsbuild/core versions >= 0.7.0.
* If the @rsbuild/core version is lower than 0.7.0, it has built-in support for the Sass plugin; you don't need to install it.

:::

### Register plugin

Register the plugin in your `rsbuild.config.ts` file:

```ts title="rsbuild.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 into the code without adding other configs.

## Options

To customize the compilation behavior of Sass, use the following options.

### sassLoaderOptions

Modify the config of [sass-loader](https://github.com/webpack/sass-loader).

* **Type:** `Object | Function`
* **Default:**

```js
const defaultOptions = {
  api: 'modern-compiler',
  implementation: require.resolve('sass-embedded'),
  sourceMap: rsbuildConfig.output.sourceMap.css,
  sassOptions: {
    quietDeps: true,
    silenceDeprecations: ['legacy-js-api', 'import'],
  },
};
```

* **Example:**

If `sassLoaderOptions` is an object, it is merged with the default config through `Object.assign`. It should be noted that `sassOptions` is merged through deepMerge in a deep way.

```js
pluginSass({
  sassLoaderOptions: {
    sourceMap: true,
  },
});
```

If `sassLoaderOptions` is a function, the default config is passed as the first parameter, which can be directly modified or returned as the final result.

```js
pluginSass({
  sassLoaderOptions(config) {
    config.additionalData = async (content, loaderContext) => {
      // ...
    };
  },
});
```

### include

* **Type:** [Rspack.RuleSetCondition](https://rspack.rs/config/module-rules#condition)
* **Default:** `/\.s(?:a|c)ss$/`
* **Version:** `>= 1.1.0`

Include some `.scss` or `.sass` files, they will be transformed by `sass-loader`. The value is the same as the [rules\[\].test](https://rspack.rs/config/module-rules#rulestest) option in Rspack.

For example:

```ts
pluginSass({
  include: /\.custom\.scss$/,
});
```

### exclude

* **Type:** [Rspack.RuleSetCondition](https://rspack.rs/config/module-rules#condition)
* **Default:** `undefined`

Exclude some `.sass` or `.scss` files, they will not be transformed by `sass-loader`.

For example:

```ts
pluginSass({
  exclude: /some-folder[\\/]foo\.scss/,
});
```

### rewriteUrls

* **Type:** `boolean`
* **Default:** `true`
* **Version:** `>= 1.2.0`

Whether to use [resolve-url-loader](https://github.com/bholloway/resolve-url-loader/tree/v5/packages/resolve-url-loader) to rewrite URLs.

When enabled, `resolve-url-loader` allows you to write relative URLs in your Sass files that are correctly resolved from the current Sass file's location, rather than being relative to the Sass entry file (e.g. `main.scss`).

If you set this option to `false`, the build performance will be improved, but Rsbuild will use the native URL resolution of Sass, which means all URLs must be relative to the Sass entry file.

```ts
pluginSass({
  rewriteUrls: false,
});
```

## Practices

### Modify Sass implementation

Sass provides several implementations, including [sass](https://npmjs.com/package/sass), [sass-embedded](https://npmjs.com/package/sass-embedded), and [node-sass](https://npmjs.com/package/node-sass).

Rsbuild uses the latest `sass-embedded` implementation by default. `sass-embedded` is a JavaScript wrapper around the native Dart Sass executable, providing a consistent API and optimal performance.

To use a different Sass implementation instead of the built-in `sass-embedded` included in Rsbuild, install the preferred Sass implementation in your project and specify it using the `sass-loader`'s [implementation](https://github.com/webpack/sass-loader?tab=readme-ov-file#implementation) option.

```ts
pluginSass({
  sassLoaderOptions: {
    implementation: require.resolve('sass'),
  },
});
```

:::tip
Switching from `sass-embedded` to another Sass implementation can significantly decrease build performance.
:::

### Select Sass API

Rsbuild uses the latest `modern-compiler` API by default. If you rely on the `legacy` API of Sass, you can set the `api` option of the sass-loader to `legacy` to maintain compatibility with some deprecated Sass syntax.

```ts
pluginSass({
  sassLoaderOptions: {
    api: 'legacy',
  },
});
```

:::tip
Sass's `legacy` API has been deprecated and will be removed in Sass 2.0. We recommend migrating to the `modern-compiler` API. For more details, see [Sass - Legacy JS API](https://sass-lang.com/documentation/breaking-changes/legacy-js-api/).
:::

### Ignore Sass deprecation warnings

Sass uses warning logs to highlight deprecated patterns that will be removed in future major releases. We recommend updating your code according to these warnings. If you do not want to see them, you can ignore the warnings by using the [silenceDeprecations](https://sass-lang.com/documentation/js-api/interfaces/stringoptions/#silenceDeprecations) option in Sass.

For example, `@import` has been deprecated in Sass. If you use this syntax, Sass will output the following prompt:

```
Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.

More info and automated migrator: https://sass-lang.com/d/import

 0 | @import './b.scss';
```

`@rsbuild/plugin-sass` adds the following configuration by default to silence the `@import` warning, if you need to silence other deprecated warnings, you can use the same method.

```ts
pluginSass({
  sassLoaderOptions: {
    sassOptions: {
      silenceDeprecations: ['import'],
    },
  },
});
```

> For more information, see [Sass Deprecations](https://sass-lang.com/documentation/js-api/interfaces/deprecations/).

### Configure multiple Sass plugins

By using the `include` and `exclude` options, you can register multiple Sass plugins and specify different options for each plugin.

For example:

```ts
export default {
  plugins: [
    pluginSass({
      exclude: /\.another\.scss$/,
    }),
    pluginSass({
      include: /\.another\.scss$/,
      sassLoaderOptions: {
        // some custom options
      },
    }),
  ],
};
```

---

# Source: https://rsbuild.dev/plugins/list/plugin-solid.md

# Solid plugin

import { SourceCode } from '@theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-solid" />

The Solid plugin provides support for Solid features. The plugin internally integrates [babel-preset-solid](https://github.com/solidjs/solid/tree/main/packages/babel-preset-solid).

:::tip
The Solid plugin relies on Babel transpilation and requires an additional [Babel Plugin](/plugins/list/plugin-babel.md). At the same time, adding the Babel plugin will cause additional compilation overhead.
:::

## Quick start

### Install plugin

You can install the plugin using the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-babel @rsbuild/plugin-solid -D" />

### Register plugin

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

```ts title="rsbuild.config.ts"
import { pluginBabel } from '@rsbuild/plugin-babel';
import { pluginSolid } from '@rsbuild/plugin-solid';

export default {
  plugins: [
    pluginBabel({
      include: /\.(?:jsx|tsx)$/,
    }),
    pluginSolid(),
  ],
};
```

After registering the plugin, you can directly develop Solid.

:::tip
Since the Solid JSX relies on Babel for compilation, you need to additionally add the [Babel plugin](/plugins/list/plugin-babel.md).

Babel compilation will introduce extra overhead, in the example above, we use `include` to match `.jsx` and `.tsx` files, thereby reducing the performance cost brought by Babel.

:::

## Options

To customize the compilation behavior of Solid, use the following options.

### solidPresetOptions

These options are passed to `babel-preset-solid`. For details, see the [babel-preset-solid documentation](https://npmjs.com/package/babel-preset-solid).

* **Type:** `SolidPresetOptions`
* **Default:** `{}`
* **Example:**

```ts
pluginSolid({
  solidPresetOptions: {
    generate: 'ssr',
    hydratable: true,
  },
});
```

---

# Source: https://rsbuild.dev/plugins/list/plugin-stylus.md

# Stylus plugin

import { SourceCode } from '@theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-stylus" />

[Stylus](https://stylus-lang.com/) is an Expressive, dynamic and robust CSS preprocessor. With Stylus plugins, you can use Stylus as the CSS preprocessor.

## Quick start

### Install plugin

You can install the plugin using the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-stylus -D" />

### Register plugin

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

```ts title="rsbuild.config.ts"
import { pluginStylus } from '@rsbuild/plugin-stylus';

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

## Example

After registering the plugin, you can import `*.styl`, `*.stylus`, `*.module.styl` or `*.module.stylus` files into the code without adding other configs.

* `normalize.styl`:

```styl
the body
   color#000
   font 14px Arial, sans-serif
```

* `title.module.styl`:

```styl
.title
   font-size: 14px;
```

* `index.js`:

```js
import './normalize.styl';
import style from './title.module.styl';

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

## Options

To customize the compilation behavior of Stylus, use the following options.

### stylusOptions

-Type:

```ts
type StylusOptions = {
  use?: string[];
  define?: [string, any, boolean?][];
  include?: string[];
  includeCSS?: boolean;
  import?: string[];
  resolveURL?: boolean;
  lineNumbers?: boolean;
  hoistAtrules?: boolean;
};
```

* **Default:** `undefined`

These options are passed to Stylus. For details, see the [Stylus documentation](https://stylus-lang.com/docs/js).

```ts
pluginStylus({
  stylusOptions: {
    lineNumbers: false,
  },
});
```

### sourceMap

* **Type:** `boolean`
* **Default:** the same as [output.sourceMap.css](/config/output/source-map.md)

Whether to generate source map.

```ts
pluginStylus({
  sourceMap: false,
});
```

---

# Source: https://rsbuild.dev/plugins/list/plugin-svelte.md

# Svelte plugin

import { SourceCode } from '@theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-svelte" />

The Svelte plugin provides support for Svelte components (`.svelte` files). The plugin internally integrates [svelte-loader](https://github.com/sveltejs/svelte-loader).

## Quick start

### Install plugin

You can install the plugin using the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-svelte -D" />

### Register plugin

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

```ts title="rsbuild.config.ts"
import { pluginSvelte } from '@rsbuild/plugin-svelte';

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

After registering the plugin, you can import `*.svelte` files in your code.

## Options

To customize the compilation behavior of Svelte, use the following options.

### svelteLoaderOptions

These options are passed to `svelte-loader`. For details, see the [svelte-loader documentation](https://github.com/sveltejs/svelte-loader).

* **Type:** `SvelteLoaderOptions`
* **Default:**

```js
const defaultOptions = {
  compilerOptions: {
    dev: isDev,
  },
  preprocess: require('svelte-preprocess')(),
  emitCss: isProd && !rsbuildConfig.output.injectStyles,
  hotReload: isDev && rsbuildConfig.dev.hmr,
};
```

* **Example:**

```ts
pluginSvelte({
  svelteLoaderOptions: {
    preprocess: null,
  },
});
```

### preprocessOptions

These options are passed to `svelte-preprocess`. For details, see the [svelte-preprocess documentation](https://github.com/sveltejs/svelte-preprocess/blob/c2107e529da9438ea5b8060aa471119940896e40/docs/preprocessing.md).

* **Type:** `AutoPreprocessOptions`
* **Default:** `undefined`

```ts
interface AutoPreprocessOptions {
  globalStyle: { ... },
  replace: { ... },
  typescript: { ... },
  scss: { ... },
  sass: { ... },
  less: { ... },
  stylus: { ... },
  babel: { ... },
  postcss: { ... },
  coffeescript: { ... },
  pug: { ... },
}
```

* **Example:**

```ts
pluginSvelte({
  preprocessOptions: {
    aliases: [
      ['potato', 'potatoLanguage'],
      ['pot', 'potatoLanguage'],
    ],
    /** Add a custom language preprocessor */
    potatoLanguage({ content, filename, attributes }) {
      const { code, map } = require('potato-language').render(content);
      return { code, map };
    },
  },
});
```

## Notes

Currently, `svelte-loader` does not support HMR for Svelte v5, see [svelte-loader - Hot Reload](https://github.com/sveltejs/svelte-loader?tab=readme-ov-file#hot-reload).

### Alias handling in Less/Sass

When using aliases to import Less or Sass files within Svelte components, you need to manually configure the preprocessor to handle alias resolution. Otherwise, you may encounter `"file not found"` errors.

* **Example:**

```ts title="rsbuild.config.ts"
import { pluginSvelte } from '@rsbuild/plugin-svelte';

export default {
  plugins: [
    pluginSvelte({
      preprocessOptions: {
        scss: {
          importer: [
            // Handle alias imports for SCSS files
            (url, prev) => {
              if (url.startsWith('@/')) {
                return { file: url.replace('@/', 'src/') };
              }
              return null;
            },
          ],
        },
        less: {
          // recommend simple alias handling for Less files
          replace: [['@/style', 'style']],
          // use less plugin to handle alias imports
          plugins: [],
        },
      },
    }),
  ],
};
```

This ensures that alias imports like `@import '@/styles/variables.scss'` or `@import '@/styles/variables.less'` are properly resolved within Svelte components.

---

# Source: https://rsbuild.dev/plugins/list/plugin-svgr.md

# SVGR plugin

import { SourceCode } from '@theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-svgr" />

By default, Rsbuild treats SVG files as static assets. For processing rules, see [Static assets](/guide/basic/static-assets.md).

With the SVGR plugin, Rsbuild supports transforming SVG to React components via [SVGR](https://react-svgr.com/).

## Quick start

### Install plugin

You can install the plugin using the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-svgr -D" />

### Register plugin

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

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

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

## Example

### Default usage

After registering the plugin, when you import an SVG in a JavaScript file, if the imported path includes the `?react` suffix, Rsbuild will call SVGR to transform the SVG into a React component.

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

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

If the imported path doesn't include the `?react` suffix, the SVG will be treated as a normal static asset and you will get a URL string or base64 URL. See [Static assets](/guide/basic/static-assets.md).

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

console.log(logoURL); // => "/static/logo.6c12aba3.png"
```

### Named import

`@rsbuild/plugin-svgr` supports named imports for `ReactComponent` when using SVGR. You need to set [svgrOptions.exportType](#svgroptionsexporttype) to `'named'`:

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

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

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

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

* Enable default imports by setting [svgrOptions.exportType](#svgroptionsexporttype) to `'default'`.
* Enable mixed imports by setting the [mixedImport](#mixedimport) option to use both default and named imports at the same time.

## Options

To customize the compilation behavior of Svgr, use the following options.

* **Type:**

```ts
type PluginSvgrOptions = {
  /**
   * Configure SVGR options.
   */
  svgrOptions?: import('@svgr/core').Config;
  /**
   * Whether to allow the use of default import and named import at the same time.
   * @default false
   */
  mixedImport?: boolean;
};
```

### svgrOptions

Modifies the options of SVGR, the passed object will be deep merged with the default value. See [SVGR - Options](https://react-svgr.com/docs/options/) for details.

* **Type:** `import('@svgr/core').Config`
* **Default:**

```ts
const defaultSvgrOptions = {
  svgo: true,
  svgoConfig: {
    plugins: [
      {
        name: 'preset-default',
        params: {
          overrides: {
            removeViewBox: false,
          },
        },
      },
      'prefixIds',
    ],
  },
};
```

* **Example:**

```ts
pluginSvgr({
  svgrOptions: {
    svgoConfig: {
      datauri: 'base64',
    },
  },
});
```

When you set `svgoConfig.plugins`, the configuration for plugins with the same name is automatically merged. For example, the following configuration will be merged with the built-in `preset-default`:

```ts
pluginSvgr({
  svgrOptions: {
    svgoConfig: {
      plugins: [
        {
          name: 'preset-default',
          params: {
            overrides: {
              cleanupIds: false,
            },
          },
        },
      ],
    },
  },
});
```

The merged `svgoConfig` will be:

```ts
const mergedSvgoConfig = {
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          removeViewBox: true,
          cleanupIds: false,
        },
      },
    },
    'prefixIds',
  ],
};
```

### svgrOptions.exportType

Set the export type of SVG React components.

* **Type:** `'default' | 'named'`
* **Default:** `undefined`

`exportType` can be set as:

* `default`: use default export.
* `named`: use `ReactComponent` named export.

For example, set the default export of SVG file as a React component:

```ts
pluginSvgr({
  svgrOptions: {
    exportType: 'default',
  },
});
```

Then import the SVG, you'll get a React component instead of a URL:

```ts
import Logo from './logo.svg';

console.log(Logo); // => React Component
```

At this time, you can also specify the `?url` query to import the URL, for example:

```ts
import logo from './logo.svg?url';

console.log(logo); // => asset url
```

:::tip
When `svgrOptions.exportType` is set to `'default'`, the named imports (ReactComponent) cannot be used.
:::

### mixedImport

* **Type:** `boolean`
* **Default:** `false`

Whether to enable mixed import, allowing to use default import and named import at the same time.

Mixed import is usually used with `svgrOptions.exportType: 'named'`, for example:

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

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

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

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

:::tip
When `mixedImport` is enabled, `svgrOptions.exportType` defaults to `'named'` if not explicitly configured.
:::

#### Limitations

We recommend using `?react` to convert an SVG into a React component rather than relying on mixed imports, which have the following limitations:

1. Increased bundle size: Mixed import causes a single SVG module to be compiled into two types of code (even if some exports are not used), which will increase the bundle size.
2. Slow down compiling: Mixed import will cause extra compilation overhead. Even if the ReactComponent export is not used in the code, the SVG file will still be compiled by SVGR. And SVGR is based on Babel, which has a high performance overhead.

### query

* **Type:** `RegExp`
* **Default:** `/react/`

Used to custom the query suffix to match SVGR transformation.

For example, if you need to match import paths with the `?svgr` suffix:

```ts
pluginSvgr({
  query: /svgr/,
});
```

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

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

### exclude

* **Type:** [Rspack.RuleSetCondition](https://rspack.rs/config/module-rules#condition)
* **Default:** `undefined`

Exclude some SVG files, they will not be transformed by SVGR.

For example, if a project includes `a.svg` and `b.svg`, you can add `b.svg` to exclude:

```ts
pluginSvgr({
  svgrOptions: {
    exportType: 'default',
  },
  exclude: /b\.svg/,
});
```

When imported, `a.svg` will be transformed into a React component, while `b.svg` will be treated as a regular static asset:

```ts title="src/index.ts"
import component from './a.svg';
import url from './b.svg';

console.log(component); // => React component
console.log(url); // => resource url
```

### excludeImporter

* **Type:** [Rspack.RuleSetCondition](https://rspack.rs/config/module-rules#condition)
* **Default:** `undefined`

Exclude some modules, the SVGs imported by these modules will not be transformed by SVGR.

For example, if your project contains `page-a/index.ts` and `page-b/index.ts`, you can add `page-b` to excludeImporter:

```ts
pluginSvgr({
  svgrOptions: {
    exportType: 'default',
  },
  excludeImporter: /\/page-b\/index\.ts/,
});
```

* SVGs referenced in page-a will be transformed to React components:

```ts title="page-a/index.ts"
import Logo from './logo.svg';

console.log(Logo); // => React component
```

* SVGs referenced in page-b will be treated as static assets:

```ts title="page-b/index.ts"
import url from './logo.svg';

console.log(url); // => Resource url
```

:::tip
The query in the module path has a higher priority than `exclude` and `excludeImporter`. For example, if a module is excluded, adding `?react` can still make it transformed by SVGR.
:::

## Type declaration

When you reference an SVG asset in TypeScript code, TypeScript may prompt that the module is missing a type definition:

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

To fix this, add type declarations for the SVG assets by creating a `src/env.d.ts` file and adding the declarations below.

* By default, you can add the following type declarations:

```ts
declare module '*.svg' {
  const content: string;
  export default content;
}
declare module '*.svg?react' {
  const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
  export default ReactComponent;
}
```

* If the value of `svgrOptions.exportType` is `'default'`, set the type declaration to:

```ts
declare module '*.svg' {
  const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
  export default ReactComponent;
}
declare module '*.svg?react' {
  const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
  export default ReactComponent;
}
```

* If the value of `svgrOptions.exportType` is `'named'`, set the type declaration to:

```ts
declare module '*.svg' {
  export const ReactComponent: React.FunctionComponent<
    React.SVGProps<SVGSVGElement>
  >;
}
declare module '*.svg?react' {
  const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
  export default ReactComponent;
}
```

* If the value of `svgrOptions.exportType` is `'named'`, and `mixedImport` is enabled, set the type declaration to:

```ts
declare module '*.svg' {
  export const ReactComponent: React.FunctionComponent<
    React.SVGProps<SVGSVGElement>
  >;
  const content: string;
  export default content;
}
declare module '*.svg?react' {
  const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
  export default ReactComponent;
}
```

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

---

# Source: https://rsbuild.dev/plugins/list/plugin-vue.md

# Vue plugin

import { SourceCode } from '@theme';

<SourceCode href="https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-vue" />

The Vue plugin provides support for Vue 3 SFC (Single File Components). The plugin internally integrates [vue-loader](https://vue-loader.vuejs.org/) v17.

:::tip
For Vue 3 JSX / TSX syntax, please use the [Vue JSX plugin](https://github.com/rstackjs/rsbuild-plugin-vue-jsx).
:::

## Quick start

### Install plugin

Install the plugin with this command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-vue -D" />

### Register plugin

Register the plugin in your `rsbuild.config.ts` file:

```ts title="rsbuild.config.ts"
import { pluginVue } from '@rsbuild/plugin-vue';

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

After registering the plugin, you can import `*.vue` SFC files in your code.

## Options

Customize Vue compilation behavior with these options:

### vueLoaderOptions

Options passed to `vue-loader`. See the [vue-loader documentation](https://vue-loader.vuejs.org/) for detailed usage.

* **Type:** `VueLoaderOptions`
* **Default:**

```js
const defaultOptions = {
  compilerOptions: {
    preserveWhitespace: false,
  },
  experimentalInlineMatchResource: true,
};
```

* **Example:**

```ts
pluginVue({
  vueLoaderOptions: {
    hotReload: false,
  },
});
```

### splitChunks

When [chunkSplit.strategy](/config/performance/chunk-split.md) set to `split-by-experience`, Rsbuild will automatically split `vue` and `router` related packages into separate chunks by default:

* `lib-vue.js`: includes `vue`, `vue-loader`, and their sub-dependencies (`@vue/shared`, `@vue/reactivity`, `@vue/runtime-dom`, `@vue/runtime-core`).
* `lib-router.js`: includes `vue-router`.

This option is used to control this behavior and determine whether the `vue` and `router` related packages need to be split into separate chunks.

* **Type:**

```ts
type SplitVueChunkOptions = {
  vue?: boolean;
  router?: boolean;
};
```

* **Default:**

```ts
const defaultOptions = {
  vue: true,
  router: true,
};
```

* **Example:**

```ts
pluginVue({
  splitChunks: {
    vue: false,
    router: false,
  },
});
```

### test

Customize the matching rule for Vue Single File Components (SFC).

* **Type:** [Rspack.RuleSetCondition](https://rspack.rs/config/module-rules#condition)
* **Default:** `/\.vue$/`
* **Version:** `>= 1.2.1`

This option allows you to extend the Vue plugin to handle additional file types. For example, you can first use a plugin or loader to transform `.md` files into Vue components, then configure the `test` option in the Vue plugin to match both `.vue` and `.md` files:

```ts
pluginVue({
  test: /\.(vue|md)$/,
});
```

## FAQ

### /deep/ selector causes compilation error

`/deep/` is a deprecated usage as of Vue v2.7. Since it is not a valid CSS syntax, CSS compilation tools like Lightning CSS will fail to compile it.

You can use `:deep()` instead. See [Vue - Deep Selectors](https://vuejs.org/api/sfc-css-features.html#deep-selectors) for more details.

```html
<style scoped>
  .a :deep(.b) {
    /* ... */
  }
</style>
```

> You can also refer to [Vue - RFC 0023](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0023-scoped-styles-changes.md) for more details.

---

# Source: https://rsbuild.dev/config/plugins.md

# plugins

Registers Rsbuild plugins.

* **Type:**

```ts
type Falsy = false | null | undefined;

type RsbuildPlugins = (
  | RsbuildPlugin
  | Falsy
  | Promise<RsbuildPlugin | Falsy | RsbuildPlugins>
  | RsbuildPlugins
)[];
```

* **Default:** `undefined`

> Please check out the [Plugin List](/plugins/list/index.md) page to discover all available plugins.

## Example

For example, to register the [Sass plugin](/plugins/list/plugin-sass.md) in Rsbuild:

* Installing the plugin:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsbuild/plugin-sass -D" />

* Registering the plugin:

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

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

## Execution order

By default, plugins run in the order they appear in the `plugins` array. Built-in Rsbuild plugins always execute before user-defined plugins.

If a plugin specifies ordering controls such as the `enforce` property, the final execution sequence will be adjusted accordingly. See the [`enforce` property](/plugins/dev/core.md#enforce-property) for details.

## Conditional registration

Falsy values in the `plugins` array are ignored, which lets you register plugins conditionally:

```ts title="rsbuild.config.ts"
const isProd = process.env.NODE_ENV === 'production';

export default defineConfig({
  plugins: [isProd && somePlugin()],
});
```

## Async plugins

If the plugin is async, you can return a `Promise` object or use an `async` function, and Rsbuild will automatically wait for the `Promise` to be resolved:

```ts title="rsbuild.config.ts"
async function myPlugin() {
  await someAsyncOperation();
  return {
    name: 'my-plugin',
    setup(api) {
      // ...
    },
  };
}

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

## Nested plugins

Rsbuild also supports nested plugins. You can pass an array that contains multiple plugins, similar to a plugin preset. This is useful for complex features that combine several plugins, such as framework integrations.

```ts title="rsbuild.config.ts"
function myPlugin() {
  return [fooPlugin(), barPlugin()];
}

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

## Local plugins

If your local code repository contains Rsbuild plugins, you can import them using relative paths.

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

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

## Plugin options

If a plugin provides custom options, you can pass the configurations through the plugin function's parameters.

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

export default defineConfig({
  plugins: [
    pluginStylus({
      stylusOptions: {
        lineNumbers: false,
      },
    }),
  ],
});
```

## Plugin registration phase

Plugin registration only runs during the Rsbuild initialization phase. You cannot dynamically add other plugins within a plugin through the plugin API:

```ts title="rsbuild.config.ts"
// Wrong
function myPlugin() {
  return {
    setup(api) {
      api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) => {
        return mergeRsbuildConfig(config, {
          plugins: [fooPlugin(), barPlugin()], // <- this will not work
        });
      });
    },
  };
}

// Correct
function myPlugin() {
  return [fooPlugin(), barPlugin()];
}

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

## Rspack plugins

The `plugins` option is used to register Rsbuild plugins. If you need to register Rspack or webpack plugins, please use [tools.rspack](/config/tools/rspack.md).

```ts title="rsbuild.config.ts"
export default {
  // Rsbuild Plugins
  plugins: [pluginStylus()],
  tools: {
    rspack: {
      // Rspack or webpack Plugins
      plugins: [new SomeWebpackPlugin()],
    },
  },
};
```

## Unplugin

[unplugin](https://github.com/unjs/unplugin) is a unified plugin system for various build tools. You can use plugins implemented based on unplugin in Rsbuild, just import the `/rspack` subpath of the plugin and register it via [tools.rspack](/config/tools/rspack.md).

Here is an example of using [unplugin-vue-components](https://npmjs.com/package/unplugin-vue-components):

```ts title="rsbuild.config.ts"
import { defineConfig } from '@rsbuild/core';
import { pluginVue } from '@rsbuild/plugin-vue';
import Components from 'unplugin-vue-components/rspack';

export default defineConfig({
  plugins: [pluginVue()],
  tools: {
    rspack: {
      plugins: [
        Components({
          // options
        }),
      ],
    },
  },
});
```

:::tip
When you use the transform hook in unplugin, also use the `transformInclude` hook to target specific modules. If the transform hook matches an `.html` module, it replaces the default EJS transform from the [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin).
:::

> Please ensure that the version of `unplugin` package is >= v1.6.0.

---

# Source: https://rsbuild.dev/config/output/polyfill.md

# output.polyfill

* **Type:** `'entry' | 'usage' | 'off'`
* **Default:** `'off'`

Controls the polyfill injection mode.

> See [Polyfill Mode](/guide/advanced/browser-compatibility.md#polyfill-mode) for more details.

## Optional value

### usage

With `output.polyfill` set to `'usage'`, Rsbuild injects polyfills based on the APIs used in each file. This provides optimal bundle size by including only needed polyfills.

```ts title="rsbuild.config.ts"
export default {
  output: {
    polyfill: 'usage',
  },
};
```

### entry

With `output.polyfill` set to `'entry'`, Rsbuild injects polyfills in each entry file. This ensures all polyfills are available but may increase bundle size.

```ts title="rsbuild.config.ts"
export default {
  output: {
    polyfill: 'entry',
  },
};
```

:::tip
It should be noted that when you bundle page with [Web Workers](/guide/basic/web-workers.md), the `entry` mode is not applicable to Web Workers because the Web Workers thread is isolated from the main thread (page), and the `usage` mode can be used at this time.
:::

### off

With `output.polyfill` set to `'off'`, Rsbuild doesn't inject polyfills. You need to handle code compatibility yourself.

```ts title="rsbuild.config.ts"
export default {
  output: {
    polyfill: 'off',
  },
};
```

---

# Source: https://rsbuild.dev/config/server/port.md

# server.port

* **Type:** `number`
* **Default:** `3000`

Sets the port number for the Rsbuild server.

By default, the Rsbuild server listens on port `3000` and automatically increments the port when it's occupied. Enable [server.strictPort](/config/server/strict-port.md) to throw an error instead of incrementing the port when it's occupied.

The Rsbuild CLI provides a [--port](/guide/basic/cli.md#rsbuild-dev) option to set the port number. The `--port` option takes priority over the `server.port` config.

```bash
npx rsbuild dev --port 8080
```

## Example

Set the port to `8080`:

```ts title="rsbuild.config.ts"
export default {
  server: {
    port: 8080,
  },
};
```

Set different port numbers for development and preview servers:

```ts title="rsbuild.config.ts"
export default {
  server: {
    port: process.env.NODE_ENV === 'development' ? 3000 : 8080,
  },
};
```

---

# Source: https://rsbuild.dev/config/tools/postcss.md

# tools.postcss

* **Type:** `Object | Function`
* **Default:**

```js
const defaultOptions = {
  postcssOptions: {
    config: false,
    sourceMap: rsbuildConfig.output.sourceMap.css,
  },
};
```

Rsbuild integrates PostCSS by default. You can configure [postcss-loader](https://github.com/webpack/postcss-loader) through `tools.postcss`.

## Function type

When `tools.postcss` is a function, the default options will be passed in as the first parameter. You can directly modify this object or return a new object as the final options. For example:

For example, to add a PostCSS plugin, you can call the [addPlugins](#addplugins) utility function:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    postcss: (opts, { addPlugins }) => {
      addPlugins(require('postcss-px-to-viewport'));
    },
  },
};
```

To pass parameters to the PostCSS plugin, call the PostCSS plugin as a function:

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

You can also modify the default `postcss-loader` options:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    postcss: (opts) => {
      opts.sourceMap = false;
    },
  },
};
```

`tools.postcss` can return a config object and completely replace the default config:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    postcss: () => {
      return {
        postcssOptions: {
          plugins: [require('postcss-px-to-viewport')],
        },
      };
    },
  },
};
```

## Object type

When `tools.postcss` is an object, it will be merged with the default configuration using `Object.assign`. Note that `Object.assign` is a shallow copy and will completely overwrite the built-in `presets` or `plugins` array, please use it with caution.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    postcss: {
      // As `Object.assign` is used, the default postcssOptions will be overwritten.
      postcssOptions: {
        plugins: [require('postcss-px-to-viewport')],
      },
    },
  },
};
```

## Utils

### addPlugins

* **Type:**

```ts
type AddPlugins = (
  plugins: PostCSSPlugin | PostCSSPlugin[],
  options?: {
    /**
     * Controls where the plugin is placed relative to the existing PostCSS plugins.
     * @default 'post'
     */
    order?: 'pre' | 'post';
  },
) => void;
```

For adding additional PostCSS plugins, You can pass in a single PostCSS plugin, or an array of PostCSS plugins.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    postcss: (config, { addPlugins }) => {
      // Add a PostCSS Plugin
      addPlugins(require('postcss-preset-env'));
      // Add multiple PostCSS Plugins
      addPlugins([require('postcss-preset-env'), require('postcss-import')]);
    },
  },
};
```

To add plugins before the existing plugins, set `order` option to `pre`:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    postcss: (config, { addPlugins }) => {
      addPlugins(require('postcss-preset-env'), { order: 'pre' });
    },
  },
};
```

## Practice

### Multiple PostCSS options

`tools.postcss.postcssOptions` can be set to a function, which receives the Rspack's `loaderContext` as a parameter. This allows you to use different PostCSS options for different file paths.

For example, use `postcss-plugin-a` for file paths containing `foo`, and use `postcss-plugin-b` for other file paths:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    postcss: {
      postcssOptions: (loaderContext) => {
        if (/foo/.test(loaderContext.resourcePath)) {
          return {
            plugins: [require('postcss-plugin-a')],
          };
        }
        return {
          plugins: [require('postcss-plugin-b')],
        };
      },
    },
  },
};
```

:::tip
If the project contains a `postcss.config.*` config file, its content will be merged with `tools.postcss.postcssOptions`, and the latter's priority is higher. The `plugins` array will be merged into a single array.
:::

## Notes

### PostCSS version

Rsbuild uses the PostCSS v8. When you use third-party PostCSS plugins, please pay attention to whether the PostCSS version is compatible. Some legacy plugins may not work in PostCSS v8.

### PostCSS config loading

Rsbuild uses [postcss-load-config](https://github.com/postcss/postcss-load-config) to load PostCSS config files and merge them with the default config.

Rsbuild internally sets the `postcss-loader`'s `postcssOptions.config` option to `false` to avoid loading config files repeatedly.

## Version history

| Version | Changes                                         |
| ------- | ----------------------------------------------- |
| v1.6.8  | Added `order` option to the `addPlugins` method |

---

# Source: https://rsbuild.dev/config/source/pre-entry.md

# source.preEntry

* **Type:** `string | string[]`
* **Default:** `undefined`

Add a script before the entry file of each page. This script will be executed before the page code. Use this to execute global logic, such as injecting polyfills, setting global styles, etc.

## Add a single script

First create a `src/polyfill.ts` file:

```js
console.log('I am a polyfill');
```

Then configure `src/polyfill.ts` to `source.preEntry`:

```ts title="rsbuild.config.ts"
export default {
  source: {
    preEntry: './src/polyfill.ts',
  },
};
```

Re-run the compilation and visit any page. You can see that the code in `src/polyfill.ts` has been executed, and `I am a polyfill` is logged in the console.

## Add global style

You can also configure global styles using `source.preEntry`. This CSS code will be loaded earlier than the page code, such as introducing a `normalize.css` file:

```ts title="rsbuild.config.ts"
export default {
  source: {
    preEntry: './src/normalize.css',
  },
};
```

## Add multiple scripts

You can add multiple scripts by setting `preEntry` to an array, and they will be executed in array order:

```ts title="rsbuild.config.ts"
export default {
  source: {
    preEntry: ['./src/polyfill-a.ts', './src/polyfill-b.ts'],
  },
};
```

---

# Source: https://rsbuild.dev/guide/framework/preact.md

# Preact

In this document, you will learn how to build a Preact application using Rsbuild.

## Create a Preact application

Use [create-rsbuild](/guide/start/quick-start.md#create-an-rsbuild-application) to create a Preact application with Rsbuild. Run the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs
  command={{
  npm: 'npm create rsbuild@latest',
  yarn: 'yarn create rsbuild',
  pnpm: 'pnpm create rsbuild@latest',
  bun: 'bun create rsbuild@latest',
}}
/>

Then select `Preact` when prompted to "Select framework".

## Use Preact in an existing project

To compile Preact, you need to register the Rsbuild [Preact Plugin](/plugins/list/plugin-preact.md). The plugin will automatically add the necessary configuration for Preact builds.

For example, register in `rsbuild.config.ts`:

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

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

## Preact Fast Refresh

Preact plugin uses [@preact/prefresh](https://github.com/preactjs/prefresh) and [@rspack/plugin-preact-refresh](https://github.com/rstackjs/rspack-plugin-preact-refresh) to hot reload Preact components.

### Component recognition

Prefresh needs to be able to recognize your components. This means that components should
start with a capital letter and hooks should start with `use` followed by a capital letter.
This allows the plugin to effectively recognize these.

Do note that a component as seen below is not named:

```jsx
export default () => {
  return <p>Want to refresh</p>;
};
```

Instead do:

```jsx
const MyComponent = () => {
  return <p>Want to refresh</p>;
};

export default MyComponent;
```

When you are working with HOC's be sure to lift up the `displayName` so the plugin can
recognize it as a component.

---

# Source: https://rsbuild.dev/config/performance/preconnect.md

# performance.preconnect

* **Type:**

```ts
type Preconnect =
  | Array<
      | string
      | {
          href: string;
          crossorigin?: boolean;
        }
    >
  | undefined;
```

* **Default:** `undefined`

Injects [`<link rel="preconnect">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect) tags into the HTML file.

## When to use

The `preconnect` keyword for the rel attribute of the `<link>` element is a hint to browsers that the user is likely to need resources from the target resource's origin, and therefore the browser can likely improve the user experience by preemptively initiating a connection to that origin.

Preconnecting speeds up future loads from a given origin by preemptively performing part or all of the handshake (DNS+TCP for HTTP, and DNS+TCP+TLS for HTTPS origins).

`<link rel="preconnect">` will provide a benefit to any future cross-origin HTTP request, navigation or subresource. It has no benefit on same-origin requests because the connection is already open.

If a page needs to make connections to many third-party domains, preconnecting them all can be counterproductive. The `<link rel="preconnect">` hint is best used for only the most critical connections. For the others, just use [`<link rel="dns-prefetch">`](/config/performance/dns-prefetch.md) to save time on the first step — the DNS lookup.

## Example

```ts title="rsbuild.config.ts"
export default {
  performance: {
    preconnect: ['https://example.com/'],
  },
};
```

The generated HTML tag is:

```html
<link ref="preconnect" href="https://example.com" />
```

## Options

### href

* **Type:** `string`
* **Default:** `undefined`

Specify the URL to preconnect to.

```ts title="rsbuild.config.ts"
export default {
  performance: {
    // Equivalent to `preconnect: ['https://example.com/'],`
    preconnect: [
      {
        href: 'https://example.com/',
      },
    ],
  },
};
```

### crossorigin

* **Type:** `boolean`
* **Default:** `false`

Specify whether to add the `crossorigin` attribute.

```ts title="rsbuild.config.ts"
export default {
  performance: {
    preconnect: [
      {
        href: 'https://example.com/',
        crossorigin: true,
      },
    ],
  },
};
```

The generated HTML tag is:

```html
<link rel="preconnect" href="https://example.com" crossorigin />
```

:::tip
Refer to this [link](https://webmasters.stackexchange.com/questions/89466/when-should-i-use-the-crossorigin-attribute-on-a-preconnect-link) to understand the use cases of the `crossorigin` attribute.
:::

---

# Source: https://rsbuild.dev/config/performance/print-file-size.md

# performance.printFileSize

* **Type:**

```ts
type PrintFileSizeOptions =
  | boolean
  | {
      total?: boolean | Function;
      detail?: boolean;
      compressed?: boolean;
      include?: (asset: PrintFileSizeAsset) => boolean;
      exclude?: (asset: PrintFileSizeAsset) => boolean;
      diff?: boolean;
    };
```

* **Default:** `true`

Whether to print the file sizes after production build.

## Default outputs

The default output log is as follows:

```
File (web)                              Size        Gzip
dist/static/js/lib-react.b0714b60.js    140.4 kB    45.0 kB
dist/static/js/index.f3fde9c7.js        1.9 kB      0.97 kB
dist/index.html                         0.39 kB     0.25 kB
dist/static/css/index.2960ac62.css      0.35 kB     0.26 kB

                               Total:   143.0 kB    46.3 kB
```

## Disable outputs

If you do not want to print any information, you can disable it by setting `printFileSize` to `false`:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    printFileSize: false,
  },
};
```

## Options

You can customize the output format through the options.

### total

* **Type:**

```ts
type Total =
  | boolean
  | ((params: {
      environmentName: string;
      distPath: string;
      assets: PrintFileSizeAsset[];
      totalSize: number;
      totalGzipSize: number;
    }) => string);
```

* **Default:** `true`

Whether to output the total size of all static assets, or provide a function to customize the output format of the total size.

When set to `false`, the total size will not be output:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    printFileSize: {
      total: false,
    },
  },
};
```

:::tip
If the current build only generates one static asset, the total size will not be printed.
:::

When set to a function, you can customize the total size output format:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    printFileSize: {
      total: ({ distPath, assets, totalSize }) => {
        return `Generated ${assets.length} files in ${distPath}, the total size is ${(totalSize / 1000).toFixed(1)} kB.`;
      },
    },
  },
};
```

Function parameters:

* `environmentName`: The unique name of the current environment, used to distinguish and locate the environment
* `distPath`: The output directory relative to the project root
* `assets`: Array of static assets, each containing `name` and `size` properties
* `totalSize`: Total size of all static assets in bytes
* `totalGzipSize`: Total gzip-compressed size of all static assets in bytes

### detail

* **Type:** `boolean`
* **Default:** `true`

Whether to output the size of each static asset.

If you do not need to view the size of each static asset, you can set `detail` to false. In this case, only the total size will be output:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    printFileSize: {
      detail: false,
    },
  },
};
```

### compressed

* **Type:** `boolean`
* **Default:** `false` when [output.target](/config/output/target.md) is `node`, otherwise `true`

Whether to output the gzip-compressed size of each static asset.

If you do not need to view the gzipped size, you can set `compressed` to false. This can save some gzip computation time for large projects:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    printFileSize: {
      compressed: false,
    },
  },
};
```

:::tip

* This data is only for reference to the size after gzip compression. Rsbuild does not enable gzip compression for static assets. Usually, you need to enable gzip compression on the server side, for example, using the [gzip module](https://nginx.org/en/docs/http/ngx_http_gzip_module.html) of nginx.
* For non-compressible assets (such as images), the gzip size will not be shown in the detailed list, but their original size will be included in the total gzip size calculation.

:::

### include

* **Type:**

```ts
type PrintFileSizeAsset = {
  /**
   * The name of the static asset.
   * @example 'index.html', 'static/js/index.[hash].js'
   */
  name: string;
  /**
   * The size of the static asset in bytes.
   */
  size: number;
};
type Include = (asset: PrintFileSizeAsset) => boolean;
```

* **Default:** `undefined`

A filter function to determine which static assets to print.

If returned `false`, the static asset will be excluded and not included in the total size or detailed size.

For example, only output static assets larger than 10 kB:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    printFileSize: {
      include: (asset) => asset.size > 10 * 1000,
    },
  },
};
```

Or only output `.js` files larger than 10 kB:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    printFileSize: {
      include: (asset) => /\.js$/.test(asset.name) && asset.size > 10 * 1000,
    },
  },
};
```

### exclude

* **Type:**

```ts
type Exclude = (asset: PrintFileSizeAsset) => boolean;
```

* **Default:** `(asset) => /\.(?:map|LICENSE\.txt|d\.ts)$/.test(asset.name)`

A filter function to determine which static assets to exclude. If both `include` and `exclude` are set, `exclude` will take precedence.

Rsbuild defaults to excluding source map, license files, and `.d.ts` type files, as these files do not affect page load performance.

For example, exclude `.html` files in addition to the default:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    printFileSize: {
      exclude: (asset) =>
        /\.(?:map|LICENSE\.txt|d\.ts)$/.test(asset.name) ||
        /\.html$/.test(asset.name),
    },
  },
};
```

### diff

* **Type:** `boolean`
* **Default:** `false`

Controls whether file size differences are displayed relative to the previous build.

When this option is enabled, Rsbuild records a snapshot of all output file sizes after each build. On subsequent builds, Rsbuild compares the current sizes against the previous snapshot and shows the change inline in parentheses.

To enable diff output:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    printFileSize: {
      diff: true,
    },
  },
};
```

On the second build, the output begins to include inline size deltas:

```
File (web)                              Size                  Gzip
dist/static/js/lib-react.b0714b60.js    140.4 kB (+2.1 kB)    45.0 kB (+0.5 kB)
dist/static/js/index.f3fde9c7.js        1.9 kB (-0.3 kB)      0.97 kB (-0.1 kB)
dist/static/css/index.2960ac62.css      0.35 kB (+0.35 kB)    0.26 kB (+0.26 kB)

                               Total:   143.0 kB (+2.15 kB)   46.3 kB (+0.66 kB)
```

* Increases are highlighted in red with a `+` prefix
* Decreases are highlighted in green with a `-` prefix
* Files with no change omit the diff indicator

:::tip
Snapshots are stored at `<root>/node_modules/.cache/rsbuild/file-sizes-[hash].json`, where \[hash] is derived from the Rsbuild configuration file path.
:::

## Version history

| Version | Changes             |
| ------- | ------------------- |
| v1.6.13 | Added `diff` option |

---

# Source: https://rsbuild.dev/config/server/print-urls.md

# server.printUrls

* **Type:**

```ts
type Routes = Array<{
  entryName: string;
  pathname: string;
}>;

type PrintUrls =
  | boolean
  | ((params: {
      urls: string[];
      port: number;
      routes: Routes;
      protocol: string;
    }) => (string | { url: string; label?: string })[] | void);
```

* **Default:** `true`

Controls whether and how server URLs are printed when the server starts.

By default, when you start the dev server or preview server, Rsbuild will print the following logs:

```
  ➜ Local:    http://localhost:3000
  ➜ Network:  http://192.168.0.1:3000
```

## Custom logging

`server.printUrls` can be set to a function, with parameters including `port`, `protocol`, `urls` and `routes`.

### Modify URL

If the `printUrls` function returns a URLs array, Rsbuild prints these URLs to the terminal in the default format:

```ts title="rsbuild.config.ts"
export default {
  server: {
    printUrls({ urls }) {
      return urls.map((url) => `${url}/base/`);
    },
  },
};
```

Output:

```
  ➜ Local:    http://localhost:3000/base/
  ➜ Network:  http://192.168.0.1:3000/base/
```

You may also return an array containing both strings and objects. Each object may include an optional `label` that overrides the default `Local:` or `Network:` label; if omitted, the default label is used:

```ts title="rsbuild.config.ts"
export default {
  server: {
    printUrls({ urls }) {
      return urls.concat({ url: 'https://example.com/', label: 'Custom:' });
    },
  },
};
```

Output:

```
  ➜ Local:    http://localhost:3000/
  ➜ Network:  http://192.168.0.1:3000/
  ➜ Custom:   https://example.com/
```

### Fully customizable

If the `printUrls` function does not return a value, Rsbuild will not print the server's URL addresses. You can customize the log content based on the parameters and output it to the terminal yourself.

```ts title="rsbuild.config.ts"
export default {
  server: {
    printUrls({ urls, port, protocol }) {
      console.log(urls); // ['http://localhost:3000', 'http://192.168.0.1:3000']
      console.log(port); // 3000
      console.log(protocol); // 'http' or 'https'
    },
  },
};
```

### MPA output

If the current project contains multiple pages, you can generate a separate URL for each page based on the `routes` parameter.

For example, when the project contains two pages, `index` and `detail`, the content of the `routes` would be:

```ts title="rsbuild.config.ts"
export default {
  server: {
    printUrls({ routes }) {
      /**
       * [
       *   { entryName: 'index', pathname: '/' },
       *   { entryName: 'detail', pathname: '/detail' }
       * ]
       */
      console.log(routes);
    },
  },
};
```

## Disable output

Setting `server.printUrls` to `false` will prevent Rsbuild from printing the server URLs.

```ts title="rsbuild.config.ts"
export default {
  server: {
    printUrls: false,
  },
};
```

### HTML disabled

If [tools.htmlPlugin](/config/tools/html-plugin.md) is set to `false`, Rsbuild will not generate HTML files or output the server URL.

However, you can still print the server URLs using the `server.printUrls` function, which has a higher priority.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    htmlPlugin: false,
  },
  server: {
    printUrls: ({ port }) => [`http://localhost:${port}`],
  },
};
```

Output:

```
  ➜ Local:    http://localhost:3000
```

## Version history

| Version | Changes                    |
| ------- | -------------------------- |
| v1.5.17 | Support for custom `label` |

---

# Source: https://rsbuild.dev/config/performance/profile.md

# performance.profile

* **Type:** `boolean`
* **Default:** `false`

Whether to capture timing information for each module, the same as the [profile](https://rspack.rs/config/other-options#profile) config of Rspack.

When enabled:

* Rsbuild will automatically generate a `dist/stats.json` file through [bundle analyzer](https://github.com/webpack/webpack-bundle-analyzer).
* Rspack will include build-time information when generating stats.json or other statistics files.

## Example

```ts title="rsbuild.config.ts"
export default {
  performance: {
    profile: true,
  },
};
```

When enabled, Rspack generates a JSON file with statistics about modules, including timing information for each module.

## Guide

Please refer to the [Build profiling](/guide/debug/build-profiling.md) page for more methods to analyze build performance.

---

# Source: https://rsbuild.dev/config/dev/progress-bar.md

# dev.progressBar

* **Type:**

```ts
type ProgressBar =
  | boolean
  | {
      id?: string;
    };
```

* **Default:** `false`

Whether to render progress bars to display the build progress.

:::tip
In `@rsbuild/core < 1.4.0`, the progress bar is enabled by default in production mode.
:::

## Example

Enable the progress bar:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    progressBar: true,
  },
};
```

Disable the progress bar:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    progressBar: false,
  },
};
```

Only enable the progress bar in development mode:

```ts title="rsbuild.config.ts"
const isDev = process.env.NODE_ENV === 'development';

export default {
  dev: {
    progressBar: isDev,
  },
};
```

## Customize the progress bar `id`

To modify the text displayed on the left side of the progress bar, set the `id` option:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    progressBar: {
      id: 'Some Text',
    },
  },
};
```

When using [environments](/guide/advanced/environments.md), you can set different progress bar `id` for different environments:

```ts title="rsbuild.config.ts"
export default {
  environments: {
    web: {
      dev: {
        progressBar: {
          id: 'Web',
        },
      },
    },
    node: {
      output: {
        target: 'node',
      },
      dev: {
        progressBar: {
          id: 'Node',
        },
      },
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/server/proxy.md

# server.proxy

* **Type:**

```ts
type ProxyConfig =
  | Record<string, string | ProxyOptions>
  | ProxyOptions[]
  | ProxyOptions;
```

* **Default:** `undefined`

Configure proxy rules for the dev server or preview server to proxy requests to the specified service.

## Example

### Basic usage

```ts title="rsbuild.config.ts"
export default {
  server: {
    proxy: {
      // http://localhost:3000/api -> http://localhost:3000/api
      // http://localhost:3000/api/foo -> http://localhost:3000/api/foo
      '/api': 'http://localhost:3000',
    },
  },
};
```

A request to `/api/users` will now proxy the request to `http://localhost:3000/api/users`.

You can also proxy to an online domain name, such as:

```ts title="rsbuild.config.ts"
export default {
  server: {
    proxy: {
      // http://localhost:3000/api -> https://nodejs.org/api
      // http://localhost:3000/api/foo -> https://nodejs.org/api/foo
      '/api': 'https://nodejs.org',
    },
  },
};
```

### Path rewrite

If you do not want `/api` to be passed along, we need to rewrite the path:

```ts title="rsbuild.config.ts"
export default {
  server: {
    proxy: {
      // http://localhost:3000/api -> http://localhost:3000
      // http://localhost:3000/api/foo -> http://localhost:3000/foo
      '/api': {
        target: 'http://localhost:3000',
        pathRewrite: { '^/api': '' },
      },
    },
  },
};
```

### Proxy WebSocket

To proxy WebSocket requests, set `ws` to `true`:

```ts title="rsbuild.config.ts"
export default {
  server: {
    proxy: {
      '/rsbuild-hmr': {
        target: 'http://localhost:3000', // will proxy to ws://localhost:3000/rsbuild-hmr
        ws: true,
      },
    },
  },
};
```

## Options

The Rsbuild server proxy uses the [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware/tree/2.x) package. Check out its documentation for more advanced usage.

The full type definition of Rsbuild server proxy is:

```ts
import type { Options as HttpProxyOptions } from 'http-proxy-middleware';

type Filter = string | string[] | ((pathname: string, req: Request) => boolean);

type ProxyOptions = HttpProxyOptions & {
  bypass?: (
    req: IncomingMessage,
    res: ServerResponse,
    proxyOptions: ProxyOptions,
  ) => MaybePromise<string | undefined | null | boolean>;
  context?: Filter;
};

type ProxyConfig =
  | ProxyOptions
  | ProxyOptions[]
  | Record<string, string>
  | Record<string, ProxyOptions>;
```

In addition to the `http-proxy-middleware` options, Rsbuild also supports the `bypass` and `context` options.

### bypass

Sometimes you don't want to proxy everything. You can bypass the proxy based on the return value of a `bypass` function.

In the function, you have access to the request, response, and proxy options.

* Return `null` or `undefined` to continue processing the request with proxy.
* Return `true` to continue processing the request without proxy.
* Return `false` to produce a 404 error for the request.
* Return a path to serve from, instead of continuing to proxy the request.
* Return a Promise to handle the request asynchronously.

For example, for a browser request, you want to serve an HTML page, but for an API request, you want to proxy it. You could configure it like this:

```ts title="rsbuild.config.ts"
export default {
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        bypass(req, res, proxyOptions) {
          if (req.headers.accept.indexOf('html') !== -1) {
            console.log('Skipping proxy for browser request.');
            return '/index.html';
          }
        },
      },
    },
  },
};
```

### context

Used to proxy multiple specified paths to the same target.

```ts title="rsbuild.config.ts"
export default {
  server: {
    proxy: [
      {
        context: ['/auth', '/api'],
        target: 'http://localhost:3000',
      },
    ],
  },
};
```

---

# Source: https://rsbuild.dev/config/server/public-dir.md

# server.publicDir

* **Type:**

```ts
type PublicDirOptions = {
  name?: string;
  copyOnBuild?: boolean | 'auto';
  watch?: boolean;
};
type PublicDir = false | PublicDirOptions | PublicDirOptions[];
```

* **Default:**

```js
const defaultValue = {
  name: 'public',
  copyOnBuild: 'auto',
  watch: false,
};
```

By default, Rsbuild uses the `public` directory for serving public assets. Files in this directory are served at [server.base](/config/server/base.md) path (default `/`).

> Related document: [Public Folder](/guide/basic/static-assets.md#public-folder).

## Options

### name

* **Type:** `string`
* **Default:** `'public'`

The name of the public directory. The value of `name` can be set to a relative path or an absolute path. Relative path will be resolved relative to the project root directory.

* Relative path example:

```ts title="rsbuild.config.ts"
export default {
  server: {
    publicDir: {
      name: '../some-public',
    },
  },
};
```

* Absolute path example:

```ts
import path from 'node:path';

export default {
  server: {
    publicDir: {
      name: path.join(__dirname, '../some-public'),
    },
  },
};
```

### copyOnBuild

* **Type:** `boolean | 'auto'`
* **Default:** `'auto'`

Whether to copy files from the public directory to the dist directory on production build.

* `true`: copy files.
* `false`: do not copy files.
* `'auto'`: if [output.target](/config/output/target.md) is not `'node'`, copy files, otherwise do not copy.

:::tip
During dev builds, if you need to copy some static assets to the output directory, you can use the [output.copy](/config/output/copy.md) option instead.
:::

#### Disable

For example, disable `copyOnBuild`:

```ts title="rsbuild.config.ts"
export default {
  server: {
    publicDir: {
      copyOnBuild: false,
    },
  },
};
```

Note that setting the value of `copyOnBuild` to false means that when you run `rsbuild preview` for a production preview, you will not be able to access the corresponding static resources.

#### Node target

By default, when [output.target](/config/output/target.md) is `'node'`, Rsbuild will not copy files from the public directory.

You can set `copyOnBuild` to `true` to copy files for the `node` target:

```ts title="rsbuild.config.ts"
export default {
  output: {
    target: 'node',
  },
  server: {
    publicDir: {
      copyOnBuild: true,
    },
  },
};
```

#### Multiple environments

When performing [multi-environment builds](/guide/advanced/environments.md), Rsbuild copies files from the public directory to the output directory of each environment. If there are nested output directories, files will only be copied to the root of the output directory. For example:

* The distDir of the `web` environment is `dist`, and the distDir of the `web1` environment is `dist/web1`. Due to the nested relationship between `dist` and `dist/web1`, the public directory files are only copied to the `dist` directory.
* The distDir of the `esm` environment is `dist/esm`, and the distDir of the `cjs` environment is `dist/cjs`. Since there is no nesting relationship between `dist/esm` and `dist/cjs`, the public directory files will be copied to both the `dist/esm` and `dist/cjs` directories.

### watch

* **Type:** `boolean`
* **Default:** `false`

Whether to watch the public directory and reload the page when the files change.

Setting `watch` to `true` allows the dev server to watch changes to files in the specified public directory and reload the page when the files are changed:

```ts title="rsbuild.config.ts"
export default {
  server: {
    publicDir: {
      watch: true,
    },
  },
};
```

Note that the `watch` option is only valid in development mode. If [dev.hmr](/config/dev/hmr.md) and [dev.liveReload](/config/dev/live-reload.md) are both set to false, `watch` will be ignored.

## Multiple directories

The `server.publicDir` can be configured as an array, allowing you to serve multiple directories as static assets folders:

```ts title="rsbuild.config.ts"
export default {
  server: {
    publicDir: [
      {
        name: 'public',
      },
      {
        name: 'assets',
        watch: false,
      },
    ],
  },
};
```

## Disabled

You can set `publicDir` to `false` to disable the static assets serving:

```ts title="rsbuild.config.ts"
export default {
  server: {
    publicDir: false,
  },
};
```

---

# Source: https://rsbuild.dev/guide/start/quick-start.md

# Quick start

## Online examples

We provide online Rsbuild examples that showcase Rspack's build performance and Rsbuild's development experience:

* [StackBlitz example](https://stackblitz.com/~/github.com/rstackjs/rsbuild-stackblitz-example)
* [CodeSandbox example](https://codesandbox.io/p/github/rstackjs/rsbuild-codesandbox-example)

## Environment preparation

Rsbuild 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

* Rsbuild >= v1.5.0 requires Node.js 18.12.0 or higher.
* Rsbuild \< 1.5.0 requires Node.js 16.10.0 or higher.

:::

## Create an Rsbuild application

Use [create-rsbuild](https://www.npmjs.com/package/create-rsbuild) to create a new Rsbuild application. Run the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs
  command={{
  npm: 'npm create rsbuild@latest',
  yarn: 'yarn create rsbuild',
  pnpm: 'pnpm create rsbuild@latest',
  bun: 'bun create rsbuild@latest',
  deno: 'deno init --npm rsbuild@latest',
}}
/>

Follow the prompts to choose options, such as whether to add optional tools like TypeScript and ESLint.

After creating the application, 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 the dev server, which runs on `http://localhost:3000` by default.

### Templates

When creating an application, you can choose from the following templates provided by `create-rsbuild`:

| Template | Official docs                   | Rsbuild integration guide               |
| -------- | ------------------------------- | --------------------------------------- |
| vanilla  | Native JavaScript               | -                                       |
| react    | [React 19](https://react.dev/)  | [Using React](/guide/framework/react.md)   |
| react18  | [React 18](https://react.dev/)  | [Using React](/guide/framework/react.md)   |
| vue      | [Vue 3](https://vuejs.org/)     | [Using Vue](/guide/framework/vue.md)       |
| vue2     | [Vue 2](https://v2.vuejs.org/)  | [Using Vue](/guide/framework/vue.md)       |
| lit      | [Lit](https://lit.dev/)         | -                                       |
| preact   | [Preact](https://preactjs.com/) | [Using Preact](/guide/framework/preact.md) |
| svelte   | [Svelte](https://svelte.dev/)   | [Using Svelte](/guide/framework/svelte.md) |
| solid    | [Solid](https://solidjs.com/)   | [Using Solid](/guide/framework/solid.md)   |

`create-rsbuild` provides basic templates. For more options, see:

* Visit [Rspack - Ecosystem](https://rspack.rs/guide/start/quick-start#ecosystem) to learn about higher-level tools built on Rsbuild.
* Visit [awesome-rstack - Starter](https://github.com/rstackjs/awesome-rstack?tab=readme-ov-file#starter) for community-maintained templates.

### Optional tools

`create-rsbuild` can help you set up commonly used tools, including [Rstest](https://rstest.rs), [Biome](https://github.com/biomejs/biome), [ESLint](https://github.com/eslint/eslint), [Prettier](https://github.com/prettier/prettier), [Tailwind CSS](https://tailwindcss.com) and [Storybook](https://storybook.js.org/). Use the arrow keys to navigate and the space bar to select. Press Enter without selecting anything to skip these tools.

```
◆  Select additional tools (Use <space> to select, <enter> to continue)
│  ◻ Rstest - testing
│  ◻ Biome - linting & formatting
│  ◻ ESLint - linting
│  ◻ Prettier - formatting
│  ◻ Tailwind CSS - styling
│  ◻ Storybook - component development
└
```

:::tip
Biome provides similar linting and formatting features to ESLint and Prettier. If you select Biome, you typically won't need to add ESLint or Prettier.
:::

### Current directory

To create an application in the current directory, set the target folder to `.`:

```
◆  Create Rsbuild Project
│
◇  Project name or path
│  .
│
◇  "." is not empty, please choose:
│  Continue and override files
```

### Non-interactive mode

[create-rsbuild](https://npmjs.com/package/create-rsbuild) 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 app in the `my-app` directory:

```bash
npx -y create-rsbuild@latest my-app --template react

# Using abbreviations
npx -y create-rsbuild@latest my-app -t react

# Specify multiple tools
npx -y create-rsbuild@latest my-app -t react --tools eslint,prettier
```

All CLI flags supported by `create-rsbuild`:

```
Usage: create-rsbuild [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

Templates:

  react-js, react-ts, vue3-js, vue3-ts, vue2-js, vue2-ts, svelte-js, svelte-ts,
  solid-js, solid-ts, vanilla-js, vanilla-ts

Optional tools:
  rstest, biome, eslint, prettier, tailwindcss, storybook
```

## Migrate from existing projects

To migrate from an existing project to Rsbuild, refer to the following guides:

* [Migrate from webpack](/guide/migration/webpack.md)
* [Migrate from Create React App](/guide/migration/cra.md)
* [Migrate from Vue CLI](/guide/migration/vue-cli.md)
* [Migrate from Vite](/guide/migration/vite.md)
* [Migrate from Modern.js Builder](/guide/migration/modern-builder.md)
* [Migrate from Tsup to Rslib](https://rslib.rs/guide/migration/tsup)
* [Migrate from Storybook to Storybook Rsbuild](https://rspack.rs/guide/migration/storybook)

### Other projects

If your project doesn't match the above migration guides, you can manually install the [@rsbuild/core](https://npmjs.com/package/@rsbuild/core) package:

<PackageManagerTabs command="add @rsbuild/core -D" />

After installation, use the following documents to configure your project:

* See [CLI](/guide/basic/cli.md) to learn about available CLI commands.
* See [Plugin List](/plugins/list/index.md) to select Rsbuild plugins.
* See [Configure Rsbuild](/guide/configuration/rsbuild.md) to configure Rsbuild.

## CLI

Rsbuild includes a lightweight CLI with commands like `dev` and `build`.

```json title="package.json"
{
  "scripts": {
    // start the dev server
    "dev": "rsbuild dev",
    // build for production
    "build": "rsbuild build",
    // preview the production build locally
    "preview": "rsbuild preview"
  }
}
```

Refer to the [CLI](/guide/basic/cli.md) to learn about all available commands and options.

## Entry module

By default, Rsbuild CLI uses `src/index.(js|ts|jsx|tsx)` as the entry module. You can modify the entry module using the [source.entry](/config/source/entry.md) option.

```ts title="rsbuild.config.ts"
export default {
  source: {
    entry: {
      foo: './src/pages/foo/index.ts',
      bar: './src/pages/bar/index.ts',
    },
  },
};
```

## Core packages

### @rsbuild/core

<a href="https://npmjs.com/package/@rsbuild/core" target="_blank" style={{ display: 'block', marginTop: '16px' }}>
  <img src="https://img.shields.io/npm/v/@rsbuild/core?style=flat-square&colorA=564341&colorB=EDED91" alt="@rsbuild/core" style={{ pointerEvents: 'none' }} />
</a>

Core Rsbuild package that provides the CLI commands and JavaScript API.

### create-rsbuild

<a href="https://npmjs.com/package/create-rsbuild" target="_blank" style={{ display: 'block', marginTop: '16px' }}>
  <img src="https://img.shields.io/npm/v/create-rsbuild?style=flat-square&colorA=564341&colorB=EDED91" alt="create-rsbuild" style={{ pointerEvents: 'none' }} />
</a>

Create a new Rsbuild project.

## Next step

You may want:

import NextSteps from '@components/NextSteps';
import Step from '@components/Step';

<NextSteps>
  <Step href="/guide/start/features" title="All features" description="Learn all features of Rsbuild" />

  <Step href="/guide/configuration/rsbuild" title="Config" description="Learn how to configure Rsbuild" />

  <Step href="https://github.com/web-infra-dev/rsbuild" title="Support Rsbuild" description="Support us with a star ⭐️" />
</NextSteps>

---

# Source: https://rsbuild.dev/guide/framework/react.md

# React

This document explains how to use Rsbuild to build a React application.

## Create a React application

Create a React application with Rsbuild using [create-rsbuild](/guide/start/quick-start.md#create-an-rsbuild-application). Run this command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs
  command={{
  npm: 'npm create rsbuild@latest',
  yarn: 'yarn create rsbuild',
  pnpm: 'pnpm create rsbuild@latest',
  bun: 'bun create rsbuild@latest',
}}
/>

Then select `React 19` or `React 18` when prompted to "Select framework".

## Use React in an existing project

To compile React's JSX syntax, register the Rsbuild [React Plugin](/plugins/list/plugin-react.md). The plugin automatically adds the necessary configuration for building React applications.

For example, register in `rsbuild.config.ts`:

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

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

:::tip
For projects using Create React App, you can refer to the [CRA Migration Guide](/guide/migration/cra.md).
:::

## Use SVGR

Rsbuild supports converting SVG to React components via [SVGR](https://react-svgr.com/).

To use SVGR, register the [SVGR plugin](/plugins/list/plugin-svgr.md).

## React Fast Refresh

Rsbuild uses React's official [Fast Refresh](https://npmjs.com/package/react-refresh) capability to perform component hot updates.

React Refresh requires components to follow certain standards, or HMR may not work. Use [eslint-plugin-react-refresh](https://github.com/ArnaudBarre/eslint-plugin-react-refresh) to validate your code.

If React component hot updates don't work, or component state is lost after updates, your React component is likely using an anonymous function. React Fast Refresh requires named functions to preserve component state after hot updates.

Here are some examples of wrong usage:

```tsx
// bad
export default function () {
  return <div>Hello World</div>;
}

// bad
export default () => <div>Hello World</div>;
```

The correct usage is to declare a name for each component function:

```tsx
// good
export default function MyComponent() {
  return <div>Hello World</div>;
}

// good
const MyComponent = () => <div>Hello World</div>;

export default MyComponent;
```

## React Compiler

React Compiler is a build-time tool that automatically optimizes your React app. It works with plain JavaScript, and understands the Rules of React, so you don’t need to rewrite any code to use it.

Before using React Compiler, we recommend reading the [React Compiler documentation](https://react.dev/learn/react-compiler) to understand its functionality, current state, and usage.

### How to use

Steps to use React Compiler in Rsbuild:

1. Upgrade `react` and `react-dom` to v19. If you can't upgrade, install the [react-compiler-runtime](https://npmjs.com/package/react-compiler-runtime) package to run the compiled code on earlier versions.
2. React Compiler currently only provides a Babel plugin. Install [@rsbuild/plugin-babel](/plugins/list/plugin-babel.md) and [babel-plugin-react-compiler](https://npmjs.com/package/babel-plugin-react-compiler).
3. Register the Babel plugin in your Rsbuild config file:

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

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginBabel({
      include: /\.(?:jsx|tsx)$/,
      babelLoaderOptions(opts) {
        opts.plugins?.unshift('babel-plugin-react-compiler');
      },
    }),
  ],
});
```

> You can also refer to the [example project](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/react-compiler-babel).

### Configuration

Set the config for React Compiler as follows:

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

const ReactCompilerConfig = {
  /* ... */
};

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginBabel({
      include: /\.(?:jsx|tsx)$/,
      babelLoaderOptions(opts) {
        opts.plugins?.unshift([
          'babel-plugin-react-compiler',
          ReactCompilerConfig,
        ]);
      },
    }),
  ],
});
```

For React 17 and 18 projects, install [react-compiler-runtime](https://npmjs.com/package/react-compiler-runtime) and specify the `target`:

```ts title="rsbuild.config.ts"
const ReactCompilerConfig = {
  target: '18', // '17' | '18' | '19'
};
```

## Router

### TanStack Router

[TanStack Router](https://tanstack.com/router/) is a fully type-safe React router with built-in data fetching, stale-while revalidate caching and first-class search-param APIs.

TanStack Router provides `@tanstack/router-plugin` to integrate with Rsbuild, which provides support for file-based routing. See:

* [Installation guide](https://tanstack.com/router/latest/docs/framework/react/installation/with-rspack)
* [Example project](https://github.com/TanStack/router/tree/main/examples/react/quickstart-rspack-file-based)

### React Router

[React Router](https://reactrouter.com/) is a user‑obsessed, standards‑focused, multi‑strategy router for React.

* To use React Router as a library, you can just follow the official documentation and no configuration is required.
* To use React Router as a framework, the community is working on an experimental Rsbuild plugin, see [rsbuild-plugin-react-router](https://github.com/rstackjs/rsbuild-plugin-react-router).

## CSS-in-JS

See [CSS-in-JS](/guide/styling/css-in-js.md) for how to use CSS-in-JS in Rsbuild.

## Customize JSX

Rsbuild uses SWC to compile JSX. You can customize the functions used by the compiled JSX code:

* If the JSX runtime is `automatic`, use [importSource](/plugins/list/plugin-react.md#swcreactoptionsimportsource) to customize the import path of the JSX runtime, for example, import from Preact or Emotion.
* If the JSX runtime is `classic`, use `pragma` and `pragmaFrag` to specify the JSX function and Fragment component.

> `@rsbuild/plugin-react` uses `automatic` as the default JSX runtime, see [swcReactOptions.runtime](/plugins/list/plugin-react.md#swcreactoptionsruntime).

### Via configuration

Configure through the `@rsbuild/plugin-react`'s [swcReactOptions](/plugins/list/plugin-react.md#swcreactoptions).

* If `runtime` is `automatic`:

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

export default defineConfig({
  plugins: [
    pluginReact({
      swcReactOptions: {
        runtime: 'automatic',
        importSource: '@emotion/react',
      },
    }),
  ],
});
```

* If `runtime` is `classic`:

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

export default defineConfig({
  plugins: [
    pluginReact({
      swcReactOptions: {
        runtime: 'classic',
        pragma: 'h',
        pragmaFrag: 'Fragment',
      },
    }),
  ],
});
```

### Via comments

You can also customize JSX behavior by adding specific comments at the top of individual JSX or TSX files, which will take precedence over the configuration.

* If the JSX runtime is `automatic`:

```tsx title="App.tsx"
/** @jsxImportSource custom-jsx-library */

const App = () => {
  return <div>Hello World</div>;
};
```

* If the JSX runtime is `classic`:

```tsx title="App.tsx"
/** @jsx Preact.h */
/** @jsxFrag Preact.Fragment */

const App = () => {
  return <div>Hello World</div>;
};
```

## Performance profiling

### React Scan

React Scan can automatically detect performance issues in your React app.

See [React Scan - Rsbuild Guide](https://github.com/aidenybai/react-scan/blob/main/docs/installation/rsbuild.md) to learn how to use React Scan with Rsbuild.

---

# Source: https://rsbuild.dev/config/performance/remove-console.md

# performance.removeConsole

* **Type:** `boolean | ConsoleType[]`
* **Default:** `false`

Whether to remove `console.[methodName]` in production build.

## Remove all

When `removeConsole` is set to `true`, all types of `console.[methodName]` are removed:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    removeConsole: true,
  },
};
```

## Specific type

You can also specify to remove only certain types of `console.[methodName]`, such as `console.log` and `console.warn`:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    removeConsole: ['log', 'warn'],
  },
};
```

The following types of console are currently supported:

```ts
type ConsoleType = 'log' | 'info' | 'warn' | 'error' | 'table' | 'group';
```

---

# Source: https://rsbuild.dev/config/performance/remove-moment-locale.md

# performance.removeMomentLocale

* **Type:** `boolean`
* **Default:** `false`

Whether to remove the locales of [moment.js](https://momentjs.com/).

`moment.js` contains a lot of locales by default, which will increase the bundle size.

When `moment.js` is used in the project, it is recommended to enable this option to automatically exclude all locales:

```ts title="rsbuild.config.ts"
export default {
  performance: {
    removeMomentLocale: true,
  },
};
```

Once enabled, you can load a specific locale via:

```js
import moment from 'moment';
import 'moment/locale/zh-cn';

moment.locale('zh-cn');
```

---

# Source: https://rsbuild.dev/config/root.md

# root

* **Type:** `string`
* **Default:** [process.cwd()](https://nodejs.org/api/process.html#processcwd)
* **Version:** `>= 1.0.0`

Specify the project root directory. Can be an absolute path, or a path relative to `process.cwd()`.

The value of Rsbuild `root` is also passed to the [context](https://rspack.rs/config/context) configuration of Rspack.

:::tip
The value of `root` does not affect the path of the `.env` file, as the `.env` file is resolved before the Rsbuild configuration file.

Rsbuild CLI supports using the `--root` option to specify the root directory, which can affect the path of the `.env` file. See ["CLI"](/guide/basic/cli.md) for more details.
:::

## Example

* Relative path:

```ts title="rsbuild.config.ts"
export default {
  root: './foo',
};
```

* Absolute path:

```ts title="rsbuild.config.ts"
import { join } from 'node:path';

export default {
  root: join(__dirname, 'foo'),
};
```

---

# Source: https://rsbuild.dev/guide/migration/rsbuild-0-x.md

# Migrating from Rsbuild 0.x

This document lists all breaking changes from Rsbuild 0.7 to 1.0. Use it as a migration reference.

> See [Breaking changes in Rsbuild v1.0.0](https://github.com/web-infra-dev/rsbuild/discussions/2508) for details.

## \[Important] Lightning CSS loader

Rsbuild now enables [lightningcss-loader](https://rspack.rs/guide/features/builtin-lightningcss-loader) by default to transform CSS files. It replaces `autoprefixer` for adding vendor prefixes and delivers better performance.

* `@rsbuild/plugin-lightningcss` is deprecated and no longer needed.
* `tools.autoprefixer` config has been removed.

Since Lightning CSS has some uncovered edge cases, you can still enable autoprefixer through a postcss config file:

```js title="postcss.config.cjs"
module.exports = {
  plugins: {
    autoprefixer: {},
  },
};
```

## \[Important] output.polyfill

Rsbuild v1 sets [output.polyfill](/config/output/polyfill.md) to `'off'` by default. This reduces polyfill code and generates smaller bundles.

If your application needs polyfills, set `output.polyfill` to `'usage'` or `'entry'`:

```ts title="rsbuild.config.ts"
export default {
  output: {
    polyfill: 'usage',
  },
};
```

## \[Important] source.decorators

Rsbuild now uses `2022-11` decorators version by default. This aligns Rsbuild's default behavior with TypeScript >= 5.0 and esbuild >= 0.21.0.

For legacy decorators, add this config:

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

export default defineConfig({
  source: {
    decorators: {
      version: 'legacy',
    },
  },
});
```

## \[Important] output.targets

:::tip
Rsbuild v1 removes the `output.targets` option and target parameters from `source.alias`, `source.entry`, and other configs. Instead, use `environments` for more flexible multi-environment configuration.

The `environments` option provides broader coverage and enables differentiated config across multiple environments. For details, see [Multiple-Environment Builds](/guide/advanced/environments.md).
:::

The `output.targets` config has been removed. Use [output.target](/config/output/target.md) and [environments](/config/environments.md) instead.

* before:

```js
export default {
  output: {
    targets: ['web', 'node'],
  },
};
```

* after:

```js
export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
      },
    },
  },
};
```

## source.alias

Removed `target` param for `source.alias` function, use [environments](/config/environments.md) config instead.

* before:

```js
export default {
  source: {
    alias: (alias, { target }) => {
      if (target === 'node') {
        alias['@common'] = './src/node/common';
      } else if (target === 'web') {
        alias['@common'] = './src/web/common';
      }
    },
  },
  output: {
    targets: ['web', 'node'],
  },
};
```

* after:

```js
export default {
  environments: {
    web: {
      source: {
        alias: {
          '@common': './src/web/common',
        },
      },
      output: {
        target: 'web',
      },
    },
    node: {
      source: {
        alias: {
          '@common': './src/node/common',
        },
      },
      output: {
        target: 'node',
      },
    },
  },
};
```

## source.entry

Removed function usage of `source.entry`, use [environments](/config/environments.md) config instead.

* before:

```js
export default {
  source: {
    entry({ target }) {
      if (target === 'web') {
        return {
          index: './src/index.client.js',
        };
      }
      if (target === 'node') {
        return {
          index: './src/index.server.js',
        };
      }
    },
  },
  output: {
    targets: ['web', 'node'],
  },
};
```

* after:

```js
export default {
  environments: {
    web: {
      source: {
        entry: {
          index: './src/index.client.js',
        },
      },
      output: {
        target: 'web',
      },
    },
    node: {
      source: {
        entry: {
          index: './src/index.server.js',
        },
      },
      output: {
        target: 'node',
      },
    },
  },
};
```

## output.overrideBrowserslist

`output.overrideBrowserslist` no longer supports `Record<RsbuildTarget, string[]` type, use [environments](/config/environments.md) config instead.

* before:

```js
export default {
  output: {
    overrideBrowserslist: {
      web: ['iOS >= 9', 'Android >= 4.4'],
      node: ['node >= 20'],
    },
  },
};
```

* after:

```js
export default defineConfig({
  environments: {
    web: {
      output: {
        overrideBrowserslist: ['iOS >= 9', 'Android >= 4.4'],
      },
    },
    node: {
      output: {
        overrideBrowserslist: ['node >= 20'],
      },
    },
  },
});
```

## output.emitAssets

`output.emitAssets` changed to boolean type, use [environments](/config/environments.md) config instead.

* before:

```js
export default {
  output: {
    targets: ['web', 'node'],
    emitAssets: ({ target }) => target !== 'node',
  },
};
```

* after:

```js
export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
        emitAssets: false,
      },
    },
  },
};
```

## output.distPath.server

Removed `output.distPath.server`, use the [environments](/config/environments.md) config instead.

```js
export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
        distPath: {
          root: 'dist/server',
        },
      },
    },
  },
};
```

## output.minify.html

Rsbuild v1 removed the `output.minify.html` and `output.minify.htmlOptions` options, and no longer minify the HTML files.

Previously Rsbuild uses `html-minifier-terser` to minify the HTML files. But the performance of `html-minifier-terser` cannot meet the needs of Rsbuild applications, and in most cases, there is little benefit in compressing HTML.

At this stage, Rsbuild will not built-in `html-minifier-terser`, so we provide a standalone [rsbuild-plugin-html-minifier-terser](https://github.com/rstackjs/rsbuild-plugin-html-minifier-terser) to support HTML minification.

```ts title="rsbuild.config.ts"
import { pluginHtmlMinifierTerser } from 'rsbuild-plugin-html-minifier-terser';

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

And we plan to use some faster Rust-based HTML minimizer in the future.

## output.charset

The default value of [output.charset](/config/output/charset.md) has been changed from `ascii` to `utf8`.

To use `ascii`, add the following config:

```ts
export default {
  output: {
    charset: 'ascii',
  },
};
```

## dev.startUrl

`dev.startUrl` has been renamed to [server.open](/config/server/open.md):

```js
export default {
  // [!code --]
  dev: {
    startUrl: true, // [!code --]
  }, // [!code --]
  // [!code ++]
  server: {
    open: true, // [!code ++]
  }, // [!code ++]
};
```

## dev.client.port

The default value of [dev.client.port](/config/dev/client.md) changed from `<port>` to `''` (use `location.port`).

Use the previous value if you want to keep the behavior:

```js
export default {
  dev: {
    client: {
      port: '<port>',
    },
  },
};
```

## html.appIcon

Previously, [html.appIcon](/config/html/app-icon.md) did not support for web app manifests, meaning it was only available on iOS.

Now `html.appIcon` supports generating web app manifests, and the type of `html.appIcon` has been changed.

* before:

```js
export default {
  html: {
    appIcon: './src/icon.png',
  },
};
```

* after:

```js
export default {
  html: {
    appIcon: {
      icons: [{ src: './src/icon.png', size: 180 }],
    },
  },
};
```

## Others

Rsbuild 1.0 has made some adjustments and optimizations to plugins API and dev server API.

Includes:

* The `onBeforeBuild` hook supports triggering multiple times in watch mode.
* Added `onBeforeEnvironmentCompile` and `onAfterEnvironmentCompile` hooks, which are triggered before/after executing the build of a single environment respectively.
* Removed `api.getHtmlPaths` and replaced it with `environment.htmlPaths`.
* Removed `api.context.entry` and replaced it with `environment.entry`.
* Removed `api.context.targets` and replaced it with `environment.target`.
* Removed `rsbuildServer.onHTTPUpgrade` and replaced it with `rsbuildServer.connectWebSocket`.

---

# Source: https://rsbuild.dev/guide/configuration/rsbuild.md

# Configure Rsbuild

Rsbuild provides a wide range of configuration options with sensible defaults for most use cases. In most scenarios, you can use Rsbuild out of the box without any configuration.

When you need to customize build behavior, use the options below.

## Configuration structure

The Rsbuild configuration structure looks like this:

```js title="rsbuild.config.mjs"
export default {
  plugins: [
    // configure Rsbuild plugins
  ],
  dev: {
    // options for local development
  },
  html: {
    // options for HTML generation
  },
  tools: {
    // options for the low-level tools
  },
  output: {
    // options for build outputs
  },
  resolve: {
    // options for module resolution
  },
  source: {
    // options for input source code
  },
  server: {
    // options for the Rsbuild server,
    // will take effect during local development and preview
  },
  security: {
    // options for Web security
  },
  performance: {
    // options for build performance and runtime performance
  },
  moduleFederation: {
    // options for module federation
  },
  environments: {
    // define different Rsbuild configurations for each environment
  },
};
```

You can find detailed descriptions of every option on the [Configure Overview](/config/index.md) page.

## Configuration file

When you use the Rsbuild CLI, it looks for a configuration file in the project root in the following order:

* rsbuild.config.mjs
* rsbuild.config.ts
* rsbuild.config.js
* rsbuild.config.cjs
* rsbuild.config.mts
* rsbuild.config.cts

We recommend using `rsbuild.config.ts` and importing the `defineConfig` utility from `@rsbuild/core`. It provides TypeScript hints and autocompletion to help you avoid configuration mistakes.

For example, in `rsbuild.config.ts`, you can define the Rsbuild [resolve.alias](/config/resolve/alias.md) configuration:

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

export default defineConfig({
  resolve: {
    alias: {
      '@common': './src/common',
    },
  },
});
```

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

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

export default defineConfig({
  resolve: {
    alias: (opts) => {
      opts['@common'] = './src/common';
    },
  },
});
```

## Specify config file

The Rsbuild CLI uses the `--config` option to specify the config file. It can be set to a relative or absolute path.

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

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

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

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

## Specify config loader

Rsbuild provides three ways to load configuration files:

* `auto` (Default): Use Node.js's native loader to load configuration files first, falling back to jiti if it fails.
* `jiti`: Use [jiti](https://github.com/unjs/jiti) to load the configuration file, providing interoperability between ESM and CommonJS. The module resolution behavior differs slightly from Node.js native behavior.
* `native`: Use Node.js native loader to load the configuration file. This ensures that module resolution behavior is consistent with Node.js native behavior and has better performance. This requires your JavaScript runtime to natively support TypeScript.

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

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

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

### About Node.js native loader

When using Node.js's native loader, 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 './rsbuild.base.config.ts'; // ✅ Correct
   import baseConfig from './rsbuild.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 such as `process.env.NODE_ENV` to dynamically set different configurations:

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

export default defineConfig({
  resolve: {
    alias: {
      '@request':
        process.env.NODE_ENV === 'development'
          ? './src/request.dev.js'
          : './src/request.prod.js',
    },
  },
});
```

## Export function

Rsbuild supports exporting a function in the config file, which allows you to dynamically compute the config and return it to Rsbuild.

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

export default defineConfig(({ env, command, envMode }) => ({
  resolve: {
    alias: {
      '@foo': env === 'development' ? './src/foo.dev.ts' : './src/foo.prod.ts',
    },
  },
}));
```

:::tip
The exported config function must provide a return value. If you do not need to return any config, you can return an empty object.
:::

The function accepts the following parameters:

### env

* **Type:** `string`
* **Default:** `process.env.NODE_ENV`

The current runtime environment.

* When running `rsbuild dev`, the default value of env is `development`.
* When running `rsbuild build` or `rsbuild preview`, the default value of env is `production`.

### envMode

* **Type:** `string`
* **Default:** `process.env.NODE_ENV`

The current value of the CLI parameter `--env-mode`.

For example, when running `rsbuild build --env-mode test`, the value of `envMode` is `test`.

### command

* **Type:** `string`

The current CLI command, such as `dev`, `build`, `preview`.

## Export async function

Rsbuild also supports exporting an async function in the config file, which lets you perform async work:

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

export default defineConfig(async ({ env, command }) => {
  const result = await someAsyncFunction();

  return {
    html: {
      title: result,
    },
  };
});
```

## Merge configurations

You can use the [mergeRsbuildConfig](/api/javascript-api/core.md#mergersbuildconfig) function exported by `@rsbuild/core` to merge multiple configurations.

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

const config1 = defineConfig({
  dev: { port: '3000' },
});
const config2 = defineConfig({
  dev: { port: '3001' },
});

// { dev: { port: '3001' }
export default mergeRsbuildConfig(config1, config2);
```

## Debug the config

You can enable Rsbuild's debug mode by setting `DEBUG=rsbuild` when running a build.

```bash
DEBUG=rsbuild pnpm dev
```

In debug mode, Rsbuild writes the config to the dist directory, making it easier to inspect and debug.

```
config inspection completed, open the following files to view the content:

   - Rsbuild config: /Project/demo/dist/.rsbuild/rsbuild.config.mjs
   - Rspack config (web): /Project/demo/dist/.rsbuild/rspack.config.web.mjs
```

Open the generated `/dist/.rsbuild/rsbuild.config.mjs` file to see the complete content of the Rsbuild config.

For a complete introduction to debug mode, see the [Debug Mode](/guide/debug/debug-mode.md) chapter.

---

# Source: https://rsbuild.dev/guide/debug/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 Rsbuild project, enable Rsdoctor as follows:

1. Install the Rsdoctor plugin:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsdoctor/rspack-plugin -D" />

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

```json title="package.json"
{
  "scripts": {
    "dev:rsdoctor": "RSDOCTOR=true rsbuild dev",
    "build:rsdoctor": "RSDOCTOR=true rsbuild 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": {
    "dev:rsdoctor": "cross-env RSDOCTOR=true rsbuild dev",
    "build:rsdoctor": "cross-env RSDOCTOR=true rsbuild build"
  },
  "devDependencies": {
    "cross-env": "^7.0.0"
  }
}
```

After running these scripts, Rsbuild 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="rsbuild.config.ts"
import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';

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

---

# Source: https://rsbuild.dev/config/tools/rspack.md

# Source: https://rsbuild.dev/guide/configuration/rspack.md

# Configure Rspack

Rsbuild supports directly modifying the Rspack configuration object, and supports modifying the built-in Rspack configuration of Rsbuild through `rspack-chain`.

:::tip
The built-in Rspack config in Rsbuild may change with iterations, and these changes will not be reflected in semver. Therefore, your custom config may become invalid when you upgrade Rsbuild.
:::

## View Rspack config

Rsbuild provides the [rsbuild inspect](/guide/basic/cli.md#rsbuild-inspect) command to view the final Rspack config generated by Rsbuild.

You can also view it through [debug mode](/guide/debug/debug-mode.md).

## Modify config object

You can use the [tools.rspack](/config/tools/rspack.md) option of Rsbuild to modify the Rspack config object.

For example, registering a built-in Rspack plugin:

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

export default {
  tools: {
    rspack: {
      plugins: [
        new rspack.CircularDependencyRspackPlugin({
          // options
        }),
      ],
    },
  },
};
```

Or registering a community webpack plugin:

```ts title="rsbuild.config.ts"
import { sentryWebpackPlugin } from '@sentry/webpack-plugin';

export default {
  tools: {
    rspack: {
      plugins: [
        sentryWebpackPlugin({
          // options
        }),
      ],
    },
  },
};
```

Or modify the built-in Rspack config with a function:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: (config, { env }) => {
      if (env === 'development') {
        config.devtool = 'cheap-module-eval-source-map';
      }
      return config;
    },
  },
};
```

> Please refer to the [tools.rspack documentation](/config/tools/rspack.md) for detailed usage.

## Access Rspack API

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](/api/javascript-api/core.md#rspack) object from `@rsbuild/core` without installing the `@rspack/core` package separately.

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

export default {
  tools: {
    rspack: {
      plugins: [
        new 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 Rsbuild depends on.

:::

## Use bundler chain

import RspackChain from '@en/shared/rspackChain.mdx';

<RspackChain />

### tools.bundlerChain

Rsbuild provides the [tools.bundlerChain](/config/tools/bundler-chain.md) config to modify the rspack-chain. Its value is a function that takes two arguments:

* The first argument is an `rspack-chain` instance, which you can use to modify the Rspack config.
* The second argument is an utils object, including `env`, `isProd`, `CHAIN_ID`, etc.

Here is a basic example:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    bundlerChain: (chain, { env }) => {
      if (env === 'development') {
        chain.devtool('cheap-module-eval-source-map');
      }
    },
  },
};
```

`tools.bundlerChain` can also be an async function:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    bundlerChain: (chain, { env }) => {
      const value = await fetchValue();
      chain.devtool(value);
    },
  },
};
```

### Basics

Before using the rspack-chain to modify the Rspack configuration, it is recommended to familiarize yourself with some basics.

#### About ID

In short, the rspack-chain requires users to set a unique ID for each rule, loader, plugin, and minimizer. With this ID, you can easily find the desired object from deeply nested objects.

Rsbuild exports all internally defined IDs through the `CHAIN_ID` object, so you can quickly locate the loader or plugin you want to modify using these exported IDs, without the need for complex traversal in the Rspack configuration object.

For example, you can remove the built-in CSS rule using `CHAIN_ID.RULE.CSS`:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      chain.module.rules.delete(CHAIN_ID.RULE.CSS);
    },
  },
};
```

#### ID types

The `CHAIN_ID` object contains various IDs, which correspond to the following configurations:

| CHAIN\_ID Field       | Corresponding Configuration | Description                                            |
| -------------------- | --------------------------- | ------------------------------------------------------ |
| `CHAIN_ID.PLUGIN`    | `plugins[i]`                | Corresponds to a plugin in the Rspack configuration    |
| `CHAIN_ID.RULE`      | `module.rules[i]`           | Corresponds to a rule in the Rspack configuration      |
| `CHAIN_ID.USE`       | `module.rules[i].loader`    | Corresponds to a loader in the Rspack configuration    |
| `CHAIN_ID.MINIMIZER` | `optimization.minimizer`    | Corresponds to a minimizer in the Rspack configuration |

### Examples

#### Custom loader

Here are examples of adding, modifying, and removing Rspack loaders.

* Add a loader to handle `.md` files:

```js title="rsbuild.config.mjs"
export default {
  tools: {
    bundlerChain: (chain) => {
      chain.module
        .rule('md')
        .test(/\.md$/)
        .use('md-loader')
        // The package name or module path of the loader
        .loader('md-loader');
    },
  },
};
```

* Modify options of the built-in SWC loader:

```js title="rsbuild.config.mjs"
export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      chain.module
        .rule(CHAIN_ID.RULE.JS)
        .use(CHAIN_ID.USE.SWC)
        .tap((options) => {
          console.log(options);
          return options;
        });
    },
  },
};
```

* Remove the built-in SWC loader:

```js title="rsbuild.config.mjs"
export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      chain.module.rule(CHAIN_ID.RULE.JS).uses.delete(CHAIN_ID.USE.SWC);
    },
  },
};
```

* Insert a loader after the built-in SWC loader that executes earlier:

```js title="rsbuild.config.mjs"
export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      chain.module
        .rule(CHAIN_ID.RULE.JS)
        .use('my-loader')
        .after(CHAIN_ID.USE.SWC)
        // The package name or module path of the loader
        .loader('my-loader')
        .options({
          // some options
        });
    },
  },
};
```

> Note: Rspack loaders are executed in reverse order.

* Insert a loader before the built-in SWC loader that executes later:

```js title="rsbuild.config.mjs"
export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      chain.module
        .rule(CHAIN_ID.RULE.JS)
        // Loader ID, not actually meaningful, just for locating
        .use('my-loader')
        .before(CHAIN_ID.USE.SWC)
        // The package name or module path of the loader
        .loader('my-loader')
        .options({
          // some options
        });
    },
  },
};
```

* Remove the built-in CSS handling rule:

```js title="rsbuild.config.mjs"
export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      chain.module.rules.delete(CHAIN_ID.RULE.CSS);
    },
  },
};
```

#### Custom plugin

Here are examples of adding, modifying, and deleting Rspack plugins.

```js title="rsbuild.config.mjs"
export default {
  tools: {
    bundlerChain: (chain, { bundler, CHAIN_ID }) => {
      // Add plugin
      chain.plugin('custom-define').use(bundler.DefinePlugin, [
        {
          'process.env': {
            NODE_ENV: JSON.stringify(process.env.NODE_ENV),
          },
        },
      ]);

      // Modify plugin
      chain.plugin(CHAIN_ID.PLUGIN.HMR).tap((options) => {
        options[0].fullBuildTimeout = 200;
        return options;
      });

      // Delete plugin
      chain.plugins.delete(CHAIN_ID.PLUGIN.HMR);
    },
  },
};
```

:::tip
In most cases, you should change the plugin options using the configurations provided by Rsbuild, rather than using `CHAIN_ID.PLUGIN`, as this may lead to unexpected behavior.

For example, use [tools.htmlPlugin](/config/tools/html-plugin.md) to change the options of HtmlPlugin.
:::

#### Modify based on environment

In the `tools.bundlerChain` function, you can access various environment identifiers in the second parameter, such as development/production build, SSR build, Web Worker build, to achieve configuration modifications for different environments.

```js title="rsbuild.config.mjs"
export default {
  tools: {
    bundlerChain: (chain, { env, isProd, target, isServer, isWebWorker }) => {
      if (env === 'development' || env === 'test') {
        // ...
      }
      if (isProd) {
        // ...
      }
      if (target === 'node') {
        // ...
      }
      if (isServer) {
        // ...
      }
      if (isWebWorker) {
        // ...
      }
    },
};
```

The above are some common configuration examples. For the complete rspack-chain API, please refer to the [rspack-chain documentation](https://github.com/rstackjs/rspack-chain).

## Configuration modification order

Rsbuild supports modifying the Rspack configuration object through `tools.rspack`, `tools.bundlerChain`, `modifyBundlerChain`, etc.

The order of execution between them is:

* [modifyBundlerChain](/plugins/dev/hooks.md#modifybundlerchain)
* [tools.bundleChain](/config/tools/bundler-chain.md)
* [modifyRspackConfig](/plugins/dev/hooks.md#modifyrspackconfig)
* [tools.rspack](/config/tools/rspack.md)

---

# Source: https://rsbuild.dev/guide/basic/server.md

# Dev server

Rsbuild includes a built-in dev server that enhances the development experience. When you run `rsbuild dev` or `rsbuild preview`, the server starts and provides features like page preview, routing, and hot module replacement.

## Base path

By default, the Rsbuild server's base path is `/`. You can access output files like `index.html` and [public folder](/guide/basic/static-assets.md#public-folder) assets at `http://localhost:3000/`.

To change the server's base path, use [server.base](/config/server/base.md). For example, to access files at `http://localhost:3000/foo/`:

```ts title="rsbuild.config.ts"
export default {
  server: {
    base: '/foo',
  },
};
```

## View static assets

After starting the dev server, visit `/rsbuild-dev-server` to view all static assets generated during the current build.

For example, open `http://localhost:3000/rsbuild-dev-server` in your browser:

<img src="https://assets.rspack.rs/rsbuild/assets/assets-report-page.png" alt="rsbuild-dev-server" width="600" />

## Page routing

The Rsbuild server provides default routing conventions and allows customization through configuration.

### Default behavior

The Rsbuild server generates page routes based on the [server.base](/config/server/base.md) and [source.entry](/config/source/entry.md) configurations.

When the entry is `index`, access the page at `/`. When the entry is `foo`, access the page at `/foo`.

When `server.base` is `/base`, access the index page at `/base`, and the foo page at `/base/foo`.

```ts title="rsbuild.config.ts"
export default {
  source: {
    entry: {
      index: './src/index.ts',
      foo: './src/pages/foo/index.ts',
    },
  },
};
```

### Fallback behavior

If a request meets the following conditions but no corresponding static asset exists, [server.htmlFallback](/config/server/html-fallback.md) triggers and falls back to `index.html` by default:

* The request method is `GET` or `HEAD`
* The `Accept` header contains `text/html` (for example, `text/html` or `*/*`)

### Custom fallback behavior

If Rsbuild's default [server.htmlFallback](/config/server/html-fallback.md) configuration doesn't meet your needs (for example, serving `main.html` when accessing `/`), use [server.historyApiFallback](/config/server/history-api-fallback.md) instead.

```ts title="rsbuild.config.ts"
export default {
  source: {
    entry: {
      main: './src/index.ts',
    },
  },
  server: {
    historyApiFallback: {
      index: '/main.html',
    },
  },
};
```

### HTML output path

Normally, `/` points to the dist root directory, and HTML files are output there. In this case, access HTML pages at `/some-path`.

If you output HTML files to other subdirectories using [output.distPath.html](/config/output/dist-path.md), access HTML pages at `/[htmlPath]/some-path` instead.

For example, if you set HTML files to output to the `HTML` directory, access index.html at `/html/`, and foo.html at `/html/foo`.

```ts
export default {
  source: {
    entry: {
      index: './src/index.ts',
      foo: './src/pages/foo/index.ts',
    },
  },
  output: {
    distPath: {
      html: 'html',
    },
  },
};
```

## Rspack dev server

Rsbuild includes its own lightweight dev server, which differs from the servers in Rspack CLI and webpack CLI and offers its own configuration options.

### Comparison

Compared to the dev server in Rspack CLI, Rsbuild's dev server has the following differences:

* **Configuration**: Rsbuild provides richer server configuration options.
* **Log Format**: The log format of Rspack CLI is largely consistent with webpack CLI, while Rsbuild's logs are clearer and more readable.
* **Dependencies**: Rsbuild is built on lightweight libraries like `connect`, which has fewer dependencies and faster startup than `express` used by `@rspack/dev-server`.

### Configuration

Rsbuild doesn't support Rspack's [devServer](https://rspack.rs/config/dev-server) config. Use Rsbuild's `dev` and `server` configs instead.

In Rsbuild, the `dev` config contains settings that only apply in development mode, while the `server` config applies to both dev and preview servers.

Below are the Rsbuild configuration options that correspond to Rspack CLI's `devServer` config:

| Rspack CLI                                                                                        | Rsbuild                                                          |
| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| [devServer.client](https://rspack.rs/config/dev-server#devserverclient)                           | [dev.client](/config/dev/client.md)                                 |
| [devServer.compress](https://rspack.rs/config/dev-server#devservercompress)                       | [server.compress](/config/server/compress.md)                       |
| [devServer.devMiddleware.writeToDisk](https://rspack.rs/config/dev-server#devserverdevmiddleware) | [dev.writeToDisk](/config/dev/write-to-disk.md)                     |
| [devServer.headers](https://rspack.rs/config/dev-server#devserverheaders)                         | [server.headers](/config/server/headers.md)                         |
| [devServer.historyApiFallback](https://rspack.rs/config/dev-server#devserverhistoryapifallback)   | [server.historyApiFallback](/config/server/history-api-fallback.md) |
| [devServer.host](https://rspack.rs/config/dev-server#devserverhost)                               | [server.host](/config/server/host.md)                               |
| [devServer.hot](https://rspack.rs/config/dev-server#devserverhot)                                 | [dev.hmr](/config/dev/hmr.md)                                       |
| [devServer.liveReload](https://rspack.rs/config/dev-server#devserverlivereload)                   | [dev.liveReload](/config/dev/live-reload.md)                        |
| [devServer.open](https://rspack.rs/config/dev-server#devserveropen)                               | [server.open](/config/server/open.md)                               |
| [devServer.port](https://rspack.rs/config/dev-server#devserverport)                               | [server.port](/config/server/port.md)                               |
| [devServer.proxy](https://rspack.rs/config/dev-server#devserverproxy)                             | [server.proxy](/config/server/proxy.md)                             |
| [devServer.setupMiddlewares](https://rspack.rs/config/dev-server#devserversetupmiddlewares)       | [dev.setupMiddlewares](/config/dev/setup-middlewares.md)            |
| [devServer.static](https://rspack.rs/config/dev-server#devserverstatic)                           | [server.publicDir](/config/server/public-dir.md)                    |
| [devServer.watchFiles](https://rspack.rs/config/dev-server#devserverwatchfiles)                   | [dev.watchFiles](/config/dev/watch-files.md)                        |

> For more configurations, refer to [Config Overview](/config/index.md).

## Middleware

Rsbuild's middleware implementation is built on [connect](https://github.com/senchalabs/connect), a lightweight HTTP server framework, and uses the standard Node.js `request` and `response` objects for handling HTTP interactions.

### Register middleware

Rsbuild provides three ways to register middleware:

1. Use the [dev.setupMiddlewares](/config/dev/setup-middlewares.md) configuration.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    setupMiddlewares: (middlewares) => {
      middlewares.push((req, res, next) => {
        next();
      });
    },
  },
};
```

2. In the Rsbuild plugin, you can register middleware through the [onBeforeStartDevServer](/plugins/dev/hooks.md#onbeforestartdevserver) hook.

```ts
const myPlugin = () => ({
  setup(api) {
    api.onBeforeStartDevServer(({ server }) => {
      server.middlewares.use((req, res, next) => {
        next();
      });
    });
  },
});
```

3. When using the Rsbuild JavaScript API, you can create a dev server instance through the [rsbuild.createDevServer](/api/javascript-api/instance.md#rsbuildcreatedevserver) method and use the `use` method to register middleware.

```ts
const server = await rsbuild.createDevServer();

server.middlewares.use((req, res, next) => {
  next();
});
```

### Integrate third-party server frameworks

When migrating from other server frameworks like Express, the original middleware may not work directly in Rsbuild. For example, Express-specific properties like `req.params`, `req.path`, `req.search`, and `req.query` aren't available in Rsbuild middleware.

To reuse existing middleware in Rsbuild, integrate your entire server application as middleware:

```ts title="rsbuild.config.ts"
import express from 'express';
import expressMiddleware from 'my-express-middleware';

// Initialize Express app
const app = express();

app.use(expressMiddleware);

export default {
  dev: {
    setupMiddlewares: (middlewares) => {
      middlewares.unshift(app);
    },
  },
};
```

## Custom server

To integrate Rsbuild's dev server into a custom server, use the `createDevServer` method to get the Rsbuild dev server instance and call its methods as needed.

For details, refer to [Rsbuild - createDevServer](/api/javascript-api/instance.md#rsbuildcreatedevserver).

---

# Source: https://rsbuild.dev/config/dev/setup-middlewares.md

# dev.setupMiddlewares

* **Type:**

```ts
type SetupMiddlewaresContext = {
  sockWrite: (
    type: string,
    data?: string | boolean | Record<string, any>,
  ) => void;
  environments: EnvironmentAPI;
};

type SetupMiddlewaresFn = (
  middlewares: {
    unshift: (...handlers: RequestHandler[]) => void;
    push: (...handlers: RequestHandler[]) => void;
  },
  context: SetupMiddlewaresContext,
) => void;

type SetupMiddlewares = SetupMiddlewaresFn | SetupMiddlewaresFn[];
```

* **Default:** `undefined`
* **Version:** `>= 1.4.0`

Used to add custom middleware to the dev server.

> See [Dev server - Middleware](/guide/basic/server.md#middleware) for more information.

## Basic usage

`setupMiddlewares` function receives a `middlewares` array, you can add custom middleware by `unshift` and `push` methods:

* Use `unshift` to prepend middleware to the array, executed earlier than the built-in middleware.
* Use `push` to append middleware to the array, executed later than the built-in middleware.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    setupMiddlewares: (middlewares) => {
      middlewares.unshift((req, res, next) => {
        console.log('first');
        next();
      });

      middlewares.push((req, res, next) => {
        console.log('last');
        next();
      });
    },
  },
};
```

The middleware can be an async function:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    setupMiddlewares: (middlewares) => {
      middlewares.unshift(async (req, res, next) => {
        await someAsyncOperation();
        next();
      });
    },
  },
};
```

`setupMiddlewares` also supports passing an array, each item of which is a function to set up middlewares:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    setupMiddlewares: [
      (middlewares) => {
        // ...
      },
      (middlewares) => {
        // ...
      },
    ],
  },
};
```

:::tip
In versions before Rsbuild 1.4.0, `setupMiddlewares` must pass an array.
:::

## Context object

The second parameter of the `setupMiddlewares` function is the `context` object, which provides some server context and APIs.

### environments

Provides Rsbuild's [environment API](/api/javascript-api/environment-api.md#environment-api), see [Dev server API - environments](/api/javascript-api/dev-server-api.md#environments) for more details.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    setupMiddlewares: (middlewares, { environments }) => {
      middlewares.unshift(async (req, _res, next) => {
        const webStats = await environments.web.getStats();
        console.log(webStats.toJson({ all: false }));
        next();
      });
    },
  },
};
```

### sockWrite

Sends some message to HMR client, see [Dev server API - sockWrite](/api/javascript-api/dev-server-api.md#sockwrite) for more details.

For example, if you send a `'static-changed'` message, the page will reload.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    setupMiddlewares: (middlewares, { sockWrite }) => {
      if (someCondition) {
        sockWrite('static-changed');
      }
    },
  },
};
```

---

# Source: https://rsbuild.dev/guide/framework/solid.md

# Solid

In this document, you will learn how to build a Solid application using Rsbuild.

## Create a Solid application

Use [create-rsbuild](/guide/start/quick-start.md#create-an-rsbuild-application) to create a Solid application with Rsbuild. Run the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs
  command={{
  npm: 'npm create rsbuild@latest',
  yarn: 'yarn create rsbuild',
  pnpm: 'pnpm create rsbuild@latest',
  bun: 'bun create rsbuild@latest',
}}
/>

Then select `Solid` when prompted to "Select framework".

## Use Solid in an existing project

To compile Solid components, you need to register the Rsbuild [Solid plugin](/plugins/list/plugin-solid.md). The plugin will automatically add the necessary configuration for Solid builds.

For example, register in `rsbuild.config.ts`:

```ts title="rsbuild.config.ts"
import { defineConfig } from '@rsbuild/core';
import { pluginBabel } from '@rsbuild/plugin-babel';
import { pluginSolid } from '@rsbuild/plugin-solid';

export default defineConfig({
  plugins: [
    pluginBabel({
      include: /\.(?:jsx|tsx)$/,
    }),
    pluginSolid(),
  ],
});
```

---

# Source: https://rsbuild.dev/config/output/source-map.md

# output.sourceMap

* **Type:**

```ts
type SourceMap =
  | boolean
  | {
      js?: Rspack.Configuration['devtool'];
      css?: boolean;
    };
```

* **Default:**

```ts
const defaultSourceMap = {
  js: mode === 'development' ? 'cheap-module-source-map' : false,
  css: false,
};
```

Configures whether to generate source map files and which source map format to generate.

:::tip What is a source map
A source map is an information file that stores source code mapping relationships. It records each location of the compiled code and its corresponding pre-compilation location. With source maps, you can directly view source code when debugging compiled code.
:::

## Default behavior

Rsbuild generates source maps using these rules by default:

* In development mode, source maps for JS files are generated for development debugging, while source maps for CSS files are not generated.
* In production mode, source maps for JS and CSS files are not generated to improve build performance.

## Boolean value

If `output.sourceMap` is `true`, source maps are generated according to the [mode](/config/mode.md), equivalent to:

```ts title="rsbuild.config.ts"
export default {
  output: {
    sourceMap: {
      js: mode === 'development' ? 'cheap-module-source-map' : 'source-map',
      css: true,
    },
  },
};
```

If `output.sourceMap` is `false`, no source map will be generated, equivalent to:

```ts title="rsbuild.config.ts"
export default {
  output: {
    sourceMap: {
      js: false,
      css: false,
    },
  },
};
```

## JS source map

The source map for JS files is controlled by `sourceMap.js` and accepts any source map format supported by Rspack's [devtool](https://rspack.rs/config/devtool) option. Setting it to `false` will disable the source map.

For example, to generate high-quality source maps in all environments:

```ts title="rsbuild.config.ts"
export default {
  output: {
    sourceMap: {
      js: 'source-map',
    },
  },
};
```

You can also set different source map formats based on the environment.

```ts title="rsbuild.config.ts"
export default {
  output: {
    sourceMap: {
      js:
        process.env.NODE_ENV === 'production'
          ? // Use a high quality source map format for production
            'source-map'
          : // Use a more performant source map format for development
            'cheap-module-source-map',
    },
  },
};
```

:::warning
Do not deploy source maps (`.map` files) to the public web server or CDN when using values such as `source-map` or `hidden-source-map` in production builds. Public source maps will expose your source code and may bring security risks.
:::

## CSS source map

The source map for CSS files is controlled by `sourceMap.css`. Setting it to `true` will enable the source map, while setting it to `false` will disable it.

To generate a source map for CSS files:

```ts title="rsbuild.config.ts"
export default {
  output: {
    sourceMap: {
      css: true,
    },
  },
};
```

In production builds, it is not recommended to enable both [output.injectStyles](/config/output/inject-styles.md) and `output.sourceMap.css`, as `output.injectStyles` will inject the source map into the JS bundles, which will increase the file size and slow down the page loading speed.

You can only enable the CSS file source map in development mode:

```ts title="rsbuild.config.ts"
export default {
  output: {
    injectStyles: true,
    sourceMap: {
      css: process.env.NODE_ENV === 'development',
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/security/sri.md

# security.sri

* **Type:**

```ts
type SriAlgorithm = 'sha256' | 'sha384' | 'sha512';

type SriOptions = {
  enable?: 'auto' | boolean;
  algorithm?: SriAlgorithm | SriAlgorithm[];
};
```

* **Default:** `undefined`

Adds an `integrity` attribute to `<script>` and `<link>` tags injected into HTML so the browser can verify the resource's integrity and prevent tampering.

> `security.sri` is implemented based on Rspack's [SubresourceIntegrityPlugin](https://rspack.rs/plugins/rspack/subresource-integrity-plugin)

## What is SRI

Subresource Integrity (SRI) is a security feature that enables browsers to verify that resources they fetch (for example, from a CDN) arrive without unexpected manipulation. It works by letting you provide a cryptographic hash that a fetched resource must match.

If the hash does not match, script tags are blocked from running and stylesheet links are not loaded.

For more on subresource integrity, see [Subresource Integrity - MDN](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity).

## Example

When using SRI, enable [html.crossorigin](/config/html/crossorigin.md) so resources can be properly validated during cross-origin loading.

```ts title="rsbuild.config.ts"
export default {
  security: {
    sri: {
      enable: 'auto',
    },
  },
  html: {
    crossorigin: 'anonymous',
  },
};
```

:::tip
If you do not set `html.crossorigin`, Rsbuild will automatically set it to `anonymous`.
:::

After enabling `security.sri`, the `<script>` and `<link>` tags generated by Rsbuild will include the `integrity` and `crossorigin` attributes:

```html
<script
  defer
  src="https://cdn.com/static/js/index.js"
  crossorigin="anonymous"
  integrity="sha384-d8fhhhTWXaPPIEMw+POJ9hqCIRvsFbegq/oef7k9R8Rpb8Dy95B2THPOECdZoLDF"
></script>

<link
  href="https://cdn.com/static/css/index.css"
  rel="stylesheet"
  crossorigin="anonymous"
  integrity="sha384-8U9HYzsHbf55cFZyiWIE29+QPYQ9WO+U5uT/ViFw0TOwM2Fbbb74ZegzRV/nvwrD"
/>
```

In addition, the [manifest file](/config/output/manifest.md#sri) generated by Rsbuild will also include an `integrity` field.

## Note

The `security.sri` in Rsbuild will only apply to the tags generated by Rspack and Rsbuild and will not apply to:

* The original tags in the HTML template.
* The tags inserted through client JavaScript code.

Rsbuild will handle the following `<link>` tags:

* `<link rel="preload">`
* `<link rel="stylesheet">`
* `<link rel="modulepreload">`

## Options

### enable

* **Type:** `'auto' | boolean`
* **Default:** `false`

Whether to enable SRI. `'auto'` means it is enabled in production mode and disabled in development mode.

```ts title="rsbuild.config.ts"
export default {
  security: {
    sri: {
      enable: 'auto',
    },
  },
};
```

> Typically, you do not need to enable SRI in development mode.

### algorithm

* **Type:** `SriAlgorithm | SriAlgorithm[]`
* **Default:** `'sha384'`

Specifies the algorithm used to compute the integrity hash.

For example, set to `sha512`:

```ts title="rsbuild.config.ts"
export default {
  security: {
    sri: {
      algorithm: 'sha512',
    },
  },
};
```

The generated value of integrity attribute will be prefixed with `sha512-`:

```html
<script
  defer
  src="https://cdn.com/static/js/index.js"
  crossorigin="anonymous"
  integrity="sha512-ShExVSs5q/j3ZBI/PeS0niJ4mBxh6tc08QN1uofI1dmGAx7ETMh8/VDddGRewxXQhjCgdgAnaiY3BfnWrUSmZA=="
></script>
```

Or configure multiple algorithms:

```ts title="rsbuild.config.ts"
export default {
  security: {
    sri: {
      algorithm: ['sha384', 'sha256'],
    },
  },
};
```

> Reference: [Cryptographic hash functions](https://www.w3.org/TR/SRI/#cryptographic-hash-functions).

## Version history

| Version | Changes                             |
| ------- | ----------------------------------- |
| v1.6.15 | Add support for multiple algorithms |

---

# Source: https://rsbuild.dev/guide/advanced/ssr.md

# Server-side rendering (SSR)

This chapter introduces how to implement SSR functionality using Rsbuild.

Rsbuild does not ship with SSR by default. Instead, it offers low-level APIs and configurations so framework developers can build SSR support. If you need SSR that works out of the box, consider a full-stack framework built on Rsbuild, such as [Modern.js](https://github.com/web-infra-dev/modern.js).

## What is SSR

SSR stands for "Server-Side Rendering". It means that the server generates the page's HTML and sends it to the client, rather than sending only an empty HTML shell and relying on JavaScript to generate the page content.

In traditional client-side rendering, the server sends an empty HTML shell and some JavaScript scripts to the client, which then fetches data from the server's API and fills the page with dynamic content. This leads to slow initial page loading times and negatively impacts user experience and SEO.

With SSR, the server generates HTML that already contains dynamic content and sends it to the client. This makes initial page loading faster and more SEO-friendly, as search engines can crawl the rendered page.

## File structure

A typical SSR application will have the following files:

```
- index.html
- server.js          # main application server
- src/
  - App.js           # exports app code
  - index.client.js  # client entry, mounts the app to a DOM element
  - index.server.js  # server entry, renders the app using the framework's SSR API
```

The `index.html` will need to include a placeholder where the server-rendered content should be injected:

```html
<div id="root"><!--app-content--></div>
```

## Create SSR configuration

In SSR scenarios, you need to generate web and node outputs at the same time for client-side rendering (CSR) and server-side rendering (SSR).

You can then use Rsbuild's [multi-environment builds](/guide/advanced/environments.md) capability to define the following configuration:

```ts title="rsbuild.config.ts"
export default {
  environments: {
    // Configure the web environment for browsers
    web: {
      source: {
        entry: {
          index: './src/index.client.js',
        },
      },
      output: {
        // Use 'web' target for the browser outputs
        target: 'web',
      },
      html: {
        // Custom HTML template
        template: './index.html',
      },
    },
    // Configure the node environment for SSR
    node: {
      source: {
        entry: {
          index: './src/index.server.js',
        },
      },
      output: {
        // Use 'node' target for the Node.js outputs
        target: 'node',
      },
    },
  },
};
```

## Custom server

Rsbuild provides the [Dev server API](/api/javascript-api/dev-server-api.md) and [environment API](/guide/advanced/environments.md#environment-api) to allow you to implement SSR.

Here is a basic example:

```ts title="server.mjs"
import express from 'express';
import { createRsbuild } from '@rsbuild/core';

async function initRsbuild() {
  const rsbuild = await createRsbuild({
    config: {
      server: {
        middlewareMode: true,
      },
    },
  });
  return rsbuild.createDevServer();
}

async function startDevServer() {
  const app = express();
  const rsbuild = await initRsbuild();
  const { environments } = rsbuild;

  // SSR when accessing /index.html
  app.get('/', async (req, res, next) => {
    try {
      // Load server bundle
      const bundle = await environments.node.loadBundle('index');
      const template = await environments.web.getTransformedHtml('index');
      const rendered = bundle.render();
      // Insert rendered content into HTML template
      const html = template.replace('<!--app-content-->', rendered);

      res.writeHead(200, { 'Content-Type': 'text/html' });
      res.end(html);
    } catch (err) {
      logger.error('SSR failed.');
      logger.error(err);
      next();
    }
  });
  app.use(rsbuild.middlewares);

  const server = app.listen(rsbuild.port, async () => {
    await rsbuild.afterListen();
  });
  rsbuild.connectWebSocket({ server });
}

startDevServer();
```

## Modify startup script

When you use a custom server, change the startup command from `rsbuild dev` to `node ./server.mjs`.

To preview the production SSR output, update the preview command as well. For an example of a production SSR server, see [Example](https://github.com/rstackjs/rstack-examples/blob/main/rsbuild/ssr-express/prod-server.mjs).

```json title="package.json"
{
  "scripts": {
    "build": "rsbuild build",
    "dev": "node ./server.mjs",
    "preview": "node ./prod-server.mjs"
  }
}
```

You can now run `npm run dev` to start the dev server with SSR and open `http://localhost:3000/` to see the server-rendered content in the HTML page.

## Get manifest

By default, Rsbuild automatically inserts the scripts and links for the current page into the HTML template. You can retrieve the compiled template with [getTransformedHtml](/api/javascript-api/environment-api.md#gettransformedhtml).

When you need to dynamically generate HTML on the server side, you will need to inject the URLs of JavaScript and CSS assets into the HTML. By configuring [output.manifest](/config/output/manifest.md), you can easily obtain the manifest information of these assets. Here is an example:

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

```ts title="server.ts"
async function renderHtmlPage(): Promise<string> {
  const manifest = await fs.promises.readFile('./dist/manifest.json', 'utf-8');
  const { entries } = JSON.parse(manifest);

  const { js, css } = entries['index'].initial;

  const scriptTags = js
    .map((url) => `<script src="${url}" defer></script>`)
    .join('\n');
  const styleTags = css
    .map((file) => `<link rel="stylesheet" href="${file}">`)
    .join('\n');

  return `
    <!DOCTYPE html>
    <html>
      <head>
        ${scriptTags}
        ${styleTags}
      </head>
      <body>
        <div id="root"></div>
      </body>
    </html>`;
}
```

## Examples

* [SSR + Express Example](https://github.com/rstackjs/rstack-examples/blob/main/rsbuild/ssr-express)
* [SSR + Express + Manifest Example](https://github.com/rstackjs/rstack-examples/blob/main/rsbuild/ssr-express-with-manifest)

## SSR-specific plugins

When developing Rsbuild plugins, if you need to add specific logic for SSR, you can distinguish it by `target`.

* Modify Rsbuild configuration for SSR via [modifyEnvironmentConfig](/plugins/dev/hooks.md#modifyenvironmentconfig):

```js
export const myPlugin = () => ({
  name: 'my-plugin',
  setup(api) {
    api.modifyEnvironmentConfig((config) => {
      if (config.target === 'node') {
        // SSR-specific Rsbuild config
      }
    });
  },
});
```

* Modify Rspack configuration for SSR via [modifyRspackConfig](/plugins/dev/hooks.md#modifyrspackconfig):

```js
export const myPlugin = () => ({
  name: 'my-plugin',
  setup(api) {
    api.modifyRspackConfig((config, { target }) => {
      if (target === 'node') {
        // SSR-specific Rspack config
      }
    });
  },
});
```

* Transform code for SSR and client separately via [transform](/plugins/dev/core.md#apitransform):

```js
export const myPlugin = () => ({
  name: 'my-plugin',
  setup(api) {
    api.transform({ test: /foo\.js$/, targets: ['web'] }, ({ code }) => {
      // transform client code
    });

    api.transform({ test: /foo\.js$/, targets: ['node'] }, ({ code }) => {
      // transform server code
    });
  },
});
```

---

# Source: https://rsbuild.dev/guide/basic/static-assets.md

# Static assets

Rsbuild supports importing static assets, including images, fonts, audio, and video.

:::tip What are static assets
Static assets are files that are part of a web application and don't change during use. Examples include images, fonts, media files, stylesheets, and JavaScript files. These assets are typically stored on a web server or CDN and delivered to the user's browser when they access the application. Because they don't change, static assets can be cached by the browser, improving application performance.
:::

## Asset formats

Rsbuild supports these formats 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).

:::tip SVG images
SVG images are a special case. Rsbuild supports converting SVG to React components, so SVG files are processed separately. For details, see [SVGR Plugin](/plugins/list/plugin-svgr.md).
:::

## Importing assets in JavaScript files

In JavaScript files, import static assets using relative paths:

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

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

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

Importing with [alias](/guide/advanced/alias.md) is also supported:

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

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

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

### URL assets

Rsbuild supports using JavaScript's native [URL](https://developer.mozilla.org/docs/Web/API/URL) and [import.meta.url](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/import.meta) to import static assets.

```tsx
const logo = new URL('./static/logo.png', import.meta.url).href;

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

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

When using `new URL()` to reference `.js` or `.ts` files, they're treated as URL assets and aren't processed by Rsbuild's built-in SWC loader.

```tsx
// foo.ts will remain the original content and be output to the dist directory
const fooTs = new URL('./foo.ts', import.meta.url).href;

console.log(fooTs); // "/static/foo.[hash].ts"
```

Similarly, when using `new URL()` to reference `.css` or `.scss` files, they're treated as URL assets and aren't processed by Rsbuild's built-in CSS loaders.

```tsx
// foo.css will remain the original content and be output to the dist directory
const fooCss = new URL('./foo.css', import.meta.url).href;

console.log(fooCss); // "/static/foo.[hash].css"
```

## Importing assets in CSS files

In CSS files, you can reference static assets using relative paths:

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

Importing with [alias](/guide/advanced/alias.md) is also supported:

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

If you want to reference static assets using absolute paths in CSS files:

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

By default, Rsbuild's built-in `css-loader` will resolve absolute paths in `url()` and look for the specified modules. To skip resolving absolute paths, you can configure [`tools.cssLoader`](/config/tools/css-loader.md#toolscssloader) to filter out specific paths. Filtered paths will remain unchanged in the code.

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

## Inline assets

The result of importing static assets depends on the file size:

* If the file size is less than 4KiB, it will be converted to a base64 string and inlined in the code.
* If the file size is larger than 4KiB, a URL will be returned and the file will be emitted to the output directory.

```js
import largeImage from './static/largeImage.png';
import smallImage from './static/smallImage.png';

console.log(largeImage); // "/static/largeImage.[hash].png"
console.log(smallImage); // "data:image/png;base64,iVBORw0KGgo..."
```

Adding the `?url` query parameter ensures the asset is always loaded as a separate file and returns a URL:

```js
import image from './static/image.png?url';

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

Adding the `?inline` query parameter ensures the asset is always inlined in the code, regardless of file size:

```js
import image from './static/image.png?inline';

console.log(image); // "data:image/png;base64,iVBORw0KGgo..."
```

For a more detailed introduction to asset inlining, refer to the [Static Asset Inlining](/guide/optimization/inline-assets.md) section.

## Importing as string

Rsbuild supports using the `?raw` query parameter to import the raw content of static assets as a string in JavaScript.

```ts
import rawSvg from './static/logo.svg?raw';

console.log(rawSvg); // The raw content of the SVG file
```

Rsbuild also supports importing the raw content of JavaScript, TypeScript, and JSX files through the `?raw` query parameter.

```ts
import rawJs from './script1.js?raw';
import rawTs from './script2.ts?raw';
import rawJsx from './script3.jsx?raw';
import rawTsx from './script4.tsx?raw';

console.log(rawJs); // The raw content of the JS file
console.log(rawTs); // The raw content of the TS file
console.log(rawJsx); // The raw content of the JSX file
console.log(rawTsx); // The raw content of the TSX file
```

You can also use the `?raw` query parameter to import the raw content of CSS files, see [CSS](/guide/styling/css-usage.md#raw).

:::tip
Rsbuild >= 1.3.0 supports the `?raw` query parameter, and >= 1.4.0 supports importing the raw content of JS and TS files.
:::

## Output files

When static assets are imported, they will be output to the dist directory. You can:

* Use [output.filename](/config/output/filename.md) to modify the output filename.
* Use [output.distPath](/config/output/dist-path.md) to modify the output path.

Read [Output Files](/guide/basic/output-files.md) for details.

## URL prefix

The URL returned after importing an asset will automatically include the path prefix:

* In development, use [dev.assetPrefix](/config/dev/asset-prefix.md) to set the path prefix.
* In production, use [output.assetPrefix](/config/output/asset-prefix.md) to set the path prefix.
* When either `dev.assetPrefix` or `output.assetPrefix` is not configured, the value of [server.base](/config/server/base.md) will be automatically used as the default prefix.

For example, you can set `output.assetPrefix` to `https://example.com`:

```ts title="rsbuild.config.ts"
export default {
  output: {
    assetPrefix: 'https://example.com',
  },
};
```

```js
import logo from './static/logo.png';

console.log(logo); // "https://example.com/static/logo.[hash].png"
```

## Public folder

The public folder at the project root can be used to place static assets. These assets won't be built by Rsbuild and can be directly referenced via URL.

* When you start the dev server, these assets will be served under the [server.base](/config/server/base.md) path (default `/`).
* When you perform a production build, these assets will be copied to the [dist directory](/guide/basic/output-files.md).

For example, you can place files such as `robots.txt`, `manifest.json`, or `favicon.ico` in the public folder.

### How to reference

You can reference files in the `public` directory via URL.

For example, in an HTML template, the `./public/favicon.ico` file can be referenced as `/favicon.ico`. [BASE\_URL](/guide/advanced/env-vars.md#processenvpublic_base_path) is the base path of the server.

```html title="index.html"
<link rel="icon" href="<%= process.env.BASE_URL %>/favicon.ico" />
```

### Notes

Keep these points in mind when using the `public` folder:

* When referencing assets in the public folder via URL, use absolute paths instead of relative paths to ensure assets can be accessed correctly after deployment.

```html title="src/index.html"
<!-- Wrong -->
<link rel="icon" href="../public/favicon.ico" />

<!-- Correct -->
<link rel="icon" href="/favicon.ico" />
```

* Avoid importing files from the public directory into your source code. The correct approach is to reference them by URL. You can place static assets that need to be imported into source code in the `/src/assets` directory.

```js title="src/index.js"
// Wrong
import logo from '../public/logo.png';

// Correct
import logo from './assets/logo.png';
```

* During the production build, files in the public folder are copied to the output folder (default is `dist`). Be careful to avoid name conflicts with output files. When files in the `public` folder have the same name as outputs, the outputs have higher priority and will overwrite the conflicting public folder files. This feature can be disabled by setting [server.publicDir.copyOnBuild](/config/server/public-dir.md) to `false`.

### Custom behavior

Rsbuild provides the [server.publicDir](/config/server/public-dir.md) option which can be used to customize the name and behavior of the public folder, as well as to disable it.

```ts title="rsbuild.config.ts"
export default {
  server: {
    publicDir: false,
  },
};
```

## 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 `@rsbuild/core` package is installed, you can reference the [preset types](/guide/basic/typescript.md#preset-types) provided by `@rsbuild/core`:

```ts
/// <reference types="@rsbuild/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 that TypeScript can correctly identify the type definition.

## Extend asset types

If the built-in asset types in Rsbuild cannot meet your requirements, you can extend additional static asset types in the following ways.

### Use `source.assetsInclude`

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

```ts title="rsbuild.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); // "/static/myFile.[hash].pdf"
```

### Use `tools.rspack`

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

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

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack(config, { addRules }) {
      addRules([
        {
          test: /\.pdf$/,
          // converts asset to a separate file and exports the URL address.
          type: 'asset/resource',
        },
      ]);
    },
  },
};
```

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

### Related configurations

Extended static asset types will be affected by the following configurations:

* [output.filename.assets](/config/output/filename.md): Set the name of extended static assets.
* [output.distPath.assets](/config/output/dist-path.md): Set the output directory of extended static assets.
* [output.dataUriLimit.assets](/config/output/data-uri-limit.md): Set the threshold of inlining for extended static assets.

## Custom rules

In some scenarios, you may need to bypass the built-in assets processing rules of Rsbuild and add some custom rules.

Taking PNG image as an example, you need to:

1. Modify the built-in Rspack config via [tools.bundlerChain](/config/tools/bundler-chain.md) to exclude `.png` files using the `exclude` method.
2. Add custom asset processing rules via [tools.rspack](/config/tools/rspack.md).

```ts title="rsbuild.config.ts"
export default {
  tools: {
    bundlerChain(chain, { CHAIN_ID }) {
      chain.module
        // Use `CHAIN_ID.RULE.IMAGE` to locate the built-in image rule
        .rule(CHAIN_ID.RULE.IMAGE)
        .exclude.add(/\.png$/);
    },
    rspack(config, { addRules }) {
      addRules([
        {
          test: /\.png$/,
          // Add a custom loader to handle png images
          loader: 'custom-png-loader',
        },
      ]);
    },
  },
};
```

## Image format

When using image assets, you can choose an appropriate image format according to the pros and cons in the table below.

| Format | Pros                                                                                                      | Cons                                                                                | Scenarios                                                                                                                                              |
| ------ | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| PNG    | Lossless compression, no loss of picture details, no distortion, support for translucency                 | Not suitable for pictures with complex color tables                                 | Suitable for pictures with few colors and well-defined borders, suitable for logos, icons, transparent images and other scenes                         |
| JPG    | Rich colors                                                                                               | Lossy compression, which will cause image distortion, does not support transparency | Suitable for pictures with a large number of colors, gradients, and overly complex pictures, suitable for portrait photos, landscapes and other scenes |
| WebP   | Supports both lossy and lossless compression, supports transparency, and is much smaller than PNG and JPG | iOS compatibility is not good                                                       | Pixel images of almost any scene, and the hosting environment that supports WebP, should prefer WebP image format                                      |
| SVG    | Lossless format, no distortion, supports transparency                                                     | Not suitable for complex graphics                                                   | Suitable for vector graphics, suitable for icons                                                                                                       |

---

# Source: https://rsbuild.dev/guide/basic/static-deploy.md

# Deploy static site

This section explains how to deploy Rsbuild build outputs as a static site.

## Background information

Before starting the deployment, you should understand the following:

* The CLI commands used for building and previewing outputs.
* The directory structure of the build outputs.
* The URL prefix of static assets.

### Build commands

The build commands provided by Rsbuild are:

* [build command](/guide/basic/cli.md#rsbuild-build), used to generate the build outputs for production deployment.
* [preview command](/guide/basic/cli.md#rsbuild-preview), used to preview the production build outputs locally. Note that you must first execute the `rsbuild build` command to generate the build outputs.

```json title="package.json"
{
  "scripts": {
    "build": "rsbuild build",
    "preview": "rsbuild preview"
  }
}
```

:::tip
The preview command is only used for local preview. Do not use it for production servers, as it is not designed for that.
:::

### Output directory

Rsbuild's build outputs typically include HTML, JS, CSS, and other assets, and are output to the `dist` directory by default. You can change the name and structure of the dist directory with configuration options. See the [Output Files](/guide/basic/output-files.md) section for more information.

```bash
dist
├── static
│   ├── image
│   ├── css
│   └── js
└── [name].html
```

### Asset prefix

We can divide the build output into two parts: **HTML files** and **static assets**:

* HTML files refer to files with the `.html` suffix in the output directory, which usually need to be deployed on the server.
* Static assets are located in the `static` directory of the output folder, which contains assets such as JavaScript, CSS, and images. They can be deployed either on the server or on a CDN.

If you deploy static assets to a subdirectory on the server, set [output.assetPrefix](/config/output/asset-prefix.md) as the base path:

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

export default defineConfig({
  output: {
    assetPrefix: '/some-base-folder/',
  },
});
```

If you prefer to serve static assets from a CDN for better performance instead of alongside the HTML on your server, set [output.assetPrefix](/config/output/asset-prefix.md) to the CDN address so the application can reference the assets correctly.

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

export default defineConfig({
  output: {
    assetPrefix: 'https://cdn.com/path/',
  },
});
```

With this configuration, when referencing static assets in HTML, the specified prefix will be automatically added. For example:

```html
<script src="https://cdn.com/path/static/js/index.some-hash.js"></script>
```

## Deployment platforms

The following sections describe how to deploy on several common platforms.

> Platform names are listed in alphabetical order.

### Cloudflare Pages

[Cloudflare Pages](https://developers.cloudflare.com/pages/) is a static site hosting platform provided by Cloudflare.

You can follow the [Cloudflare Pages - Git integration guide](https://developers.cloudflare.com/pages/get-started/git-integration/) to integrate with Git and deploy your site to Cloudflare Pages.

When configuring, complete the following fields under "Build settings":

* **Build command**: fill in the project's build command, typically `npm run build`.
* **Build output directory**: fill in the project's output directory, which defaults to `dist`.

Then click the **Save and Deploy** button to start the deployment.

### GitHub pages

[GitHub Pages](https://pages.github.com/) is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub.

The following are step-by-step instructions for deploying to GitHub Pages.

1. Configure the URL prefix for static assets using [output.assetPrefix](/config/output/asset-prefix.md).

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

export default defineConfig({
  output: {
    // Please replace <REPO_NAME> with the repository name.
    // For example, "/my-project/"
    assetPrefix: '/<REPO_NAME>/',
  },
});
```

2. Open the "Settings" page of your GitHub repository, click "Pages" in the left menu to access the GitHub Pages configuration page.
3. Select "Source" → "GitHub Actions" and click "create your own" to create a GitHub Action configuration file.
4. Paste the following content into the editor and name the file `github-pages.yml` (you can adjust the content and filename as needed).

```yaml title="github-pages.yml"
# Sample workflow for building and deploying a Rsbuild site to GitHub Pages
name: Rsbuild Deployment

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ['main']
  # Allows you to run this workflow manually from the actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment
concurrency:
  group: 'pages'
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      # If you use other package managers like yarn or pnpm,
      # you will need to install them first
      - name: Install dependencies
        run: npm i

      - name: Build
        run: npm run build

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './dist'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
```

5. Commit and wait for GitHub Actions to execute. Once complete, you can visit `https://<USERNAME>.github.io/<REPO_NAME>/` to view the deployed page.

### Netlify

[Netlify Core](https://netlify.com/) is a frontend cloud solution for developers to build and deploy future-proof digital solutions with modern, composable tooling.

#### Add new site

Netlify provides a detailed guide. You can follow the instructions in [Netlify - Add new site](https://docs.netlify.com/welcome/add-new-site/), configure the basic settings, and start the deployment.

You need to configure the following fields:

* **Build command**: fill in the project's build command, typically `npm run build`.
* **Publish directory**: fill in the project's output directory, which defaults to `dist`.

Then click the **Deploy site** button to start the deployment.

#### Custom domains

If you want to make your sites accessible at custom domain names, you can configure this in Netlify's "Domain management" section.

> Detailed guide: [Netlify - Custom domains](https://docs.netlify.com/domains-https/custom-domains/).

### Vercel

[Vercel](https://vercel.com/) is a platform for developers that provides the tools, workflows, and infrastructure you need to build and deploy your web apps faster, without the need for additional configuration.

#### Add new site

Vercel provides a detailed guide. You can follow [Vercel - Projects](https://vercel.com/docs/projects/overview) to create a project in your dashboard, configure the basic settings, and start the deployment.

Only the following fields under "Build and Output Settings" need to be configured:

* **Output directory**: fill in the project's output directory, which defaults to `dist`.

Then click the **Deploy** button to start the deployment.

#### Configure domains

If you want to make your sites accessible at custom domain names, you can configure this in Vercel's "Domains" section.

> Detailed guide: [Vercel - Domains](https://vercel.com/docs/projects/domains).

### Zephyr Cloud

[Zephyr Cloud](https://zephyr-cloud.io) is a zero-config deployment platform that integrates directly into your build process and provides global edge distribution for federated applications.

#### How to deploy

Follow the steps in [zephyr-rsbuild-plugin](https://www.npmjs.com/package/zephyr-rsbuild-plugin).

During the build process, your application will be automatically deployed and you'll receive a deployment URL. Zephyr Cloud handles asset optimization, global CDN distribution, module federation setup, and provides automatic rollback capabilities.

Start for free today at [zephyr-cloud.io](https://zephyr-cloud.io).

---

# Source: https://rsbuild.dev/config/server/strict-port.md

# server.strictPort

* **Type:** `boolean`
* **Default:** `false`

When a port is occupied, Rsbuild will automatically increment the port number until an available port is found.

Set `strictPort` to `true` and Rsbuild will throw an exception when the port is occupied.

## Example

### Basic usage

Enable strict port mode to ensure the dev server fails if the specified port is occupied:

```ts title="rsbuild.config.ts"
export default {
  server: {
    strictPort: true,
  },
};
```

### Use with specific port

When you need to ensure your application runs on a specific port:

```ts title="rsbuild.config.ts"
export default {
  server: {
    port: 3333,
    strictPort: true,
  },
};
```

With this configuration, if port 3333 is already in use, Rsbuild will throw an error instead of automatically using port 3334.

---

# Source: https://rsbuild.dev/config/tools/style-loader.md

# tools.styleLoader

* **Type:** `Object | Function`
* **Default:** `{}`

The config of [style-loader](https://github.com/webpack/style-loader) can be set through `tools.styleLoader`.

It is worth noting that Rsbuild does not enable `style-loader` by default. You can use [output.injectStyles](/config/output/inject-styles.md) config to enable it.

## Object type

When `tools.styleLoader` is an object, it will be merged with the default configuration using `Object.assign`.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    styleLoader: {
      insert: 'head',
    },
  },
};
```

## Function type

When `tools.styleLoader` is a function, the default options will be passed in as the first parameter. You can directly modify this object or return a new object as the final options to be used. For example:

```ts title="rsbuild.config.ts"
export default {
  tools: {
    styleLoader: (config) => {
      config.insert = 'head';
      return config;
    },
  },
};
```

---

# Source: https://rsbuild.dev/guide/framework/svelte.md

# Svelte

In this document, you will learn how to build a Svelte application using Rsbuild.

## Create a Svelte application

Use [create-rsbuild](/guide/start/quick-start.md#create-an-rsbuild-application) to create a Svelte application with Rsbuild. Run the following command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs
  command={{
  npm: 'npm create rsbuild@latest',
  yarn: 'yarn create rsbuild',
  pnpm: 'pnpm create rsbuild@latest',
  bun: 'bun create rsbuild@latest',
}}
/>

Then select `Svelte` when prompted to "Select framework".

## Use Svelte in an existing project

To compile Svelte components (`.svelte` files), you need to register the Rsbuild [Svelte plugin](/plugins/list/plugin-svelte.md). The plugin will automatically add the necessary configuration for Svelte builds.

For example, register in `rsbuild.config.ts`:

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

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

---

# Source: https://rsbuild.dev/config/tools/swc.md

# Source: https://rsbuild.dev/guide/configuration/swc.md

# Configure SWC

[SWC](https://github.com/swc-project/swc) (Speedy Web Compiler) is a transformer and minimizer for JavaScript and TypeScript based on Rust. SWC provides similar functionality to Babel and Terser, and it is 20x faster than Babel on a single thread and 70x faster on four cores.

Rsbuild enables the following SWC features by default:

* Transform JavaScript and TypeScript code using Rspack's [builtin:swc-loader](https://rspack.rs/guide/features/builtin-swc-loader), which is the Rust version of [swc-loader](https://github.com/swc-project/pkgs/tree/main/packages/swc-loader).
* Minify JavaScript code using Rspack's [SwcJsMinimizerRspackPlugin](https://rspack.rs/plugins/rspack/swc-js-minimizer-rspack-plugin).

## Loader options

The options for `builtin:swc-loader` are the same as those for the JS version of `swc-loader`. Rsbuild exposes some options to configure `builtin:swc-loader`:

* [tools.swc](/config/tools/swc.md)：to configure the options for `builtin:swc-loader`.
* [source.include](/config/source/include.md)：to specify files that need to be compiled by SWC.
* [source.exclude](/config/source/exclude.md)：to exclude files that do not need to be compiled by SWC.

Here are some examples:

### Register SWC plugin

`tools.swc` can be used to register SWC's Wasm plugins, for example, registering [@swc/plugin-styled-components](https://npmjs.com/package/@swc/plugin-styled-components):

```js
export default {
  tools: {
    swc: {
      jsc: {
        experimental: {
          plugins: [['@swc/plugin-styled-components', {}]],
        },
      },
    },
  },
};
```

> You can check out the [awesome-swc](https://github.com/swc-contrib/awesome-swc) repository to see the SWC plugins available in the community.

### SWC plugin version

Please note that the SWC plugin is still an experimental feature, and the SWC Wasm plugin is currently not backward compatible. The version of the SWC plugin is closely tied to the version of `swc_core` that Rspack depends on.

This means that you must choose an SWC plugin that matches the current version of `swc_core` to ensure that it works properly. If the version of the SWC plugin you are using does not match the version of `swc_core` that Rspack depends on, Rspack will throw an error during the build process. Please refer to [Rspack FAQ - SWC Plugin Version Unmatched](https://rspack.rs/errors/swc-plugin-version) for more information.

### Enable Emotion support

Example of enabling the Emotion support using the `builtin:swc-loader`:

```js
export default {
  tools: {
    swc: {
      jsc: {
        experimental: {
          plugins: [['@swc/plugin-emotion', {}]],
        },
      },
    },
  },
};
```

For more options, please refer to [@swc/plugin-emotion](https://npmjs.com/package/@swc/plugin-emotion).

### Enable Relay support

Example of enabling the Relay support using the `builtin:swc-loader`:

```js
export default {
  tools: {
    swc: {
      jsc: {
        experimental: {
          plugins: [['@swc/plugin-relay', {}]],
        },
      },
    },
  },
};
```

For more options, please refer to [@swc/plugin-relay](https://npmjs.com/package/@swc/plugin-relay).

## Minimizer options

Rsbuild provides the [output.minify.js](/config/output/minify.md) option to configure the SwcJsMinimizerRspackPlugin. Here are some examples:

### Exclude files

You can exclude certain files from being minified using the `exclude` option:

```ts
export default {
  output: {
    minify: {
      jsOptions: {
        exclude: /foo\/bar/,
      },
    },
  },
};
```

## Switching minifier

See [output.minify - Switching minifier](/config/output/minify.md#switching-minifier) to learn how to switch to other JavaScript minifier.

---

# Source: https://rsbuild.dev/guide/styling/tailwindcss-v3.md

# Tailwind CSS v3

[Tailwind CSS](https://v3.tailwindcss.com/) is a CSS framework and design system based on utility classes, which can quickly add common styles to components and supports flexible extension of theme styles.

You can integrate Tailwind CSS in Rsbuild via PostCSS plugins.

## Installing Tailwind CSS

Rsbuild has built-in support for PostCSS, you can install `tailwindcss` package to integrate Tailwind CSS:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add tailwindcss@^3 -D" />

## Configuring PostCSS

You can register the `tailwindcss` PostCSS plugin through [postcss.config.cjs](https://npmjs.com/package/postcss-loader#config) or [tools.postcss](/config/tools/postcss.md).

```js title="postcss.config.cjs"
module.exports = {
  plugins: {
    tailwindcss: {},
  },
};
```

## Configuring Tailwind CSS

Create a `tailwind.config.js` file in the root directory of your project and add the following content:

```js title="tailwind.config.js"
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{html,js,ts,jsx,tsx}'],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

:::tip
The above configuration is for reference only and can be modified to suit the needs of your project. For example, non-TypeScript projects do not need to include ts and tsx files.
:::

Note that the `content` option should include the paths to all source files that contain Tailwind class names. For details, see [tailwindcss - Content Configuration](https://v3.tailwindcss.com/docs/content-configuration).

```js title="tailwind.config.js"
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{html,js,ts,jsx,tsx}',
    '../../lib1/src/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

### Other configuration methods

* You can directly pass the Tailwind CSS configuration to `postcss.config.cjs`:

```js title="postcss.config.cjs"
module.exports = {
  plugins: {
    tailwindcss: {
      content: ['./src/**/*.{html,js,ts,jsx,tsx}'],
      // ...other options
    },
  },
};
```

* You can also set the Tailwind CSS configuration through [tools.postcss](/config/tools/postcss.md):

```js title="rsbuild.config.js"
import tailwindcss from 'tailwindcss';

export default {
  tools: {
    postcss: {
      postcssOptions: {
        plugins: [
          tailwindcss({
            content: ['./src/**/*.{html,js,ts,jsx,tsx}'],
            // ...other options
          }),
        ],
      },
    },
  },
};
```

But we recommend placing the Tailwind CSS configuration in `tailwind.config.*` because other methods may cause the Tailwind CSS build performance to degrade, refer to [tailwindcss/issues/14229](https://github.com/tailwindlabs/tailwindcss/issues/14229).

## Importing CSS

Add the `@tailwind` directives in your CSS entry file:

```css title="main.css"
@tailwind base;
@tailwind components;
@tailwind utilities;
```

Depending on your needs, you can selectively import the CSS styles provided by Tailwind CSS. Please refer to the [@tailwind documentation](https://v3.tailwindcss.com/docs/functions-and-directives#tailwind) for detailed usage of the `@tailwind` directives.

## Done

You have now completed all the steps to integrate Tailwind CSS in Rsbuild!

You can use Tailwind's utility classes in any component or HTML, such as:

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

For more usage details, refer to the [Tailwind CSS documentation](https://v3.tailwindcss.com/).

## VS Code extension

Tailwind CSS provides a [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) plugin for VS Code to automatically complete Tailwind CSS class names, CSS functions, and directives.

You can install this plugin in VS Code to enable the autocompletion feature.

## Optimize build performance

When using Tailwind CSS, if the `content` field in `tailwind.config.js` is not correctly configured, this can lead to poor build performance and HMR performance. This is because Tailwind CSS internally matches files based on the glob defined in `content`. The more files it matches, the greater the performance overhead.

Therefore, we recommend that you specify the paths to be scanned accurately to avoid unnecessary performance overhead. For example, only include HTML or JS files in the project source code that actually contain Tailwind class names, and avoid including irrelevant files or directories, especially the `node_modules` directory.

Here is a bad example of scanning the `node_modules`:

```js title="tailwind.config.js"
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{html,js,ts,jsx,tsx}',
    // Scanning a large number of files, leading to performance degradation
    './node_modules/**/*.js',
  ],
};
```

Sometimes, you may accidentally scan the `node_modules` directory, for example, when scanning files in a monorepo:

```js title="tailwind.config.js"
module.exports = {
  content: [
    './src/**/*.{html,js,ts,jsx,tsx}',
    // Incorrectly includes the `packages/ui/node_modules` directory
    // Should be '../../packages/ui/src/**/*.{html,js,ts,jsx,tsx}'
    '../../packages/ui/**/*.{html,js,ts,jsx,tsx}',
  ],
};
```

## Optimize CSS size

To optimize the size of Tailwind CSS styles, you can try [rsbuild-plugin-tailwindcss](https://github.com/rstackjs/rsbuild-plugin-tailwindcss).

This plugin reads the module graph information of Rspack, automatically sets the accurate `content` configuration to generate minimal Tailwind CSS styles.

```ts title="rsbuild.config.ts"
import { pluginTailwindCSS } from 'rsbuild-plugin-tailwindcss';

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

> See [rsbuild-plugin-tailwindcss](https://github.com/rstackjs/rsbuild-plugin-tailwindcss) for more information.

---

# Source: https://rsbuild.dev/guide/styling/tailwindcss.md

# Tailwind CSS v4

[Tailwind CSS](https://tailwindcss.com/) is a CSS framework and design system based on utility classes, which can quickly add common styles to components and supports flexible extension of theme styles.

You can integrate Tailwind CSS in Rsbuild via PostCSS plugins.

## Choosing Tailwind CSS version

This document introduces the integration of Tailwind CSS v4.

Please note that Tailwind CSS v4 uses many modern CSS features, such as [Cascade Layers](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Cascade_layers), if your target browser does not support these features, please use Tailwind CSS v3 first, see [Using Tailwind CSS v3](/guide/styling/tailwindcss-v3.md) for more details.

More information can be found in [Tailwind CSS - Compatibility](https://tailwindcss.com/docs/compatibility).

## Installing Tailwind CSS

Rsbuild has built-in support for PostCSS, you can install `tailwindcss` and `@tailwindcss/postcss` packages to integrate Tailwind CSS:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add tailwindcss @tailwindcss/postcss -D" />

## Configuring PostCSS

You can register the Tailwind CSS PostCSS plugin through [postcss.config.cjs](https://npmjs.com/package/postcss-loader#config) or [tools.postcss](/config/tools/postcss.md).

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

## Importing CSS

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 `@tailwind` directive at the beginning of your `.css` file, see [Tailwind CSS - Compatibility](https://tailwindcss.com/docs/compatibility#sass-less-and-stylus) for more details.
:::

## Done

You have now completed all the steps to integrate Tailwind CSS in Rsbuild!

You can use Tailwind's utility classes in any component or HTML, such as:

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

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

## VS Code extension

Tailwind CSS provides a [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) plugin for VS Code to automatically complete Tailwind CSS class names, CSS functions, and directives.

You can install this plugin in VS Code to enable the autocompletion feature.

---

# Source: https://rsbuild.dev/config/output/target.md

# output.target

* **Type:**

```ts
type RsbuildTarget = 'web' | 'node' | 'web-worker';
```

* **Default:** `'web'`
* **Version:** `>= 1.0.0`

Sets the build target for Rsbuild.

Rsbuild supports multiple build targets for running in different environments. After setting the target type, Rsbuild's default configuration will change accordingly.

## Default target

The target is `'web'` by default, building outputs for browsers.

Rsbuild reads the [Browserslist config](https://github.com/browserslist/browserslist) in the project to determine the range of supported browsers.

## Optional values

In addition to `'web'`, `target` can also be set to the following values:

* `'node'`: Build for Node.js environment, usually used in SSR or other scenarios.
* `'web-worker'`: Build for Web Workers environment.

For example, to build for the Node.js environment:

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

## Parallel builds

You can use [environments](/config/environments.md) to build multiple targets in parallel.

To build `web` and `node` outputs simultaneously, use [environments](/config/environments.md):

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

## Node target

Refers to the build target for running in the Node.js environment, usually used in scenarios such as SSR.

When `target` is set to `'node'`, Rsbuild will:

* Set Rspack's [target](https://rspack.rs/config/target) to `'node'`.
* No HTML files will be generated, and HTML-related logic will not be executed, since HTML is not required in the Node.js environment.
* The default code split strategy will be disabled, but dynamic import can still work.
* Disable HMR.
* Set the default value of Browserslist to `['node >= 16']`.
* Set the default value of [output.emitCss](/config/output/emit-css.md) to `false`. This means CSS code will not be extracted to separate files, but CSS Modules id information will be included in the bundle.

### Node addons

When `target` is set to `'node'`, Rsbuild allows you to import Node.js [Addons](https://nodejs.org/api/addons.html) in JavaScript files.

For example:

```js title="src/index.js"
import addon from './addon.node';

addon.doSomething();
```

The referenced addons file will be output to the `dist` directory:

```
dist/index.js
dist/addon.node
```

## Web Workers target

Refers to the build target for running in the [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) environment.

When `target` is set to `'web-worker'`, Rsbuild will:

* Set Rspack's [target](https://rspack.rs/config/target) to `'webworker'`.
* No HTML files will be generated, and HTML-related logic will not be executed, since HTML is not required in the Web Worker environment.
* CSS code will not be bundled or extracted, but CSS Modules id information will be included in the bundle (the default value of [output.emitCss](/config/output/emit-css.md) is `false`).
* The default code split strategy will be disabled, and **dynamic import cannot work**, because Web Workers only run a single JavaScript file.
* Set the default value of [output.emitCss](/config/output/emit-css.md) to `false`. This means CSS code will not be extracted to separate files, but CSS Modules id information will be included in the bundle.
* Disable HMR.

For more information, see [Using Web Workers](/guide/basic/web-workers.md).

## Other targets

[Rspack](https://rspack.rs/config/target) supports other target types, such as `electron-main` and `electron-renderer`.

Rsbuild currently does not support these targets. You can configure these targets using [tools.rspack](/config/tools/rspack.md).

For example, setting the `target` to `'electron-main'` will override the default `'web'` set by Rsbuild.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: {
      target: 'electron-main',
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/html/template-parameters.md

# html.templateParameters

* **Type:** `Record<string, unknown> | Function`
* **Default:**

```ts
type DefaultParameters = {
  mountId: string; // the value of `html.mountId` config
  entryName: string; // entry name
  assetPrefix: string; // the value of dev.assetPrefix or output.assetPrefix configs
  compilation: Compilation; // Compilation object of Rspack
  rspackConfig: Rspack.Configuration; // Rspack config object
  // generated by html-rspack-plugin
  htmlPlugin: {
    tags: {
      headTags: HtmlTagObject[];
      bodyTags: HtmlTagObject[];
    };
    files: {
      publicPath: string;
      js: string[];
      css: string[];
      favicon?: string;
    };
  };
};
```

Define the parameters in the HTML template, see [HTML Template - Template Parameters](/guide/basic/html-template.md#template-parameters) for detailed usage.

## Object usage

If the value of `templateParameters` is an object, it will be merged with the default parameters using `Object.assign`.

For example, if you need to use the `foo` parameter in an HTML template, you can add the following settings:

```ts title="rsbuild.config.ts"
export default {
  html: {
    templateParameters: {
      foo: 'bar',
    },
  },
};
```

Then, you can read the parameter in the HTML template using `<%= foo %>`:

```html
<script>
  window.foo = '<%= foo %>';
</script>
```

The compiled HTML code will be:

```html
<script>
  window.foo = 'bar';
</script>
```

## Function usage

* **Type:**

```ts
type TemplateParametersFunction = (
  defaultValue: Record<string, unknown>,
  utils: { entryName: string },
) => Record<string, unknown> | void;
```

When `html.templateParameters` is of type Function, the function receives two parameters:

* `value`: Default `templateParameters` configuration of Rsbuild.
* `utils`: An object containing the `entryName` field, corresponding to the name of the current entry.

In the context of a multi-page application (MPA), you can set different `templateParameters` based on the entry name:

```ts title="rsbuild.config.ts"
export default {
  html: {
    templateParameters(defaultValue, { entryName }) {
      const params = {
        foo: {
          ...defaultValue,
          type: 'Foo',
        },
        bar: {
          ...defaultValue,
          type: 'Bar',
          hello: 'world',
        },
      };
      return params[entryName] || defaultValue;
    },
  },
};
```

---

# Source: https://rsbuild.dev/guide/advanced/testing.md

# Testing

Rsbuild doesn't include built-in testing frameworks, but integrates seamlessly with popular testing tools.

This guide shows how to add [unit testing](#unit-testing) and [end-to-end testing](#end-to-end-testing) to Rsbuild applications.

## Unit testing

Unit tests verify individual components and functions in isolation. Rsbuild can work with testing frameworks like [Rstest](https://rstest.rs), [Vitest](https://vitest.dev/), [Jest](https://jestjs.io/), and others.

The following example uses Rstest to show how to add unit tests to an Rsbuild application.

### Rstest

[Rstest](https://rstest.rs/) is a testing framework built on Rsbuild that provides first-class support for Rsbuild applications. It offers Jest-compatible APIs while natively supporting modern features like TypeScript and ESM.

#### Installing

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rstest/core -D" />

#### Configuring scripts

Add test scripts to your `package.json`:

```json
{
  "scripts": {
    "test": "rstest",
    "test:watch": "rstest -w"
  }
}
```

#### Writing tests

Create test files, for example:

```ts title="src/utils.ts"
export function add(a: number, b: number) {
  return a + b;
}
```

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

test('should add two numbers correctly', () => {
  expect(add(1, 2)).toBe(3);
  expect(add(-1, 1)).toBe(0);
});
```

#### Running tests

```bash
# Run tests
npm run test

# Run and watch
npm run test:watch
```

These are the basic steps for using Rstest. Check the [Rstest documentation](https://rstest.rs/guide/start/) for more usage details.

### Examples

Refer to the following examples for more usage patterns:

* [react-rstest](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/react-rstest): Using Rstest and [React Testing Library](https://github.com/testing-library/react-testing-library) to test React components.
* [react-jest](https://github.com/rstackjs/rstack-examples/tree/main/rsbuild/react-jest): Using Jest and [React Testing Library](https://github.com/testing-library/react-testing-library) to test React components.

## End-to-end testing

End-to-end testing validates complete user workflows, ensuring your application functions correctly in real browser environments.

For E2E testing, we recommend Playwright, a modern end-to-end testing framework. See the [Playwright documentation](https://playwright.dev/docs/intro) for details.

---

# Source: https://rsbuild.dev/config/html/title.md

# html.title

* **Type:** `string ｜ Function`
* **Default:** `'Rsbuild App'`

Set the title tag of the HTML page.

:::tip
If the HTML template used in the current project already includes the `<title>` tag, the `html.title` will not take effect.
:::

## String usage

`html.title` can be directly set as a string:

```ts title="rsbuild.config.ts"
export default {
  html: {
    title: 'Example',
  },
};
```

The `title` tag generated in HTML will be:

```html
<title>Example</title>
```

## Function usage

* **Type:**

```ts
type TitleFunction = ({ value: string; entryName: string }) => string | void;
```

When `html.title` is of type Function, the function receives an object as the argument, and the object's values include:

* `value`: the default title configuration of Rsbuild.
* `entryName`: the name of the current entry.

In the MPA (multi-page application) scenario, you can return different `title` strings based on the entry name, thus generating different `title` tags for each page:

```ts title="rsbuild.config.ts"
export default {
  html: {
    title({ entryName }) {
      const titles = {
        foo: 'Foo Page',
        bar: 'Bar Page',
      };
      return titles[entryName] || 'Other Page';
    },
  },
};
```

## Unset `<title>` tag

When `html.title` is set to an empty string, Rsbuild will not inject the `<title>` tag:

```ts title="rsbuild.config.ts"
export default {
  html: {
    title: '',
  },
};
```

---

# Source: https://rsbuild.dev/config/source/transform-import.md

# source.transformImport

* **Type:**

```ts
type TransformImport =
  | Array<{
      libraryName: string;
      libraryDirectory?: string;
      style?: string | boolean;
      styleLibraryDirectory?: string;
      camelToDashComponentName?: boolean;
      transformToDefaultImport?: boolean;
      customName?: string;
      customStyleName?: string;
    }>
  | Function;
```

* **Default:** `undefined`

Transform the import path to modularly import subpaths of third-party packages. The functionality is similar to [babel-plugin-import](https://npmjs.com/package/babel-plugin-import).

## Example

### Import antd on demand

When using the [antd](https://github.com/ant-design/ant-design) component library (versions below v5), you can import components on demand with this config:

```ts title="rsbuild.config.ts"
export default {
  source: {
    transformImport: [
      {
        libraryName: 'antd',
        libraryDirectory: 'es',
        style: 'css',
      },
    ],
  },
};
```

The source code is:

```js
import { Button } from 'antd';
```

Will be transformed into:

```js
import Button from 'antd/es/button';
import 'antd/es/button/style';
```

### Import lodash on demand

When using lodash, you can automatically refer to the subpath through `transformImport` to reduce bundle size.

```ts title="rsbuild.config.ts"
export default {
  source: {
    transformImport: [
      {
        libraryName: 'lodash',
        customName: 'lodash/{{ member }}',
      },
    ],
  },
};
```

The source code is:

```js
import { get } from 'lodash';
```

Will be transformed to:

```js
import get from 'lodash/get';
```

Please avoid the following usage, otherwise all of lodash's code will be imported:

```js
import _ from 'lodash';
import lodash from 'lodash';
```

## Scope

`transformImport` is only applicable to modules compiled by Rsbuild. Note that Rsbuild does not compile JavaScript files in the node\_modules by default. This means that the code in the node\_modules directory will not be processed by `transformImport`.

If you want to process the code in node\_modules through `transformImport`, please add the relevant modules to the [source.include](/config/source/include.md) config.

```ts title="rsbuild.config.ts"
export default {
  source: {
    include: [/node_modules[\\/]some-package[\\/]/],
  },
};
```

## Options

### libraryName

* **Type:** `string`

The original import path that needs to be transformed.

### libraryDirectory

* **Type:** `string`
* **Default:** `'lib'`

Constructs the transformed path by concatenating `${libraryName}/${libraryDirectory}/${member}`, where member is the imported member.

Example:

```ts
import { Button } from 'foo';
```

Out:

```ts
import Button from 'foo/lib/button';
```

### style

* **Type:** `boolean`
* **Default:** `undefined`

Determines whether to import related styles. If it is `true`, the path `${libraryName}/${libraryDirectory}/${member}/style` will be imported. If it is `false` or `undefined`, the style will not be imported.

When it is set to `true`:

```ts
import { Button } from 'foo';
```

Out:

```ts
import Button from 'foo/lib/button';
import 'foo/lib/button/style';
```

### styleLibraryDirectory

* **Type:** `string`
* **Default:** `undefined`

Constructs the import path when importing styles. If this configuration is specified, the `style` configuration option will be ignored. The constructed import path is `${libraryName}/${styleLibraryDirectory}/${member}`.

When it is set to `styles`:

```ts
import { Button } from 'foo';
```

Out:

```ts
import Button from 'foo/lib/button';
import 'foo/styles/button';
```

### camelToDashComponentName

* **Type:** `boolean`
* **Default:** `true`

Whether to convert camelCase imports to kebab-case.

Example:

```ts
import { ButtonGroup } from 'foo';
```

Out:

```ts
// set to true:
import ButtonGroup from 'foo/button-group';
// set to false:
import ButtonGroup from 'foo/ButtonGroup';
```

### transformToDefaultImport

* **Type:** `boolean`
* **Default:** `true`

Whether to convert import statements to default imports.

Example:

```ts
import { Button } from 'foo';
```

Out:

```ts
// set to true:
import Button from 'foo/button';
// set to false:
import { Button } from 'foo/button';
```

### customName

* **Type:** `string`
* **Default:** `undefined`

Customize the transformed path.

For example, the following config will transform `import { foo } from 'my-lib'` into `import foo from 'my-lib/foo'`.

```ts title="rsbuild.config.ts"
export default {
  source: {
    transformImport: [
      {
        libraryName: 'my-lib',
        customName: `my-lib/{{ member }}`,
      },
    ],
  },
};
```

In addition, you can also declare the format of the path after transformation, for example setting it to `my-lib/{{ camelCase member }}` to convert member into camel case.

The following formats are supported:

* `kebabCase`: lowercase letters, words joined by hyphens. For example: `my-variable-name`.
* `snakeCase`: lowercase letters, words joined by underscores. For example: `my_variable_name`.
* `camelCase`: first letter lowercase, the first letter of each following word uppercase. For example: `myVariableName`.
* `upperCase`: uppercase letters, other characters unchanged. For example: `MY-VARIABLE-NAME`.
* `lowerCase`: lowercase letters, other characters unchanged. For example: `my-variable-name`.

### customStyleName

* **Type:** `string`
* **Default:** `undefined`

Customize the transformed style path, the usage is consistent with `customName`.

## Function type

The `transformImport` can be a function, it will accept the previous value, and you can modify it.

```ts title="rsbuild.config.ts"
export default {
  source: {
    transformImport: (imports) => {
      return imports.filter((data) => data.libraryName !== 'antd');
    },
  },
};
```

You can also return a new value as the final result in the function, which will replace the previous value.

```ts title="rsbuild.config.ts"
export default {
  source: {
    transformImport: () => {
      return [
        {
          libraryName: 'antd',
          libraryDirectory: 'es',
          style: 'css',
        },
      ];
    },
  },
};
```

---

# Source: https://rsbuild.dev/config/source/tsconfig-path.md

# source.tsconfigPath

* **Type:** `string`
* **Default:** `'tsconfig.json'`

Configure a custom tsconfig.json file path to use, can be a relative or absolute path.

## Purpose

The `tsconfig.json` configuration file affects the following behaviors of Rsbuild:

* The `paths` field configures [Path Aliases](/guide/advanced/alias.md).
* Sets the scope and rules for the [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check).

## Example

The value of `source.tsconfigPath` can be set to a relative or an absolute path. Relative path will be resolved relative to the project root directory.

* Relative path example:

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

* Absolute path example:

```ts
import path from 'node:path';

export default {
  source: {
    tsconfigPath: path.join(__dirname, 'tsconfig.custom.json'),
  },
};
```

---

# Source: https://rsbuild.dev/api/javascript-api/types.md

# Rsbuild types

This section describes some of the type definitions provided by the Rsbuild.

## RsbuildInstance

The type of Rsbuild instance, corresponding to the return value of the [createRsbuild](/api/javascript-api/core.md#creatersbuild) method.

```ts
import type { RsbuildInstance } from '@rsbuild/core';

let rsbuild: RsbuildInstance;
```

## RsbuildConfig

The type of Rsbuild configuration.

```ts
import type { RsbuildConfig } from '@rsbuild/core';

const config: RsbuildConfig = {
  // ...
};
```

You can also import the type definitions of each field in the Rsbuild config:

```ts
import type {
  DevConfig,
  HtmlConfig,
  ToolsConfig,
  SourceConfig,
  ServerConfig,
  OutputConfig,
  SecurityConfig,
  PerformanceConfig,
  ModuleFederationConfig,
} from '@rsbuild/core';
```

## NormalizedConfig

The type of Rsbuild configuration after normalization, corresponding to the return value of the [getNormalizedConfig](/plugins/dev/core.md#apigetnormalizedconfig) method.

```ts
import type { NormalizedConfig } from '@rsbuild/core';

const config: NormalizedConfig = api.getNormalizedConfig();
```

You can also import the type definitions of each field in the normalized config:

```ts
import type {
  NormalizedDevConfig,
  NormalizedHtmlConfig,
  NormalizedToolsConfig,
  NormalizedSourceConfig,
  NormalizedServerConfig,
  NormalizedOutputConfig,
  NormalizedSecurityConfig,
  NormalizedPerformanceConfig,
  NormalizedModuleFederationConfig,
} from '@rsbuild/core';
```

## NormalizedEnvironmentConfig

The type of Rsbuild environment configuration after normalization, corresponding to the return value of the [`getNormalizedConfig({ environment })`](/plugins/dev/core.md#apigetnormalizedconfig) method.

```ts
import type { NormalizedEnvironmentConfig } from '@rsbuild/core';

const config: NormalizedEnvironmentConfig = api.getNormalizedConfig({
  environment,
});
```

## RsbuildContext

The type of the [context property](/api/javascript-api/instance.md#rsbuildcontext) in the Rsbuild instance.

```ts
import type { RsbuildContext } from '@rsbuild/core';

const context: RsbuildContext = rsbuild.context;
```

## 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
import type { RsbuildPlugin } from '@rsbuild/core';

const myPlugin: RsbuildPlugin = {
  name: 'my-plugin',
  setup() {},
};
```

## RsbuildPluginAPI

The API interface that Rsbuild exposes to plugins through the `setup` function.

It allows plugins to interact with the build process, modify configurations, register hooks, and access context information.

```ts
import type { RsbuildPluginAPI } from '@rsbuild/core';

const myPlugin = {
  name: 'my-plugin',
  setup(api: RsbuildPluginAPI) {},
};
```

## RsbuildTarget

The type of build target.

```ts
import type { RsbuildTarget } from '@rsbuild/core';
```

## CreateRsbuildOptions

The param type of [createRsbuild](/api/javascript-api/core.md#creatersbuild) method.

```ts
import type { CreateRsbuildOptions } from '@rsbuild/core';
```

## InspectConfigOptions

The param type of [rsbuild.inspectConfig](/api/javascript-api/instance.md#rsbuildinspectconfig) method.

```ts
import type { InspectConfigOptions } from '@rsbuild/core';
```

## Rspack

Includes all types exported by `@rspack/core`, such as `Rspack.Configuration`.

```ts
import type { Rspack } from '@rsbuild/core';

const rspackConfig: Rspack.Configuration = {};
```

## Others

See [@rsbuild/core - src/index.ts](https://github.com/web-infra-dev/rsbuild/blob/main/packages/core/src/index.ts) for all exported types.

---

# Source: https://rsbuild.dev/guide/basic/typescript.md

# TypeScript

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

## TypeScript transformation

Rsbuild uses [SWC](/guide/configuration/swc.md) by default for transforming TypeScript code to JavaScript, and also supports switching to [Babel](/plugins/list/plugin-babel.md) for transformation.

### Isolated modules

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 value. When using TypeScript in Rsbuild, enable the [verbatimModuleSyntax](https://www.typescriptlang.org/tsconfig/#verbatimModuleSyntax) or [isolatedModules](https://typescriptlang.org/tsconfig/#isolatedModules) option in `tsconfig.json`:

* For TypeScript >= 5.0.0, use the `verbatimModuleSyntax` option, which enables the `isolatedModules` option by default:

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

* For TypeScript \< 5.0.0, use the `isolatedModules` option:

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

The `isolatedModules` option prevents syntax that SWC and Babel cannot compile correctly, such as cross-file type references. It guides you toward correct 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

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

Create a `src/env.d.ts` file to reference these types:

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

> See [types.d.ts](https://github.com/web-infra-dev/rsbuild/blob/main/packages/core/types.d.ts) for the complete preset type definitions that Rsbuild includes.

## Type checking

When transpiling TypeScript code using tools like SWC and Babel, type checking isn't performed.

### Type check plugin

To enable type checking, you can use the [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) plugin. This plugin runs TypeScript type checking in a separate process and internally integrates [ts-checker-rspack-plugin](https://github.com/rstackjs/ts-checker-rspack-plugin).

The plugin supports type checking in both dev and build modes, helping you catch type errors early in development.

Refer to [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) for usage instructions.

### Using tsc

You can also use [tsc](https://www.typescriptlang.org/docs/handbook/compiler-options.html) directly for type checking by adding a `type-check` step to your `build` script. This approach only performs type checking after the build and doesn't run during dev mode.

```json title="package.json"
{
  "scripts": {
    "build": "rsbuild build && npm run type-check",
    "type-check": "tsc --noEmit"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}
```

For Vue applications, use [vue-tsc](https://github.com/vuejs/language-tools/tree/master/packages/tsc) instead of `tsc`. It supports Vue SFCs in addition to TypeScript files.

```json title="package.json"
{
  "scripts": {
    "build": "rsbuild build && npm run type-check",
    "type-check": "vue-tsc --noEmit"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "vue-tsc": "^3.0.0"
  }
}
```

## tsconfig.json Path

Rsbuild reads the `tsconfig.json` file from the root directory by default. Use [source.tsconfigPath](/config/source/tsconfig-path.md) to configure a custom tsconfig.json file path.

```ts
export default {
  source: {
    tsconfigPath: './tsconfig.custom.json',
  },
};
```

## Path extensions

When importing another module in a TypeScript module, TypeScript allows using the `.js` file extension:

```ts title="src/index.ts"
// The actual referenced module could be `./some-module.ts` or `./some-module.tsx`
import { someFn } from './some-module.js';
```

Rsbuild supports this feature through Rspack's [extensionAlias](https://rspack.rs/config/resolve#resolveextensionalias) configuration. In TypeScript projects, Rsbuild adds the following configuration by default:

```js
const rspackConfig = {
  resolve: {
    extensionAlias: {
      '.js': ['.js', '.ts', '.tsx'],
      '.jsx': ['.jsx', '.tsx'],
    },
  },
};
```

This means:

* You can use the `.js` extension to import `.ts` or `.tsx` files.
* You can use the `.jsx` extension to import `.tsx` files.

## Decorators version

Rsbuild does not read the `experimentalDecorators` option in `tsconfig.json`, instead, it provides the [decorators.version](/config/source/decorators.md#decoratorsversion) configuration to specify the decorator version.

By default, Rsbuild uses the `2022-03` version of the decorators, you can also set it to `legacy` to use the legacy decorators:

```ts title="rsbuild.config.ts"
export default {
  source: {
    decorators: {
      version: 'legacy',
    },
  },
};
```

---

# Source: https://rsbuild.dev/guide/styling/unocss.md

# UnoCSS

[UnoCSS](https://unocss.dev/) is the instant atomic CSS engine, which is designed to be flexible and extensible. The core is un-opinionated, and all the CSS utilities are provided via presets.

You can integrate UnoCSS in Rsbuild via PostCSS plugins.

## Installing UnoCSS

You need to install `unocss` and `@unocss/postcss` first.

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add unocss @unocss/postcss -D" />

## Configuring PostCSS

You can register the `unocss` PostCSS plugin through [postcss.config.mjs](https://www.npmjs.com/package/postcss-loader#config) or [tools.postcss](/config/tools/postcss.md).

```js title="postcss.config.mjs"
import UnoCSS from '@unocss/postcss';

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

Rsbuild has integrated [autoprefixer](https://github.com/postcss/autoprefixer), so you only need to register the `UnoCSS` plugin.

## Configuring UnoCSS

Create a `uno.config.ts` file in the root directory of your project and add the following content:

```js title="uno.config.ts"
import { defineConfig, presetUno } from 'unocss';

export default defineConfig({
  content: {
    filesystem: ['./src/**/*.{html,js,ts,jsx,tsx}'],
  },
  presets: [presetUno()],
});
```

:::tip
The above configuration is for reference only and can be modified to suit the needs of your project.
:::

## Importing CSS

Add the `@unocss` directives in your CSS entry file:

```css title="main.css"
@unocss preflights;
@unocss default;
```

Depending on your needs, you can selectively import the CSS styles provided by UnoCSS. Please refer to the [unocss documentation](https://unocss.dev/integrations/postcss#usage) for detailed usage of the UnoCSS.

## Done

You have now completed all the steps to integrate UnoCSS in Rsbuild!

You can use UnoCSS's utility classes in any component or HTML, such as:

```html
<h1 class="px-2 items-center justify-between">Hello world!</h1>
```

For more usage details, refer to the [UnoCSS documentation](https://unocss.dev/).

## VS Code extension

UnoCSS provides a [VS Code Extension](https://unocss.dev/integrations/vscode) plugin for VS Code to decoration and tooltip for matched utilities.

You can install this plugin in VS Code to enable more intelligent features.

---

# Source: https://rsbuild.dev/guide/upgrade/upgrade-rsbuild.md

# Upgrading Rsbuild

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

:::tip

* See [Releases](/community/releases/index.md) to learn about Rsbuild's release strategy.
* See [npm - @rsbuild/core](https://npmjs.com/package/@rsbuild/core) to view the latest version.

:::

## Using taze

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

### Usage

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

```bash
npx taze --include /rsbuild/ -w
```

The result will look similar to:

```bash
rsbuild - 3 patch

  @rsbuild/core               dev  ~1mo  ^1.0.0  →  ^1.2.0
  @rsbuild/plugin-react       dev  ~1mo  ^1.0.0  →  ^1.2.0
  @rsbuild/plugin-type-check  dev  ~1mo  ^1.0.0  →  ^1.2.0

ℹ 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 `@rsbuild` scope:

```bash
npx taze --include /@rsbuild/ -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/ -w -r
```

* Add `-l` to upgrade locked versions:

```bash
npx taze --include /rsbuild/ -w -l
```

* To upgrade to a major version:

```bash
npx taze major --include /rsbuild/ -w
```

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

---

# Source: https://rsbuild.dev/community/releases/v0-1.md

*November 22, 2023*

# Announcing Rsbuild 0.1

![](https://assets.rspack.rs/rsbuild/rsbuild-banner-v0-1.png)

We are pleased to announce **the release of** **[Rsbuild](https://github.com/web-infra-dev/rsbuild)** **0.1!**

Rsbuild is an Rspack-based build tool, designed to be **an enhanced Rspack** **CLI** that is both more user friendly and out-of-the-box. Rsbuild is the ideal solution for those looking to migrate from webpack to Rspack. It significantly reduces configuration by 90% while offering a 10x build speed.

### 🚀 Performance

The build performance of Rsbuild is on par with native Rspack. Considering that Rsbuild includes more out-of-the-box features, its performance will be slightly lower than Rspack.

This is the time it takes to build 1000 React components:

import { BenchmarkGraph } from '@components/Benchmark';

<BenchmarkGraph />

> The data is based on the benchmark built by the Farm team, more info in [build-tools-performance](https://github.com/rstackjs/build-tools-performance).

### 🔥 Features

Rsbuild has the following features:

* **Easy to Configure**: One of the goals of Rsbuild is to provide out-of-the-box build capabilities for Rspack users, allowing developers to start a web project with zero configuration. In addition, Rsbuild provides semantic build configuration to reduce the learning curve for Rspack configuration.

* **Performance Oriented**: Rsbuild integrates high-performance Rust-based tools from the community, including [Rspack](https://github.com/web-infra-dev/rspack), [SWC](https://swc.rs/) and [Lightning CSS](https://lightningcss.dev/), to deliver top-notch build speed and development experience. Compared to webpack-based tools like Create React App and Vue CLI, Rsbuild provides 5 to 10 times faster build performance and lighter dependencies.

* **Plugin Ecosystem**: Rsbuild has a lightweight plugin system and includes a range of high-quality official plugins. Furthermore, Rsbuild is compatible with most webpack plugins and all Rspack plugins, allowing users to leverage existing community or in-house plugins in Rsbuild without the need for rewriting code.

* **Stable Artifacts**: Rsbuild is designed with a strong focus on the stability of build artifacts. It ensures high consistency between artifacts in the development and production builds, and automatically completes syntax downgrading and polyfill injection. Rsbuild also provides plugins for type checking and artifact syntax validation to prevent quality and compatibility issues in production code.

* **Framework Agnostic**: Rsbuild is not coupled with any front-end UI framework. It supports frameworks like React, Vue, Svelte, Solid and Preact through plugins, and plans to support more UI frameworks from the community in the future.

### 💡 Next step

Currently, Rsbuild is still evolving rapidly and plans to introduce many more powerful new features.

For example, we are developing **Rsdoctor**, a robust build analysis tool that can be used with all Rspack and webpack projects. It will provide a visual user interface to help developers analyze build times, duplicate dependencies, code transformation processes, and more, making it easier to locate and resolve build issues.

![Rsdoctor preview](https://assets.rspack.rs/rsbuild/assets/rsdoctor-preview.jpg)

We will be releasing the first working version of Rsdoctor soon. Thereafter, Rsbuild will iterate in sync with Rspack, with plans to release version 1.0 in the first half of 2024.

---

# Source: https://rsbuild.dev/community/releases/v0-2.md

*December 11, 2023*

# Announcing Rsbuild 0.2

![](https://assets.rspack.rs/rsbuild/rsbuild-banner-v0-2.png)

The Rsbuild 0.2 contains some incompatible API changes. Please refer to the current documentation for upgrading.

## Targets

We will move the `target` option of `createRsbuild` to rsbuild config, this change allows user to configure `targets` in the rsbuild config file.

* before:

```js
const rsbuild = await createRsbuild({
  target: ['web', 'node'],
});
```

* after:

```js
// rsbuild.config.ts
export default {
  output: {
    targets: ['web', 'node'],
  },
};
```

> Only affect JavaScript API. Users using the Rsbuild CLI do not need to change.

## Entry

Remove the deprecated `source.entries` config.

`source.entries` has been renamed to `source.entry` since Rsbuild 0.1.0, and we will remove the legacy `source.entries` config in Rsbuild v0.2.0.

* before:

```js
// rsbuild.config.ts
export default {
  source: {
    entries: {},
  },
};
```

* after:

```js
// rsbuild.config.ts
export default {
  source: {
    entry: {},
  },
};
```

## Write to disk

`dev.writeToDisk` defaults to `false`.

Motivation:

* Reduce fs overhead and improve dev server performance.
* Avoid trigger watcher of UnoCSS and other tools. See [#654](https://github.com/web-infra-dev/rsbuild/issues/654).
* Align the default behavior with webpack-dev-middleware and other community dev servers.

User can enable writeToDisk manually:

```js
export default {
  dev: {
    writeToDisk: true,
  },
};
```

## Babel plugin

`@rsbuild/plugin-babel` will move all babel-loader options to `babelLoaderOptions`:

* before:

```ts
pluginBabel({
  plugins: [],
  presets: [],
});
```

* after:

```ts
pluginBabel([
  babelLoaderOptions: {
    plugins: [],
    presets: [],
  }
]);
```

This change allows us to add more options for `pluginBabel`, such as `include` and `exclude`.

## Source map

`output.disableSourceMap` has been renamed to `output.sourceMap`.

* before:

```js
export default {
  output: {
    disableSourceMap: {
      js: true,
      css: true,
    },
  },
};
```

* after:

```js
export default {
  output: {
    sourceMap: {
      js: false,
      css: false,
    },
  },
};
```

The default value of source map has also been updated to improve build performance.

* before: generate JS / CSS source map in development, generate JS source map in production.
* after: generate JS source map in development, no source map are generated in production.

## Inject styles

Rename `output.disableCssExtract` to `output.injectStyles` to be clearer:

* before:

```js
export default {
  output: {
    disableCssExtract: true,
  },
};
```

* after:

```js
export default {
  output: {
    injectStyles: true,
  },
};
```

---

# Source: https://rsbuild.dev/community/releases/v0-3.md

*January 10, 2024*

# Announcing Rsbuild 0.3

![](https://assets.rspack.rs/rsbuild/rsbuild-banner-v0-3.png)

Rsbuild 0.3 version has upgraded Rspack to 0.5 and now supports Module Federation. In addition, it includes some incompatible API changes. Please refer to the current documentation for upgrading.

## Rspack 0.5

Bump Rspack to v0.5.0, see: [Rspack 0.5 Release Announcement](https://rspack.rs/blog/announcing-0-5)

Notable changes:

* [Module Federation added to Rspack](https://rspack.rs/blog/module-federation-added-to-rspack)
* [Remove deprecated builtins options](https://rspack.rs/blog/announcing-0-5#make-swchelpers-and-react-refresh-as-peerdependencies)

## TOML / YAML plugin

The need to import TOML and YAML in JS is not common, so Rsbuild core will no longer support import TOML and YAML by default in v0.3.0.

The TOML and YAML plugin will become a independent plugin:

* TOML:

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

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

* YAML:

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

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

## JavaScript API

Some JavaScript APIs have changed:

* The `printURLs` option of `rsbuild.startDevServer` is deprecated, use [server.printUrls](/config/server/print-urls.md) instead.
* The `logger` option of `rsbuild.startDevServer` is deprecated, use [logger.override()](/api/javascript-api/core.md#logger) instead.

## Node target

* Adjust default browserslist for node target, from `node >= 14` to `node >= 16`.
* The default value of `output.distPath.server` is changed from `'bundles'` to `'server'`

---

# Source: https://rsbuild.dev/community/releases/v0-4.md

*February 06, 2024*

# Announcing Rsbuild 0.4

![](https://assets.rspack.rs/rsbuild/rsbuild-banner-v0-4.png)

Rsbuild 0.4 provides built-in support for module federation. It also contains some incompatible API updates. Please refer to the current document for upgrading.

### Module Federation config

Rsbuild now provides a built-in [moduleFederation](/config/module-federation/options.md) option, which will make configuring Module Federation in Rsbuild much easier.

* **Example:**

```ts title="rsbuild.config.ts"
export default defineConfig({
  moduleFederation: {
    options: {
      // ModuleFederationPluginOptions
    },
  },
});
```

When you use this option, Rsbuild will automatically set the default `publicPath` and `splitChunks` config, making module federation ready to use out of the box.

> See [RFC - Provide first-class support for Module Federation](https://github.com/web-infra-dev/rsbuild/discussions/1461) for details.

### Plugin hook order

In Rsbuild plugin, you can now declare the order of hooks using the `order` field:

```ts
const myPlugin = () => ({
  setup(api) {
    api.modifyRsbuildConfig({
      handler: () => console.log('hello'),
      order: 'pre',
    });
  },
});
```

> For more details, see [Plugin Hooks](/plugins/dev/hooks.md).

### Rename disableFilenameHash

The `output.disableFilenameHash` config has been renamed to [output.filenameHash](/config/output/filename-hash.md).

* Before:

```ts
export default {
  output: {
    disableFilenameHash: true,
  },
};
```

* After:

```ts
export default {
  output: {
    filenameHash: false,
  },
};
```

## Remove postcss-flexbugs-fixes

Rsbuild 0.4 removed the built-in [postcss-flexbugs-fixes](https://github.com/luisrudge/postcss-flexbugs-fixes) plugin.

This plugin is used to fix some flex bugs for IE 10 / 11. Considering that modern browsers no longer have these flex issues, we removed this plugin to improve build performance.

If your project needs to be compatible with IE 10 / 11 and encounters these flex issues, you can manually add this plugin in Rsbuild:

* Install plugin:

```bash
npm add postcss-flexbugs-fixes -D
```

* Register plugin in `postcss.config.cjs`:

```js
module.exports = {
  'postcss-flexbugs-fixes': {},
};
```

## Pure React plugin

The React plugin has removed default [source.transformImport](/config/source/transform-import.md) config for [antd](https://npmjs.com/package/antd) v4 and [@arco-design/web-react](https://npmjs.com/package/@arco-design/web-react).

Configurations related to the UI library should be provided in the UI library-specific plugins, such as `rsbuild-plugin-antd` or `rsbuild-plugin-arco`, and the React plugin will concentrate on providing fundamental abilities for React.

* If your project is using `antd` v3 or v4, you can manually add the following config:

```ts title="rsbuild.config.ts"
export default {
  source: {
    transformImport: [
      {
        libraryName: 'antd',
        libraryDirectory: 'es',
        style: 'css',
      },
    ],
  },
};
```

* If your project is using `@arco-design/web-react`, you can manually add the following config:

```ts title="rsbuild.config.ts"
export default {
  source: {
    transformImport: [
      {
        libraryName: '@arco-design/web-react',
        libraryDirectory: 'es',
        camelToDashComponentName: false,
        style: 'css',
      },
      {
        libraryName: '@arco-design/web-react/icon',
        libraryDirectory: 'react-icon',
        camelToDashComponentName: false,
      },
    ],
  },
};
```

## JavaScript API

The `loadConfig` method now returns both the contents of the config and the path to the config file:

```js
import { loadConfig } from '@rsbuild/core';

// 0.3
const config = await loadConfig();

// 0.4
const { content, filePath } = await loadConfig();
```

---

# Source: https://rsbuild.dev/community/releases/v0-5.md

*March 19, 2024*

# Announcing Rsbuild 0.5

![](https://assets.rspack.rs/rsbuild/rsbuild-banner-v0-5.png)

Rsbuild 0.5 is an important milestone. As of this release, most of the Rsbuild API has reached a stable state and we expect to release Rsbuild 1.0 in Q3 2024.

Main changes:

* ⚡️ Support for [Lightning CSS](https://lightningcss.dev/) to speed up CSS compilation.
* 🌟 Support for custom server based on the new JavaScript API.
* 🍭 Refactor the SVGR plugin to support more usages.
* 📍 Support for custom minify options.

## ⚡️ Supports Lightning CSS

Lightning CSS 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 also provides a better compression ratio.

Rsbuild provides the Lightning CSS plugin to use Lightning CSS on an opt-in basis, replacing the built-in PostCSS, autoprefixer, and SWC CSS minimizer in Rsbuild.

All you need to do is register the Lightning CSS plugin in the Rsbuild configuration to complete the switch:

```ts title="rsbuild.config.ts"
import { pluginLightningcss } from '@rsbuild/plugin-lightningcss';

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

In a real large-scale web application, we have integrated the Rsbuild Lightning CSS plugin and used [Rsdoctor](https://rsdoctor.rs/) to analyze the changes in build time:

* CSS compilation time was reduced from 8.4s to 0.12s, a 70x improvement.
* The overall build time was reduced from 33.1s to 25.4s, a 30% increase.

## 🌟 Support for custom server

Rsbuild now supports replacing the dev server with a custom server that reuses Rsbuild's page preview, routing, and module hot update features. This makes it easier to integrate Rsbuild with other Node.js frameworks.

For example, you can implement a custom server based on express:

```ts
import express from 'express';
import { createRsbuild } from '@rsbuild/core';

async function startCustomServer() {
  const app = express();
  const rsbuild = await createRsbuild({
    config: {
      server: {
        middlewareMode: true,
      },
    },
  });
  const { port, middlewares } = await rsbuild.createDevServer();

  app.use(middlewares);
  app.listen(port);
}
```

For more details, please refer to [Rsbuild - createDevServer](/api/javascript-api/instance.md#rsbuildcreatedevserver).

## 🍭 Refactoring SVGR plugin

In versions prior to 0.5.0, the default usage of the SVGR plugin was the same as create-react-app, allowing SVGs to be used via mixed import:

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

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

However, there are two problems with this approach:

1. **Increased bundle size**: Mixed import causes a single SVG module to be compiled into two types of code (even if some exports are not used), which will increase the bundle size.
2. **Slow down compiling**: Mixed import will cause extra compilation overhead. Even if the ReactComponent export is not used in the code, the SVG file will still be compiled by SVGR. And SVGR is based on Babel, which has a high performance overhead.

So we have refactored the `@rsbuild/plugin-svgr` plugin to support converting SVGs to React components via the `?react` query. This approach can solve the problems mentioned above, and is more in line with community best practices.

```jsx
import logoUrl from './logo.svg';
import Logo from './logo.svg?react';

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

The SVGR plugin now supports switching between different SVGR usages. If a project needs to use the previous mixed import usage, you can manually enable the [mixedImport](/plugins/list/plugin-svgr.md#mixedimport) option:

```js
pluginSvgr({
  mixedImport: true,
});
```

## 📍 Custom minify options

The `output.disableMinimize` option has been renamed to [output.minify](/config/output/minify.md), and it allows customizing JS and HTML minification options.

```ts title="rsbuild.config.ts"
export default {
  output: {
    minify: {
      jsOptions: {
        minimizerOptions: {
          mangle: false,
        },
      },
    },
  },
};
```

Projects using `output.disableMinimize` can refer to the example below:

```ts
export default {
  output: {
    disableMinimize: true, // [!code --]
    minify: false, // [!code ++]
  },
};
```

> See ["allow customize minify options"](https://github.com/web-infra-dev/rsbuild/issues/1681).

***

For more information, please refer to:

* [Rsbuild 0.5.0 Changelog](https://github.com/web-infra-dev/rsbuild/releases/tag/v0.5.0)
* [Rsbuild 0.5.0 Breaking Changes](https://github.com/web-infra-dev/rsbuild/discussions/1732)

---

# Source: https://rsbuild.dev/community/releases/v0-6.md

*April 10, 2024*

# Announcing Rsbuild 0.6

![](https://assets.rspack.rs/rsbuild/rsbuild-banner-v0-6.png)

Rsbuild 0.6 has been released along with Rspack 0.6!

Notable changes:

* Upgrade to Rspack 0.6
* Error overlay enabled by default
* Support for Vue JSX HMR
* New transform plugin API
* Default port changed to 3000

## Upgrade to Rspack 0.6

Rsbuild has upgraded the dependent Rspack to version 0.6, and adapted the breaking changes of CSS Modules contained in Rspack 0.6.

In the new version, Rspack has enabled the new tree shaking algorithm by default, resulting in a significant improvement in bundle size and artifact stability. Please refer to the [Rspack 0.6 release announcement](https://rspack.rs/blog/announcing-0-6) to learn more.

## Error overlay enabled by default

Starting from Rsbuild 0.6, the default value of [dev.client.overlay](/config/dev/client.md) has been adjusted to `true`. This means that when a compilation error occurs, Rsbuild will pop up the error overlay by default to display the error information:

![](https://assets.rspack.rs/rsbuild/assets/rsbuild-error-overlay.png)

If you do not need this feature, you can set `dev.client.overlay` to `false` to disable it.

```ts title="rsbuild.config.ts"
export default defineConfig({
  dev: {
    client: {
      overlay: false,
    },
  },
});
```

## Support for Vue JSX HMR

`@rsbuild/plugin-vue-jsx` now supports JSX HMR. When you modify JSX code in a Vue 3 application, it will automatically trigger hot module replacement and preserve the current page state.

This feature is implemented by community contributor [@liyincode](https://github.com/liyincode) ❤️, and released as a standalone package [babel-plugin-vue-jsx-hmr](https://github.com/liyincode/babel-plugin-vue-jsx-hmr), for use in projects outside of Rsbuild.

## New transform API

Rsbuild plugin now supports the [transform API](/plugins/dev/core.md#apitransform), which can be thought of as a lightweight implementation of Rspack loader. It provides a simple and easy to use API and automatically calls Rspack loader at the backend to transform the code.

In Rsbuild plugins, you can quickly implement code transformation functions using `api.transform`, which can handle the majority of common scenarios without having to learn how to write an Rspack loader.

For example, match modules with the `.pug` extension and transform them to JavaScript code:

```ts
import pug from 'pug';

const pluginPug = () => ({
  name: 'my-pug-plugin',
  setup(api) {
    api.transform({ test: /\.pug$/ }, ({ code }) => {
      const templateCode = pug.compileClient(code, {});
      return `${templateCode}; module.exports = template;`;
    });
  },
});
```

For some complex code transformation scenarios, `api.transform` may not be sufficient. In such situations, you can implement it using the Rspack loader.

## Default port changed to 3000

Rsbuild has changed the default value of [server.port](/config/server/port.md) from `8080` to `3000`.

Port 3000 is commonly used for web development, and is also the default port used by tools such as create-react-app. Changing the default port to 3000 can prevent possible port conflicts when using 8080.

To use port 8080, set it manually as follows:

```ts title="rsbuild.config.ts"
export default defineConfig({
  server: {
    port: 8080,
  },
});
```

---

# Source: https://rsbuild.dev/community/releases/v0-7.md

*May 28, 2024*

# Announcing Rsbuild 0.7

![](https://assets.rspack.rs/rsbuild/rsbuild-banner-v0-7.png)

Rsbuild 0.7 has been released with Rspack 0.7!

This is the last minor release before the Rsbuild 1.0. After this, the Rspack team will focus on the development of 1.0 and aim to launch the Rspack / Rsbuild 1.0 alpha version soon.

Notable changes in Rsbuild 0.7:

* [Support for Storybook](#support-for-storybook)
* [Faster Sass Compilation](#faster-sass-compilation)
* [Better CSS supports](#better-css-supports)
* [Typed CSS Modules](#typed-css-modules)
* [ESM/CJS Exports](#esmcjs-exports)
* [Breaking Changes](#breaking-changes)

## Support for Storybook

Rsbuild now supports Storybook!

[storybook-builder-rsbuild](https://github.com/rstackjs/storybook-rsbuild) is a Storybook builder based on Storybook v8 and Rsbuild that allows you to quickly build your components and stories.

![](https://assets.rspack.rs/rsbuild/rsbuild-banner-with-storybook.png)

* For projects using Rsbuild, you can now quickly integrate Storybook and reuse your existing Rsbuild config.
* For projects using the Storybook webpack builder, you can now upgrade to Rsbuild and **get ~5x faster build performance**.

We provide `storybook-react-rsbuild` and `storybook-vue3-rsbuild` to support React and Vue 3. For example, to integrate React:

```js title=".storybook/main.js"
import { StorybookConfig } from 'storybook-react-rsbuild';

const config: StorybookConfig = {
  framework: 'storybook-react-rsbuild',
};

export default config;
```

![](https://assets.rspack.rs/rsbuild/assets/storybook-rsbuild-preview.png)

> For more usage, please refer to [storybook-rsbuild repository](https://github.com/rstackjs/storybook-rsbuild).

## Faster Sass compilation

In Rsbuild 0.7, **Sass compilation is 3~10 times faster**. The performance improvements are particularly noticeable on large projects.

Comparison of build times for Rsbuild 0.6 and 0.7 when compiling Bootstrap's Sass code:

![](https://assets.rspack.rs/rsbuild/assets/sass-embedded-compare.jpeg)

This improvement is due to Rsbuild's default use of [sass-embedded](https://npmjs.com/package/sass-embedded), a JavaScript wrapper around the native Dart Sass executable that provides a consistent API and superior performance.

Rsbuild has also enabled the latest sass-loader's [modern-compiler](https://github.com/webpack/sass-loader/releases/tag/v14.2.0) API. This can enable Sass's shared resources feature, which allows the same compiler process to be reused when compiling multiple files, improving build performance.

## Better CSS supports

Rsbuild now uses [CssExtractRspackPlugin](https://rspack.rs/plugins/rspack/css-extract-rspack-plugin) to extract CSS into separate files, rather than using the [experimental.css](https://rspack.rs/config/experiments#experimentscss) config to do so.

This allows Rsbuild to support more CSS features, including:

* Support for using `<style module>` in the Vue SFC:

```html title="index.vue"
<template>
  <p :class="$style.red">Red</p>
</template>

<style module>
  .red {
    color: red;
  }
</style>
```

* Support for complex CSS Modules `:global()` syntax

```css title="style.module.css"
:local(.parent):global(.child) > ul {
  color: red;
}
```

* Support for more CSS Modules options, such as [cssModules.exportGlobals](/config/output/css-modules.md#cssmodulesexportglobals)
* Now you can use [tools.cssExtract](/config/tools/css-extract.md) to configure CssExtractRspackPlugin.

## Typed CSS Modules

Rsbuild 0.7 added a new [Typed CSS Modules plugin](https://github.com/rstackjs/rsbuild-plugin-typed-css-modules), which is used to generate type declaration files for CSS Modules in the project.

When you use CSS Modules in a TypeScript project, the default type definition is as follows. It can only provide basic type support, and cannot accurately prompt which class names are exported by CSS Modules.

```ts title="src/env.d.ts"
declare module '*.module.css' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
```

After using the Typed CSS Modules plugin, Rsbuild will generate type declaration files for all CSS Modules in the project, providing accurate type hints.

For example, create two files named `src/index.ts` and `src/index.module.css`:

```tsx title="src/index.ts"
import styles from './index.module.css';

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

```css title="index.module.css"
.page-header {
  color: black;
}
```

After building, Rsbuild will generate a `src/index.module.css.d.ts` type declaration file:

```ts title="src/index.module.css.d.ts"
interface CssExports {
  'page-header': string;
  pageHeader: string;
}
declare const cssExports: CssExports;
export default cssExports;
```

Now when you open the `src/index.ts` file, you can see that the `styles` object already has an accurate type.

## ESM/CJS Exports

Now, all packages of Rsbuild provide exports in both ES modules and CommonJS formats, and ["type"="module"](https://nodejs.org/api/packages.html#type) has been declared in the package.json.

![](https://assets.rspack.rs/rsbuild/assets/rsbuild-dual-package-example.png)

This allows you to use `import` or `require` to use the JavaScript API of Rsbuild:

```js
// ES module
import { createRsbuild } from '@rsbuild/core';

// CommonJS
const { createRsbuild } = require('@rsbuild/core');
```

ESM/CJS interop is a tricky issue, so we will provide both formats for a long time to make it easier for more users to use.

## Breaking changes

### Upgrade Rspack to 0.7

Rsbuild has upgraded the dependent Rspack to version 0.7 and adapted to the breaking changes included in it. Typically, these breaking changes will not affect you.

In the new version, Rspack supports lazy compilation, which can significantly improve the dev startup time for large projects. Please refer to [Announcing Rspack 0.7](https://rspack.rs/blog/announcing-0-7) to learn more.

In Rsbuild, you can use [dev.lazyCompilation](/config/dev/lazy-compilation.md) to enable lazy compilation.

### Sass and Less plugins

Rsbuild's Sass and Less plugins are now two separate npm packages instead of being built into `@rsbuild/core` as before. This change allows users to enable Sass and Less compilation as needed.

For example, projects using CSS solutions such as Tailwind CSS, CSS-in-JS, etc., no longer need to install the dependencies required for Sass and Less, **saving about 7MB of disk space**.

* If your project requires compiling `.scss` or `.sass` files, please install and register the [@rsbuild/plugin-sass](/plugins/list/plugin-sass.md) plugin:

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

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

* If your project requires compiling `.less` files, please install and register the [@rsbuild/plugin-less](/plugins/list/plugin-less.md) plugin:

```ts title="rsbuild.config.ts"
import { pluginLess } from '@rsbuild/plugin-less';

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

### dataUriLimit defaults

The default value for [output.dataUriLimit](/config/output/data-uri-limit.md) has been changed from `10000 (10 kB)` to `4096 (4 KiB)`.

This is because more applications are currently using HTTP 2.0, so splitting assets into separate files would perform better. Meanwhile, inlining assets over 4KiB can make the JS bundle to be too large and not cache friendly.

If you prefer the previous defaults, add the following config:

```ts title="rsbuild.config.ts"
export default {
  output: {
    dataUriLimit: 10000,
  },
};
```

---

# Source: https://rsbuild.dev/guide/upgrade/v0-to-v1.md

# Upgrading from 0.x to v1

This document lists all breaking changes from Rsbuild 0.7 to 1.0. Use it as a migration reference.

> See [Breaking changes in Rsbuild v1.0.0](https://github.com/web-infra-dev/rsbuild/discussions/2508) for details.

## \[Important] Lightning CSS loader

Rsbuild now enables [lightningcss-loader](https://rspack.rs/guide/features/builtin-lightningcss-loader) by default to transform CSS files. It replaces `autoprefixer` for adding vendor prefixes and delivers better performance.

* `@rsbuild/plugin-lightningcss` is deprecated and no longer needed.
* `tools.autoprefixer` config has been removed.

Since Lightning CSS has some uncovered edge cases, you can still enable autoprefixer through a postcss config file:

```js title="postcss.config.cjs"
module.exports = {
  plugins: {
    autoprefixer: {},
  },
};
```

## \[Important] output.polyfill

Rsbuild v1 sets [output.polyfill](/config/output/polyfill.md) to `'off'` by default. This reduces polyfill code and generates smaller bundles.

If your application needs polyfills, set `output.polyfill` to `'usage'` or `'entry'`:

```ts title="rsbuild.config.ts"
export default {
  output: {
    polyfill: 'usage',
  },
};
```

## \[Important] source.decorators

Rsbuild now uses `2022-11` decorators version by default. This aligns Rsbuild's default behavior with TypeScript >= 5.0 and esbuild >= 0.21.0.

For legacy decorators, add this config:

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

export default defineConfig({
  source: {
    decorators: {
      version: 'legacy',
    },
  },
});
```

## \[Important] output.targets

:::tip
Rsbuild v1 removes the `output.targets` option and target parameters from `source.alias`, `source.entry`, and other configs. Instead, use `environments` for more flexible multi-environment configuration.

The `environments` option provides broader coverage and enables differentiated config across multiple environments. For details, see [Multiple-Environment Builds](/guide/advanced/environments.md).
:::

The `output.targets` config has been removed. Use [output.target](/config/output/target.md) and [environments](/config/environments.md) instead.

* before:

```js
export default {
  output: {
    targets: ['web', 'node'],
  },
};
```

* after:

```js
export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
      },
    },
  },
};
```

## source.alias

Removed `target` param for `source.alias` function, use [environments](/config/environments.md) config instead.

* before:

```js
export default {
  source: {
    alias: (alias, { target }) => {
      if (target === 'node') {
        alias['@common'] = './src/node/common';
      } else if (target === 'web') {
        alias['@common'] = './src/web/common';
      }
    },
  },
  output: {
    targets: ['web', 'node'],
  },
};
```

* after:

```js
export default {
  environments: {
    web: {
      source: {
        alias: {
          '@common': './src/web/common',
        },
      },
      output: {
        target: 'web',
      },
    },
    node: {
      source: {
        alias: {
          '@common': './src/node/common',
        },
      },
      output: {
        target: 'node',
      },
    },
  },
};
```

## source.entry

Removed function usage of `source.entry`, use [environments](/config/environments.md) config instead.

* before:

```js
export default {
  source: {
    entry({ target }) {
      if (target === 'web') {
        return {
          index: './src/index.client.js',
        };
      }
      if (target === 'node') {
        return {
          index: './src/index.server.js',
        };
      }
    },
  },
  output: {
    targets: ['web', 'node'],
  },
};
```

* after:

```js
export default {
  environments: {
    web: {
      source: {
        entry: {
          index: './src/index.client.js',
        },
      },
      output: {
        target: 'web',
      },
    },
    node: {
      source: {
        entry: {
          index: './src/index.server.js',
        },
      },
      output: {
        target: 'node',
      },
    },
  },
};
```

## output.overrideBrowserslist

`output.overrideBrowserslist` no longer supports `Record<RsbuildTarget, string[]` type, use [environments](/config/environments.md) config instead.

* before:

```js
export default {
  output: {
    overrideBrowserslist: {
      web: ['iOS >= 9', 'Android >= 4.4'],
      node: ['node >= 20'],
    },
  },
};
```

* after:

```js
export default defineConfig({
  environments: {
    web: {
      output: {
        overrideBrowserslist: ['iOS >= 9', 'Android >= 4.4'],
      },
    },
    node: {
      output: {
        overrideBrowserslist: ['node >= 20'],
      },
    },
  },
});
```

## output.emitAssets

`output.emitAssets` changed to boolean type, use [environments](/config/environments.md) config instead.

* before:

```js
export default {
  output: {
    targets: ['web', 'node'],
    emitAssets: ({ target }) => target !== 'node',
  },
};
```

* after:

```js
export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
        emitAssets: false,
      },
    },
  },
};
```

## output.distPath.server

Removed `output.distPath.server`, use the [environments](/config/environments.md) config instead.

```js
export default {
  environments: {
    web: {
      output: {
        target: 'web',
      },
    },
    node: {
      output: {
        target: 'node',
        distPath: {
          root: 'dist/server',
        },
      },
    },
  },
};
```

## output.minify.html

Rsbuild v1 removed the `output.minify.html` and `output.minify.htmlOptions` options, and no longer minify the HTML files.

Previously Rsbuild uses `html-minifier-terser` to minify the HTML files. But the performance of `html-minifier-terser` cannot meet the needs of Rsbuild applications, and in most cases, there is little benefit in compressing HTML.

At this stage, Rsbuild will not built-in `html-minifier-terser`, so we provide a standalone [rsbuild-plugin-html-minifier-terser](https://github.com/rstackjs/rsbuild-plugin-html-minifier-terser) to support HTML minification.

```ts title="rsbuild.config.ts"
import { pluginHtmlMinifierTerser } from 'rsbuild-plugin-html-minifier-terser';

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

And we plan to use some faster Rust-based HTML minimizer in the future.

## output.charset

The default value of [output.charset](/config/output/charset.md) has been changed from `ascii` to `utf8`.

To use `ascii`, add the following config:

```ts
export default {
  output: {
    charset: 'ascii',
  },
};
```

## dev.startUrl

`dev.startUrl` has been renamed to [server.open](/config/server/open.md):

```js
export default {
  // [!code --]
  dev: {
    startUrl: true, // [!code --]
  }, // [!code --]
  // [!code ++]
  server: {
    open: true, // [!code ++]
  }, // [!code ++]
};
```

## dev.client.port

The default value of [dev.client.port](/config/dev/client.md) changed from `<port>` to `''` (use `location.port`).

Use the previous value if you want to keep the behavior:

```js
export default {
  dev: {
    client: {
      port: '<port>',
    },
  },
};
```

## html.appIcon

Previously, [html.appIcon](/config/html/app-icon.md) did not support for web app manifests, meaning it was only available on iOS.

Now `html.appIcon` supports generating web app manifests, and the type of `html.appIcon` has been changed.

* before:

```js
export default {
  html: {
    appIcon: './src/icon.png',
  },
};
```

* after:

```js
export default {
  html: {
    appIcon: {
      icons: [{ src: './src/icon.png', size: 180 }],
    },
  },
};
```

## Others

Rsbuild 1.0 has made some adjustments and optimizations to plugins API and dev server API.

Includes:

* The `onBeforeBuild` hook supports triggering multiple times in watch mode.
* Added `onBeforeEnvironmentCompile` and `onAfterEnvironmentCompile` hooks, which are triggered before/after executing the build of a single environment respectively.
* Removed `api.getHtmlPaths` and replaced it with `environment.htmlPaths`.
* Removed `api.context.entry` and replaced it with `environment.entry`.
* Removed `api.context.targets` and replaced it with `environment.target`.
* Removed `rsbuildServer.onHTTPUpgrade` and replaced it with `rsbuildServer.connectWebSocket`.

---

# Source: https://rsbuild.dev/community/releases/v1-0.md

*September 10, 2024*

# Announcing Rsbuild 1.0

![](https://assets.rspack.rs/rsbuild/assets/rsbuild-1-0-banner.png)

We are pleased to announce the release of Rsbuild 1.0!

## Why Rsbuild

For a long time, developers using webpack have been bothered by two major issues: **slow build times and configuration complexity**.

We have used Rust to rewrite webpack into [Rspack](https://github.com/web-infra-dev/rspack), which addresses the slow build issue. However, to maintain compatibility with the webpack ecosystem, Rspack retains webpack's configuration and API, which means it still has some complexity and a learning curve.

### Evolution of the ecosystem

In the early days, there were some excellent tools within the webpack ecosystem, such as Create React App (CRA) and Vue CLI. These tools provided best practices for building React or Vue applications, while hiding the complex webpack configuration. As a result, many React and Vue users used these tools to build applications without having to configure webpack from scratch.

As the ecosystem evolved, full-stack web frameworks such as Next.js, Nuxt, and Remix became popular; Vite was introduced as a lightweight build tool and also gained popularity. However, CRA and Vue CLI gradually stopped being maintained.

When we look at the npm download numbers for webpack, CRA, and Vue CLI, we find that a large number of projects are still using these tools. For example, webpack has about 25 million weekly downloads, and CRA has nearly 3 million weekly downloads. Many of these projects are CSR applications that do not require the SSR features of full-stack frameworks. Vite seems like a good choice, but after using Vite in our ByteDance projects, we found that migrating from webpack to Vite comes with high costs and introduces new problems, such as dev and build inconsistency, and slow page refreshes in large applications during development.

For the webpack ecosystem, we discovered a sad fact: **the webpack ecosystem lacks a build tool that is easy to use and well maintained**. The tool should be as user-friendly as CRA and Vue CLI, fully meet the needs of CSR application development, and have features such as fast startup and plugin support similar to Vite.

### The birth of Rsbuild

During the development of Rspack, we became aware of the above problems and decided to create a modern build tool based on Rspack called **Rsbuild**.

![](https://assets.rspack.rs/rsbuild/assets/rsbuild-1-0-build-tools.png)

Rsbuild is built on top of Rspack. We designed Rsbuild with an easy-to-use, TypeScript-friendly API and a set of carefully designed configurations to fully leverage the Rspack's build performance while reducing configuration complexity and high up-front costs.

When developing Rsbuild, we learned best practices from the best tools in the community and focused on two usage scenarios:

* As a lightweight build tool: Helps developers quickly set up web applications with out-of-the-box support for CSR applications.
* As a shared infrastructure: Provides [JavaScript API](/api/start/index.md) and [Plugin API](/plugins/dev/index.md) for higher-level tools and frameworks, allowing developers to easily build their tools or frameworks on top of Rsbuild.

## Performance

**Rsbuild is currently the fastest build tool in the webpack and Rspack ecosystem**. Here is a comparison between Rsbuild, Create React App, Vite, and Rspack CLI:

| Metric                          | Create React App | Vite (with SWC) | Rspack CLI | Rsbuild | Rsbuild vs CRA    |
| ------------------------------- | ---------------- | --------------- | ---------- | ------- | ----------------- |
| dev startup time (1000 modules) | 5.47s            | 1.29s           | 0.66s      | 0.39s   | **14x faster**    |
| build time (1000 modules)       | 5.69s            | 1.39s           | 0.51s      | 0.27s   | **20x faster**    |
| npm dependencies count          | 1241             | 15              | 283        | 14      | **99% reduction** |
| npm install size                | 146.6MB          | 56.3MB          | 75.1MB     | 59.1MB  | **60% reduction** |

Compared to the [Rspack CLI](https://npmjs.com/package/@rspack/cli), Rsbuild provides a richer set of features while demonstrating superior performance.

This is because Rspack CLI needs to maintain compatibility with the [webpack-cli](https://npmjs.com/package/webpack-cli). It relies on the `webpack-dev-server` and provides the same default behavior as webpack, which has some performance limitations. Rsbuild, on the other hand, is designed for modern web development. We have reimplemented a lighter CLI, dev server, and build process for Rsbuild, resulting in faster startup speeds and fewer npm dependencies.

> See the [Rsbuild Introduction](/guide/start/index.md) for more comparisons between Rsbuild, webpack, Vue CLI, and Vite.

## Who is using

In the [Rspack 1.0 Announcement](https://rspack.rs/blog/announcing-1-0), we introduced that Rspack is growing rapidly, with almost half of Rspack users using Rsbuild and giving us lots of positive feedback.

At ByteDance, we use Rsbuild as the cornerstone of our internal web frameworks to support thousands of web projects. These projects cover diverse use cases, including desktop web applications, mobile web applications, cross-platform web applications, documentation sites, and more.

For the community, we have open-sourced a high-performance toolchain based on Rsbuild, including the static site generator [Rspress](https://github.com/web-infra-dev/rspress), the library development tool [Rslib](https://github.com/web-infra-dev/rslib), the full-stack React framework [Modern.js](https://github.com/web-infra-dev/modern.js), and the [Storybook Rsbuild](https://github.com/rstackjs/storybook-rsbuild). The extensibility of Rsbuild allows these tools to flexibly integrate with Rsbuild and share its plugin ecosystem.

After releasing Rsbuild 1.0, we also plan to collaborate with some excellent teams like [Remix](https://github.com/remix-run/remix), to bring Rsbuild to more web frameworks.

## Plugin ecosystem

The Rsbuild plugin ecosystem is constantly evolving. There are currently over 50 [Rsbuild plugins](https://github.com/rstackjs/awesome-rstack?tab=readme-ov-file#rsbuild-plugins) available in the community. We provide several advanced features through plugins to support the development of production-grade applications, such as [type checking](https://github.com/rstackjs/rsbuild-plugin-type-check), [compatibility checking](https://github.com/rstackjs/rsbuild-plugin-check-syntax), and [static assets retry](https://github.com/rstackjs/rsbuild-plugin-assets-retry). Thanks to Rspack's compatibility with webpack, Rsbuild also supports most webpack plugins.

Compared to webpack or Rspack, the Rsbuild plugin API is more straightforward and beginner-friendly, allowing developers to easily create plugins to meet their specific needs.

For example, let us implement a plugin that outputs a file to the dist directory. The implementation comparison between Rspack and Rsbuild is as follows:

![](https://assets.rspack.rs/rsbuild/assets/rsbuild-1-0-plugin-compare.png)

As shown, the API style of the Rsbuild plugin is similar to esbuild, it can be defined by a function. The plugin hooks have been simplified to avoid verbose APIs, making plugin development more intuitive.

## How to use 1.0

* If you haven't used Rsbuild before, you can experience it through the [CodeSandbox example](https://codesandbox.io/p/github/rstackjs/rsbuild-codesandbox-example) or refer to the [Quick start](/guide/start/quick-start.md) to use Rsbuild.
* If you are using Rsbuild 0.7 or earlier, please note that 1.0 includes some breaking changes. You can refer to the [Migrating from 0.x](/guide/upgrade/v0-to-v1.md) document to upgrade.
* Rsbuild also provides migration guides for projects that use webpack, CRA, Vue CLI, etc. See [Migrate from Existing Projects](/guide/start/quick-start.md#migrate-from-existing-projects).

> Give a star 🌟 to the [Rsbuild GitHub repository](https://github.com/web-infra-dev/rsbuild).

## What's next

Rsbuild 1.0 provides several advanced features for the development of enterprise applications and higher-level tools, such as the [multi-environment build API](/guide/advanced/environments.md), [SSR API](/guide/advanced/ssr.md), [plugin API](/plugins/dev/index.md), [Module Federation support](/guide/advanced/module-federation.md), and [library build (Rslib)](https://github.com/web-infra-dev/rslib). We plan to continue to enhance these features to better support the development of the Rsbuild ecosystem.

In the next 12 to 18 months, Rsbuild will evolve together with Rspack, adopting Rspack's new features as soon as they become available. These features include persistent caching, faster HMR, and TypeScript-based optimizations. For more details, see [Rspack - What's next](https://rspack.rs/blog/announcing-1-0#whats-next).

Finally, a big thank you to all the developers who have contributed to Rsbuild ❤️:

![](https://assets.rspack.rs/rsbuild/assets/rsbuild-1-0-contributors.png)

---

# Source: https://rsbuild.dev/guide/migration/vite-plugin.md

# Vite plugin

This chapter introduces how to migrate a Vite plugin to Rsbuild plugin.

## Existing plugins

Before migrating a Vite plugin, it is recommended to check if there is a corresponding plugin in the Rsbuild ecosystem. You can find the plugins through the following pages:

* [Rsbuild official plugins](/plugins/list.md)
* [Rsbuild community plugins](https://github.com/rstackjs/awesome-rstack?tab=readme-ov-file#rsbuild-plugins)

## Define a plugin

Rsbuild plugin is defined in a way similar to Vite, usually a function that accepts plugin options as a parameter and returns a plugin description object.

The main difference is that Vite's hooks are defined directly on the plugin description object, while Rsbuild's hooks are accessed and called through the [api object](/plugins/dev/core.md). This allows you to control the timing of plugin API calls more flexibly.

* Vite plugin:

```ts title="vitePlugin.ts"
const vitePlugin = (options) => ({
  name: 'vite-plugin',
  transform() {
    // ...
  },
});
```

* Rsbuild plugin:

```ts title="rsbuildPlugin.ts"
const rsbuildPlugin = (options) => ({
  name: 'rsbuild-plugin',
  setup(api) {
    api.transform(() => {
      // ...
    });
  },
});
```

## Plugin hooks

Rsbuild's plugin API covers most of the Vite and Rollup plugin hooks, for example:

| Vite plugin hooks    | Rsbuild plugin API                                                                                                     |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `resolveId`          | [resolve](/plugins/dev/core.md#apiresolve)                                                                                |
| `transform`          | [transform](/plugins/dev/core.md#apitransform)                                                                            |
| `config`             | [modifyRsbuildConfig](/plugins/dev/hooks.md#modifyrsbuildconfig)                                                          |
| `configResolved`     | [getNormalizedConfig](/plugins/dev/core.md#apigetnormalizedconfig)                                                        |
| `configEnvironment`  | [modifyEnvironmentConfig](/plugins/dev/hooks.md#modifyenvironmentconfig)                                                  |
| `configureServer`    | [onBeforeStartDevServer](/plugins/dev/hooks.md#onbeforestartdevserver)                                                    |
| `buildStart`         | [onBeforeBuild](/plugins/dev/hooks.md#onbeforebuild), [onBeforeStartDevServer](/plugins/dev/hooks.md#onbeforestartdevserver) |
| `buildEnd`           | [onAfterBuild](/plugins/dev/hooks.md#onafterbuild), [onCloseDevServer](/plugins/dev/hooks.md#onclosedevserver)               |
| `closeBundle`        | [onCloseBuild](/plugins/dev/hooks.md#onclosebuild), [onCloseDevServer](/plugins/dev/hooks.md#onclosedevserver)               |
| `transformIndexHtml` | [modifyHTML](/plugins/dev/hooks.md#modifyhtml), [modifyHTMLTags](/plugins/dev/hooks.md#modifyhtmltags)                       |

See [Plugin system](/plugins/dev/index.md) for more details.

## `config` hook

Rsbuild provides the [modifyRsbuildConfig](/plugins/dev/hooks.md#modifyrsbuildconfig) hook to modify Rsbuild configuration. Since Rsbuild and Vite have different configuration structures, you'll need to adjust your configuration when migrating Vite plugins.

For example, you should replace Vite's `define` option with Rsbuild's [source.define](/config/source/define.md) option.

* Vite plugin:

```ts title="vitePlugin.ts"
const vitePlugin = {
  name: 'my-plugin',
  config: (config) => {
    config.define = {
      ...config.define,
      FOO: '"foo"',
    };
  },
};
```

* Rsbuild plugin:

```ts title="rsbuildPlugin.ts"
const rsbuildPlugin = {
  name: 'my-plugin',
  setup(api) {
    api.modifyRsbuildConfig((config) => {
      config.source ||= {};
      config.source.define = {
        ...config.source.define,
        FOO: '"foo"',
      };
    });
  },
};
```

:::tip
See [Config migration](/guide/migration/vite.md#config-migration) to learn how to migrate Vite configurations to Rsbuild.
:::

## `configEnvironment` hook

Rsbuild provides the [modifyEnvironmentConfig](/plugins/dev/hooks.md#modifyenvironmentconfig) hook to modify the configuration of a specific environment.

* Vite plugin:

```ts
const vitePlugin = {
  name: 'config-environment',
  configEnvironment(name, config) {
    if (name === 'web') {
      config.resolve.alias = {
        // ...
      };
    }
  },
};
```

* Rsbuild plugin:

```js
const rsbuildPlugin = {
  name: 'config-environment',
  setup(api) {
    api.modifyEnvironmentConfig((config, { name }) => {
      if (name === 'web') {
        config.resolve.alias = {
          // ...
        };
      }
    });
  },
};
```

## `configResolved` hook

Rsbuild provides the [api.getNormalizedConfig](/plugins/dev/core.md#apigetnormalizedconfig) method to get the resolved configuration. This method serves a similar purpose to Vite's `configResolved` hook.

* Vite plugin:

```ts title="vitePlugin.ts"
const vitePlugin = () => {
  let config;
  return {
    name: 'read-config',
    configResolved(resolvedConfig) {
      config = resolvedConfig;
    },
    transform() {
      console.log(config);
      // ...
    },
  };
};
```

* Rsbuild plugin:

```ts title="rsbuildPlugin.ts"
const rsbuildPlugin = () => ({
  name: 'read-config',
  setup(api) {
    api.transform(() => {
      const config = api.getNormalizedConfig();
      console.log(config);
      // ...
    });
  },
});
```

## `transformIndexHtml` hook

Vite's `transformIndexHtml` hook corresponds to two hooks in Rsbuild:

* [modifyHTML](/plugins/dev/hooks.md#modifyhtml): for modifying HTML content
* [modifyHTMLTags](/plugins/dev/hooks.md#modifyhtmltags): for modifying HTML tags

Here is an example of replacing the HTML title.

* Vite Plugin:

```ts title="vitePlugin.ts"
const htmlPlugin = () => {
  return {
    name: 'html-plugin',
    transformIndexHtml(html) {
      return html.replace(
        /<title>(.*?)<\/title>/,
        `<title>Title replaced!</title>`,
      );
    },
  };
};
```

* Rsbuild Plugin:

```ts title="rsbuildPlugin.ts"
const rsbuildPlugin = {
  name: 'html-plugin',
  setup(api) {
    api.modifyHTML((html) => {
      return html.replace(
        /<title>(.*?)<\/title>/,
        `<title>Title replaced!</title>`,
      );
    });
  },
};
```

## `configureServer` hook

Rsbuild provides the `onBeforeStartDevServer` hook to replace Vite's `configureServer` hook, which allows you to get the dev server instance and add custom middleware.

* Vite plugin:

```ts title="vitePlugin.ts"
const vitePlugin = () => ({
  name: 'setup-middleware',
  configureServer(server) {
    server.middlewares.use((req, res, next) => {
      // custom handle request...
    });
  },
});
```

* Rsbuild plugin:

```ts title="rsbuildPlugin.ts"
const rsbuildPlugin = {
  name: 'setup-middleware',
  setup(api) {
    api.onBeforeStartDevServer(({ server }) => {
      server.middlewares.use((req, res, next) => {
        // custom handle request...
      });
    });
  },
};
```

## `apply` property

Rsbuild plugin provides the same [apply property](/plugins/dev/core.md#conditional-application) as Vite plugins.

* Vite plugin:

```ts title="vitePlugin.ts"
const vitePlugin = {
  name: 'vite-plugin',
  apply: 'build',
};
```

* Rsbuild plugin:

```ts title="rsbuildPlugin.ts"
const rsbuildPlugin = {
  name: 'rsbuild-plugin',
  apply: 'build',
};
```

---

# Source: https://rsbuild.dev/guide/migration/vite.md

# Vite

This guide explains how to migrate a Vite project to Rsbuild.

## Installing dependencies

First, replace Vite's npm dependencies with Rsbuild's equivalents.

import { PackageManagerTabs } from '@theme';

* Remove Vite dependencies:

<PackageManagerTabs command="remove vite" />

* Install Rsbuild dependencies:

<PackageManagerTabs command="add @rsbuild/core -D" />

## Updating npm scripts

Next, update the npm scripts in your package.json to run Rsbuild CLI commands.

```json title="package.json"
{
  "scripts": {
    "dev": "vite", // [!code --]
    "build": "vite build", // [!code --]
    "preview": "vite preview", // [!code --]
    "dev": "rsbuild dev", // [!code ++]
    "build": "rsbuild build", // [!code ++]
    "preview": "rsbuild preview" // [!code ++]
  }
}
```

## Create configuration file

Create an Rsbuild configuration file named `rsbuild.config.ts` alongside package.json, and add the following content:

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

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

## Build entry

The default build entry points for Rsbuild and Vite are different. Vite uses `index.html` as the default entry, while Rsbuild uses `src/index.js`.

When migrating from Vite to Rsbuild, use Rsbuild's [source.entry](/config/source/entry.md) to set the build entry and [html.template](/config/html/template.md) to set the template.

Using a newly created Vite project as an example, first delete the `<script>` tags from `index.html`:

```html title="index.html"
<!-- [!code --] -->
<script type="module" src="/src/main.ts"></script>
```

Then add the following configuration:

```ts title="rsbuild.config.ts"
export default {
  html: {
    template: './index.html',
  },
  source: {
    entry: {
      index: './src/main.ts',
    },
  },
};
```

Rsbuild automatically injects the `<script>` tags into the generated HTML files during the build.

## Migrating plugins

Most common Vite plugins can be easily migrated to Rsbuild plugins, such as:

| Vite                                                                                   | Rsbuild                                                                                        |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [@vitejs/plugin-react](https://npmjs.com/package/@vitejs/plugin-react)                 | [@rsbuild/plugin-react](/plugins/list/plugin-react.md)                                            |
| [@vitejs/plugin-react-swc](https://npmjs.com/package/@vitejs/plugin-react-swc)         | [@rsbuild/plugin-react](/plugins/list/plugin-react.md)                                            |
| [@vitejs/plugin-vue](https://npmjs.com/package/@vitejs/plugin-vue)                     | [@rsbuild/plugin-vue](/plugins/list/plugin-vue.md)                                                |
| [@vitejs/plugin-vue2](https://npmjs.com/package/@vitejs/plugin-vue2)                   | [@rsbuild/plugin-vue2](https://github.com/rstackjs/rsbuild-plugin-vue2)                        |
| [@vitejs/plugin-vue-jsx](https://npmjs.com/package/@vitejs/plugin-vue-jsx)             | [@rsbuild/plugin-vue-jsx](https://github.com/rstackjs/rsbuild-plugin-vue-jsx)                  |
| [@vitejs/plugin-vue2-jsx](https://npmjs.com/package/@vitejs/plugin-vue2-jsx)           | [@rsbuild/plugin-vue2-jsx](https://github.com/rstackjs/rsbuild-plugin-vue2-jsx)                |
| [@vitejs/plugin-basic-ssl](https://npmjs.com/package/@vitejs/plugin-basic-ssl)         | [@rsbuild/plugin-basic-ssl](https://github.com/rstackjs/rsbuild-plugin-basic-ssl)              |
| [@vitejs/plugin-legacy](https://npmjs.com/package/@vitejs/plugin-legacy)               | No need to use, see [Browser Compatibility](/guide/advanced/browser-compatibility.md) for details |
| [@sveltejs/vite-plugin-svelte](https://npmjs.com/package/@sveltejs/vite-plugin-svelte) | [@rsbuild/plugin-svelte](/plugins/list/plugin-svelte.md)                                          |
| [vite-plugin-svgr](https://npmjs.com/package/vite-plugin-svgr)                         | [@rsbuild/plugin-svgr](/plugins/list/plugin-svgr.md)                                              |
| [vite-plugin-checker](https://npmjs.com/package/vite-plugin-checker)                   | [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check)            |
| [vite-plugin-eslint](https://npmjs.com/package/vite-plugin-eslint)                     | [@rsbuild/plugin-eslint](https://github.com/rstackjs/rsbuild-plugin-eslint)                    |
| [vite-plugin-static-copy](https://npmjs.com/package/vite-plugin-static-copy)           | [output.copy](/config/output/copy.md)                                                             |
| [vite-plugin-node-polyfills](https://npmjs.com/package/vite-plugin-node-polyfills)     | [@rsbuild/plugin-node-polyfill](https://github.com/rstackjs/rsbuild-plugin-node-polyfill)      |
| [vite-plugin-solid](https://npmjs.com/package/vite-plugin-solid)                       | [@rsbuild/plugin-solid](/plugins/list/plugin-solid.md)                                            |
| [@preact/preset-vite](https://npmjs.com/package/@preact/preset-vite)                   | [@rsbuild/plugin-preact](/plugins/list/plugin-preact.md)                                          |

You can refer to [Plugin List](/plugins/list/index.md) to learn more about available plugins.

## Config migration

Here is the corresponding Rsbuild configuration for each Vite option:

| Vite                                  | Rsbuild                                                          |
| ------------------------------------- | ---------------------------------------------------------------- |
| root                                  | [root](/config/root.md)                                             |
| mode                                  | [mode](/config/mode.md)                                             |
| base                                  | [server.base](/config/server/base.md)                               |
| define                                | [source.define](/config/source/define.md)                           |
| plugins                               | [plugins](/config/plugins.md)                                       |
| appType                               | [server.historyApiFallback](/config/server/history-api-fallback.md) |
| envDir                                | [Env directory](/guide/advanced/env-vars.md#env-directory)          |
| logLevel                              | [logLevel](/config/log-level.md)                                    |
| cacheDir                              | [buildCache](/config/performance/build-cache.md)                    |
| publicDir                             | [server.publicDir](/config/server/public-dir.md)                    |
| customLogger                          | [Custom logger](/api/javascript-api/core.md#custom-logger)          |
| assetsInclude                         | [source.assetsInclude](/config/source/assets-include.md)            |
| resolve.alias                         | [resolve.alias](/config/resolve/alias.md)                           |
| resolve.dedupe                        | [resolve.dedupe](/config/resolve/dedupe.md)                         |
| resolve.extensions                    | [resolve.extensions](/config/resolve/extensions.md)                 |
| resolve.conditions                    | [resolve.conditionNames](/config/resolve/condition-names.md)        |
| resolve.mainFields                    | [resolve.mainFields](/config/resolve/main-fields.md)                |
| resolve.preserveSymlinks              | [tools.rspack.resolve.symlinks](/config/tools/rspack.md)            |
| html.cspNonce                         | [security.nonce](/config/security/nonce.md)                         |
| css.modules                           | [output.cssModules](/config/output/css-modules.md)                  |
| css.postcss                           | [tools.postcss](/config/tools/postcss.md)                           |
| css.preprocessorOptions.sass          | [pluginSass](/plugins/list/plugin-sass.md)                          |
| css.preprocessorOptions.less          | [pluginLess](/plugins/list/plugin-less.md)                          |
| css.preprocessorOptions.stylus        | [pluginStylus](/plugins/list/plugin-stylus.md)                      |
| css.devSourcemap                      | [output.sourceMap](/config/output/source-map.md)                    |
| css.lightningcss                      | [tools.lightningcssLoader](/config/tools/lightningcss-loader.md)    |
| server.host, preview.host             | [server.host](/config/server/host.md)                               |
| server.port, preview.port             | [server.port](/config/server/port.md)                               |
| server.cors, preview.cors             | [server.cors](/config/server/cors.md)                               |
| server.strictPort, preview.strictPort | [server.strictPort](/config/server/strict-port.md)                  |
| server.https, preview.https           | [server.https](/config/server/https.md)                             |
| server.open, preview.open             | [server.open](/config/server/open.md)                               |
| server.proxy, preview.proxy           | [server.proxy](/config/server/proxy.md)                             |
| server.headers, preview.headers       | [server.headers](/config/server/headers.md)                         |
| server.hmr                            | [dev.hmr](/config/dev/hmr.md), [dev.client](/config/dev/client.md)     |
| server.middlewareMode                 | [server.middlewareMode](/config/server/middleware-mode.md)          |
| build.target, build.cssTarget         | [Browserslist](/guide/advanced/browserslist.md)                     |
| build.outDir, build.assetsDir         | [output.distPath](/config/output/dist-path.md)                      |
| build.assetsInlineLimit               | [output.dataUriLimit](/config/output/data-uri-limit.md)             |
| build.cssMinify                       | [output.minify](/config/output/minify.md)                           |
| build.sourcemap                       | [output.sourceMap](/config/output/source-map.md)                    |
| build.lib                             | Use [Rslib](https://github.com/web-infra-dev/rslib)              |
| build.manifest                        | [output.manifest](/config/output/manifest.md)                       |
| build.ssrEmitAssets                   | [output.emitAssets](/config/output/emit-assets.md)                  |
| build.minify, build.terserOptions     | [output.minify](/config/output/minify.md)                           |
| build.emptyOutDir                     | [output.cleanDistPath](/config/output/clean-dist-path.md)           |
| build.copyPublicDir                   | [server.publicDir](/config/server/public-dir.md)                    |
| build.reportCompressedSize            | [performance.printFileSize](/config/performance/print-file-size.md) |
| ssr, worker                           | [environments](/config/environments.md)                             |

Notes:

* The table above doesn't cover every Vite option; feel free to add more.

## Environment variables

Vite injects environment variables starting with `VITE_` into the client code by default, while Rsbuild injects environment variables starting with `PUBLIC_` by default (see [public variables](/guide/advanced/env-vars.md#public-variables)).

To match Vite's behavior, you can manually call Rsbuild's [loadEnv](/api/javascript-api/core.md#loadenv) method to read environment variables starting with `VITE_`, and inject them into the client code through the [source.define](/config/source/define.md) config.

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

const { publicVars } = loadEnv({ prefixes: ['VITE_'] });

export default defineConfig({
  source: {
    define: publicVars,
  },
});
```

Rsbuild injects the following [environment variables](/guide/advanced/env-vars.md) by default:

* `import.meta.env.MODE`
* `import.meta.env.BASE_URL`
* `import.meta.env.PROD`
* `import.meta.env.DEV`

For `import.meta.env.SSR`, you can set it through the [environments](/config/environments.md) and [source.define](/config/source/define.md) configuration options:

```ts title="rsbuild.config.ts"
export default defineConfig({
  environments: {
    web: {
      source: {
        define: {
          'import.meta.env.SSR': JSON.stringify(false),
        },
      },
    },
    node: {
      source: {
        define: {
          'import.meta.env.SSR': JSON.stringify(true),
        },
      },
      output: {
        target: 'node',
      },
    },
  },
});
```

## Preset types

Vite provides some preset type definitions through the `vite-env.d.ts` file. When migrating to Rsbuild, you can use the [preset types](/guide/basic/typescript.md#preset-types) provided by `@rsbuild/core`:

```ts title="src/env.d.ts"
// [!code --]
/// <reference types="vite/client" />
// [!code ++]
/// <reference types="@rsbuild/core/types" />
```

## Glob import

Vite provides `import.meta.glob()` for importing multiple modules.

When migrating to Rsbuild, you can use the [import.meta.webpackContext()](https://rspack.rs/api/runtime-api/module-variables#importmetawebpackcontext) function of Rspack instead:

* Vite:

```js
const modules = import.meta.glob('./dir/*.js');

for (const path in modules) {
  modules[path]().then((mod) => {
    console.log(path, mod);
  });
}
```

* Rsbuild:

```js
const context = import.meta.webpackContext('./dir', {
  // Whether to search subdirectories
  recursive: false,
  regExp: /\.js$/,
});

for (const path of context.keys()) {
  const mod = context(path);
  console.log(path, mod);
}
```

## vite-tsconfig-paths

Rsbuild supports TypeScript's `paths` option as alias out of the box, so you can remove the `vite-tsconfig-paths` dependency directly.

See [Path aliases](/guide/advanced/alias.md) for more details.

## Migrating Vite plugins

See [Vite plugin](/guide/migration/vite-plugin.md) to learn how to migrate Vite plugins.

## Validating results

After completing the steps above, the basic migration from Vite to Rsbuild is complete. You can now run the `npm run dev` command to try starting the dev server.

If you encounter issues during the build process, debug using the error log, or check the Vite configuration for any settings that haven't been migrated to Rsbuild.

## Contents supplement

This document covers only part of the migration process. If you have content to add, feel free to contribute via a pull request 🤝.

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

---

# Source: https://rsbuild.dev/guide/migration/vue-cli.md

# Vue CLI

This chapter introduces how to migrate a [Vue CLI](https://github.com/vuejs/vue-cli) project to Rsbuild.

## Install dependencies

First, you need to replace the npm dependencies of Vue CLI with Rsbuild's dependencies.

import { PackageManagerTabs } from '@theme';

* Remove Vue CLI dependencies:

<PackageManagerTabs command="remove @vue/cli-service @vue/cli-plugin-babel @vue/cli-plugin-eslint core-js" />

* Install Rsbuild dependencies:

<PackageManagerTabs command="add @rsbuild/core @rsbuild/plugin-vue -D" />

:::tip
If your project is based on Vue 2, replace `@rsbuild/plugin-vue` with `@rsbuild/plugin-vue2`.
:::

## Update npm scripts

Next, you need to update the npm scripts in the package.json file to Rsbuild's CLI commands.

```json title="package.json"
{
  "scripts": {
    "serve": "vue-cli-service serve", // [!code --]
    "build": "vue-cli-service build", // [!code --]
    "serve": "rsbuild dev", // [!code ++]
    "build": "rsbuild build", // [!code ++]
    "preview": "rsbuild preview" // [!code ++]
  }
}
```

:::tip
Rsbuild does not integrate ESLint, so it does not provide a command to replace `vue-cli-service lint`. You can directly use ESLint's [CLI commands](https://eslint.org/docs/latest/use/command-line-interface) as an alternative.
:::

## Create configuration file

Create a Rsbuild configuration file `rsbuild.config.ts` in the same directory as package.json, and add the following content:

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

export default defineConfig({
  plugins: [pluginVue()],
  source: {
    // Specify the entry file
    entry: {
      index: './src/main.js',
    },
  },
});
```

:::tip
If your project is based on Vue 2, use `import { pluginVue2 } from '@rsbuild/plugin-vue2';`.
:::

## HTML template

Vue CLI uses the `public/index.html` file as the default HTML template. In Rsbuild, you can specify the HTML template through [html.template](/config/html/template.md):

```ts title="rsbuild.config.ts"
export default defineConfig({
  html: {
    template: './public/index.html',
  },
});
```

In the HTML template, if you are using the `BASE_URL` variable from Vue CLI, replace it with Rsbuild's [assetPrefix variable](/config/html/template-parameters.md) and use a forward slash for concatenation:

```html
<link rel="icon" href="<%= BASE_URL %>favicon.ico" />
<!-- [!code --] -->
<link rel="icon" href="<%= assetPrefix %>/favicon.ico" />
<!-- [!code ++] -->
```

This completes the basic migration from Vue CLI to Rsbuild. You can now run the `npm run serve` command to try starting the dev server.

## Config migration

Here is the corresponding Rsbuild configuration for Vue CLI configuration:

| Vue CLI                                                                                                                                 | Rsbuild                                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [publicPath](https://cli.vuejs.org/config/#publicpath)                                                                                  | [dev.assetPrefix](/config/dev/asset-prefix.md) / [output.assetPrefix](/config/output/asset-prefix.md)                                                        |
| [outputDir](https://cli.vuejs.org/config/#outputdir) / [assetsDir](https://cli.vuejs.org/config/#assetsdir)                             | [output.distPath](/config/output/dist-path.md)                                                                                                            |
| [filenameHashing](https://cli.vuejs.org/config/#filenamehashing)                                                                        | [output.filenameHash](/config/output/filename-hash.md)                                                                                                    |
| [pages](https://cli.vuejs.org/config/#pages)                                                                                            | [source.entry](/config/source/entry.md) / [html.template](/config/html/template.md) / [html.title](/config/html/title.md)                                       |
| [transpileDependencies](https://cli.vuejs.org/config/#transpiledependencies)                                                            | [source.include](/config/source/include.md)                                                                                                               |
| [productionSourceMap](https://cli.vuejs.org/config/#productionsourcemap) / [css.sourceMap](https://cli.vuejs.org/config/#css-sourcemap) | [output.sourceMap](/config/output/source-map.md)                                                                                                          |
| [crossorigin](https://cli.vuejs.org/config/#crossorigin)                                                                                | [html.crossorigin](/config/html/crossorigin.md)                                                                                                           |
| [configureWebpack](https://cli.vuejs.org/config/#configurewebpack)                                                                      | [tools.rspack](/config/tools/rspack.md)                                                                                                                   |
| [chainWebpack](https://cli.vuejs.org/config/#chainwebpack)                                                                              | [tools.bundlerChain](/config/tools/bundler-chain.md)                                                                                                      |
| [css.extract](https://cli.vuejs.org/config/#css-extract)                                                                                | [output.injectStyles](/config/output/inject-styles.md)                                                                                                    |
| [css.loaderOptions](https://cli.vuejs.org/config/#css-loaderoptions)                                                                    | [tools.cssLoader](/config/tools/css-loader.md) / [less](/plugins/list/plugin-less.md) / [sass](/plugins/list/plugin-sass.md) / [postcss](/config/tools/postcss.md) |
| [devServer.proxy](https://cli.vuejs.org/config/#devserver-proxy)                                                                        | [server.proxy](/config/server/proxy.md)                                                                                                                   |

Notes:

* When migrating `configureWebpack`, note that most of the webpack and Rsbuild configs are the same, but there are also some differences or functionalities not implemented in Rsbuild.
* The above table does not cover all configurations of Vue CLI, feel free to add more.

## Environment variables

Vue CLI injects environment variables starting with `VUE_APP_` into the client code by default, while Rsbuild injects environment variables starting with `PUBLIC_` by default (see [public variables](/guide/advanced/env-vars.md#public-variables)).

To be compatible with Vue CLI's behavior, you can manually call Rsbuild's [loadEnv](/api/javascript-api/core.md#loadenv) method to read environment variables starting with `VUE_APP_`, and inject them into the client code through the [source.define](/config/source/define.md) config.

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

const { publicVars } = loadEnv({ prefixes: ['VUE_APP_'] });

export default defineConfig({
  source: {
    define: publicVars,
  },
});
```

## 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 pull request 🤝.

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

---

# Source: https://rsbuild.dev/guide/framework/vue.md

# Vue

This document explains how to build a Vue 3 or Vue 2 application using Rsbuild.

## Create a Vue application

Create a Vue application with Rsbuild using [create-rsbuild](/guide/start/quick-start.md#create-an-rsbuild-application). Run this command:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs
  command={{
  npm: 'npm create rsbuild@latest',
  yarn: 'yarn create rsbuild',
  pnpm: 'pnpm create rsbuild@latest',
  bun: 'bun create rsbuild@latest',
}}
/>

Then select `Vue 3` or `Vue 2` when prompted to "Select framework".

## Vue 3

### Use Vue in an existing project

To compile Vue SFC (Single File Components), register the Rsbuild [Vue plugin](/plugins/list/plugin-vue.md). The plugin automatically adds the necessary configuration for Vue builds.

For example, register in `rsbuild.config.ts`:

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

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

:::tip
For projects using Vue CLI, you can refer to the [Vue CLI Migration Guide](/guide/migration/vue-cli.md).
:::

### Use the JSX syntax of Vue

To use the JSX syntax of Vue, you also need to register the [@rsbuild/plugin-vue-jsx](https://github.com/rstackjs/rsbuild-plugin-vue-jsx).

### TypeScript support

Rsbuild supports compiling TypeScript by default.

Please refer to the [TypeScript - IDE Support](https://vuejs.org/guide/typescript/overview.html#ide-support) section of the Vue documentation to learn how to set up Vue TypeScript support in your IDE.

## Vue 2

### Use Vue 2 in an existing project

To compile Vue SFC (Single File Components), you need to register the Rsbuild [Vue 2 plugin](https://github.com/rstackjs/rsbuild-plugin-vue2). The plugin will automatically add the necessary configuration for Vue builds.

For example, register in `rsbuild.config.ts`:

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

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

:::tip

* The Vue 2 plugin only supports Vue >= 2.7.0.
* For projects using Vue CLI, you can refer to the [Vue CLI Migration Guide](/guide/migration/vue-cli.md).

:::

### Use the JSX syntax of Vue

To use the JSX syntax of Vue, you also need to register the [@rsbuild/plugin-vue2-jsx](https://github.com/rstackjs/rsbuild-plugin-vue2-jsx).

### Type declarations

In a TypeScript project, you need to add type definitions for `*.vue` files so that TypeScript can recognize them correctly.

Create `env.d.ts` in the `src` directory and add the following content:

```ts title="src/env.d.ts"
declare module '*.vue' {
  import Vue from 'vue';

  export default Vue;
}
```

---

# Source: https://rsbuild.dev/guide/basic/wasm-assets.md

# Wasm

Rsbuild provides native support for WebAssembly (WASM) modules, allowing you to import and use `.wasm` files directly in your project.

:::tip What is WebAssembly
WebAssembly (Wasm) is a portable, high-performance binary format designed to execute CPU-intensive computing tasks in modern web browsers, bringing near-native performance and reliability to the web platform.
:::

## Import

You can reference a WebAssembly module in a JavaScript file using named imports:

```js title="index.js"
import { add } from './add.wasm';

console.log(add); // [native code]
console.log(add(1, 2)); // 3
```

WebAssembly modules can also be imported via dynamic import:

```js title="index.js"
import('./add.wasm').then(({ add }) => {
  console.log('---- Async Wasm Module');
  console.log(add); // [native code]
  console.log(add(1, 2)); // 3
});
```

You can also get the path of a WebAssembly module using the `new URL` syntax:

```js title="index.js"
const wasmURL = new URL('./add.wasm', import.meta.url);

console.log(wasmURL.pathname); // "/static/wasm/[contenthash:8].module.wasm"
```

## Output directory

When you import a `.wasm` asset, Rsbuild outputs it to the `dist/static/wasm` directory by default.

You can change the output directory for `.wasm` files using the [output.distPath](/config/output/dist-path.md) configuration:

```ts
export default {
  output: {
    distPath: {
      wasm: 'resource/wasm',
    },
  },
};
```

## Type declaration

When you import a WebAssembly file in TypeScript code, you usually need to add the corresponding type declaration.

For example, if the `add.wasm` file exports an `add()` method, you can create an `add.wasm.d.ts` file in the same directory and add the corresponding type declaration:

```ts title="add.wasm.d.ts"
export const add: (num1: number, num2: number) => number;
```

---

# Source: https://rsbuild.dev/config/dev/watch-files.md

# dev.watchFiles

* **Type:**

```ts
type WatchFiles = {
  paths: string | string[];
  type?: 'reload-page' | 'reload-server';
  // watch options for chokidar
  options?: ChokidarOptions;
};

type WatchFilesConfig = WatchFiles | WatchFiles[];
```

* **Default:** `undefined`

Watch specified files and directories for changes. When a change is detected, it can trigger a page reload or restart the dev server.

## paths

* **Type:** `string | string[]`
* **Default:** `undefined`

Paths of the files or directories to watch, supports glob syntax. It can be a single path or an array of multiple paths.

* Watching a single file:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    watchFiles: {
      paths: 'public/demo.txt',
    },
  },
};
```

* Using glob to match multiple files:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    watchFiles: {
      paths: 'src/**/*.txt',
    },
  },
};
```

* Watching multiple file paths:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    watchFiles: {
      paths: ['src/**/*.txt', 'public/**/*'],
    },
  },
};
```

## type

* **Type:** `'reload-page' | 'reload-server'`
* **Default:** `'reload-page'`

Specifies whether to trigger a page reload or restart the dev server when a file changes.

### reload-page

`reload-page` means that when a file changes, the page in the browser will automatically reload. If the type is not explicitly specified, Rsbuild defaults to the `reload-page` behavior.

This can be used to watch changes to static assets, such as files in the [public directory](/config/server/public-dir.md).

```ts title="rsbuild.config.ts"
export default {
  dev: {
    watchFiles: {
      type: 'reload-page',
      paths: 'public/**/*',
    },
  },
};
```

> If both [dev.hmr](/config/dev/hmr.md) and [dev.liveReload](/config/dev/live-reload.md) are set to `false`, the page will not automatically reload.

### reload-server

`reload-server` means that the dev server will automatically restart when a file changes. This can be used to watch changes to configuration files, such as modules imported by your `rsbuild.config.ts` file.

For example, if you maintain some common configuration files in the `config` directory, such as `common.ts`, you may want the dev server to automatically restart when these files change. Example configuration:

```ts title="rsbuild.config.ts"
import { commonConfig } from './config/common';

export default {
  ...commonConfig,
  dev: {
    watchFiles: {
      type: 'reload-server',
      paths: ['./config/*.ts'],
    },
  },
};
```

Note that the reload-server functionality is provided by Rsbuild CLI. If you are using a custom server or a framework built on top of Rsbuild, this configuration is currently not supported.

## options

* **Type:** `ChokidarOptions`
* **Default:** `undefined`

`watchFiles` is implemented based on [chokidar v4](https://github.com/paulmillr/chokidar#api), and you can pass chokidar options through `options`.

```ts title="rsbuild.config.ts"
export default {
  dev: {
    watchFiles: {
      paths: 'src/**/*.txt',
      options: {
        usePolling: false,
      },
    },
  },
};
```

## Notes

`watchFiles` is not applicable for watching build dependency files. When an Rsbuild build starts, the underlying Rspack automatically watches all build dependencies. Any changes to these files will trigger a new build.

If you want to prevent some files from triggering a rebuild when they change, you can use Rspack's [watchOptions.ignored](https://rspack.rs/config/watch#watchoptionsignored) configuration item.

> See [HMR - File Watching](/guide/advanced/hmr.md#file-watching) for details.

---

# Source: https://rsbuild.dev/guide/basic/web-workers.md

# Web Workers

This page explains how to configure and use [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers) in an Rsbuild project.

:::tip Web Workers
Web Workers are a type of JavaScript program that runs in the background, independently of other scripts, without affecting the performance of the page. This makes it possible to run long-running scripts, such as ones that handle complex calculations or access remote resources, without blocking the user interface or other scripts. Web workers provide an easy way to run tasks in the background and improve the overall performance of web applications.
:::

## Use Web Workers

### Import with constructors

Rspack provides built-in support for Web Workers, so you can use them directly in Rsbuild projects without adding extra loaders.

For example, create a file called `worker.js`:

```js title="worker.js"
self.onmessage = (event) => {
  const result = event.data * 2;
  self.postMessage(result);
};
```

Then use this worker in the main thread:

```js title="index.js"
const worker = new Worker(new URL('./worker.js', import.meta.url));

worker.onmessage = (event) => {
  console.log('The results from Workers:', event.data);
};

worker.postMessage(10);
```

Rspack supports multiple Worker syntaxes by default. See [Rspack - Web Workers](https://rspack.rs/guide/features/web-workers) for more information.

### Using worker-loader

If your project already uses `worker-loader`, or you want to use the `inline` and other features provided by `worker-loader`, you can use [worker-rspack-loader](https://github.com/rstackjs/worker-rspack-loader) as an alternative to `worker-loader` in Rsbuild projects.

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: {
      resolveLoader: {
        alias: {
          // Modify the resolution of worker-loader in the inline loader
          // such as `worker-loader!pdfjs-dist/es5/build/pdf.worker.js`
          'worker-loader': require.resolve('worker-rspack-loader'),
        },
      },
      module: {
        rules: [
          {
            test: /\.worker\.js$/,
            loader: 'worker-rspack-loader',
          },
        ],
      },
    },
  },
};
```

When using `worker-rspack-loader`, load the Web Worker file with `import` instead of `new Worker('/path/to/worker.js')`.

```js
import Worker from './file.worker.js';

const worker = new Worker();

worker.postMessage({ a: 1 });
```

> `worker-loader` is no longer maintained. If you don't need to inline Web Workers, we recommend using the `new Worker()` syntax.

### Loading scripts from remote URLs

By default, the worker script is emitted as a separate chunk. You can upload this file to a CDN, but it must follow the [same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy).

If you want your worker scripts to be accessible across domains, a common solution is to load them via [importScripts](https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/importScripts) (not subject to CORS). You can refer to the following code:

```js title="index.js"
// https://github.com/jantimon/remote-web-worker
import 'remote-web-worker';

const worker = new Worker(new URL('./worker.js', import.meta.url), {
  type: 'classic',
});

worker.onmessage = (event) => {
  console.log('The results from Workers:', event.data);
};

worker.postMessage(10);
```

For detailed discussions on cross-domain issues, please refer to [Discussions - webpack 5 web worker support for CORS?](https://github.com/webpack/webpack/discussions/14648)

### Browser compatibility

When your application includes both main-thread code and Web Workers created with `new Worker`, note that Web Workers run in isolated threads and do not share the main-thread environment. As a result, Rsbuild’s polyfill [entry mode](/guide/advanced/browser-compatibility.md#entry-mode) does not apply to Web Workers. In this case, it’s recommended to use the [usage mode](/guide/advanced/browser-compatibility.md#usage-mode) to inject the required polyfills directly into each Web Worker.

```ts title="rsbuild.config.ts"
export default {
  output: {
    polyfill: 'usage',
  },
};
```

## Standalone build

Rsbuild supports standalone building of Web Workers bundles. When you need to configure independent build options for Web Workers or provide Web Workers for use by other applications, you can use the following methods.

Set Rsbuild's [output.target](/config/output/target.md) configuration option to `'web-worker'` to generate build artifacts that run in Worker threads.

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

Use [environments](/config/environments.md) to build both Web Workers and the main application simultaneously:

```ts title="rsbuild.config.ts"
export default {
  environments: {
    web: {
      // Build configuration for the main application
    },
    webWorker: {
      // Build configuration for Web Workers
      output: {
        target: 'web-worker',
      },
    },
  },
};
```

---

# Source: https://rsbuild.dev/guide/migration/webpack.md

# webpack

This section introduces how to migrate a webpack project to Rsbuild.

## Installing dependencies

First, replace webpack's npm dependencies with Rsbuild's dependencies.

import { PackageManagerTabs } from '@theme';

* Remove webpack dependencies:

<PackageManagerTabs command="remove webpack webpack-cli webpack-dev-server" />

* Install Rsbuild dependencies:

<PackageManagerTabs command="add @rsbuild/core -D" />

## Updating npm scripts

Next, update the npm scripts in your package.json to use Rsbuild's CLI commands.

```json title="package.json"
{
  "scripts": {
    "serve": "webpack serve -c webpack.config.js", // [!code --]
    "build": "webpack build -c webpack.config.js", // [!code --]
    "dev": "rsbuild dev", // [!code ++]
    "build": "rsbuild build" // [!code ++]
  }
}
```

## Create configuration file

Create an Rsbuild configuration file `rsbuild.config.ts` in the same directory as package.json, and add the following content:

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

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

> See [Configure Rsbuild](/guide/configuration/rsbuild.md) for more.

## Config migration

Webpack projects often include complex `webpack.config.js` configuration files.

After migrating to Rsbuild, most webpack configurations (such as output, resolve, and module.rules) are built-in and no longer require manual setup.

For the few webpack configurations that need to be migrated, you can choose the following options:

* Use the [tools.rspack](/config/tools/rspack.md) option (Rspack and webpack configurations are basically equivalent).

```ts title="rsbuild.config.ts"
export default {
  tools: {
    rspack: {
      plugins: [new SomeWebpackPlugin()],
    },
  },
};
```

* Use the configuration helpers in Rsbuild; for example, you can set css-loader options through [tools.cssLoader](/config/tools/css-loader.md).

> See [Configure Rspack](/guide/configuration/rspack.md) for more.

### Build entry

webpack uses the `entry` field to set the build entry. In Rsbuild, you can use [source.entry](/config/source/entry.md) to set it.

```ts title="rsbuild.config.ts"
export default {
  source: {
    entry: {
      foo: './src/pages/foo/index.ts',
      bar: './src/pages/bar/index.ts',
    },
  },
};
```

### Cleaning up config

Because Rsbuild includes common loaders and plugins, you can remove the following dependencies to significantly speed up dependency installation:

* css-loader
* babel-loader
* style-loader
* postcss-loader
* html-webpack-plugin
* mini-css-extract-plugin
* autoprefixer
* @babel/core
* @babel/preset-env
* @babel/preset-typescript
* @babel/runtime
* ...

:::tip
The above list covers only some removable dependencies. Real-world webpack projects may include many others, so adjust as needed.
:::

### Using plugins

Rsbuild offers a rich set of plugins that provide out-of-the-box support for common scenarios. You can refer to the [Plugin List](/plugins/list/index.md) documentation to learn about these plugins.

For example, in a React project, you can integrate Rsbuild plugins as follows. First, remove React-related build dependencies that the Rsbuild React plugin already includes, such as:

* `react-refresh`
* `@babel/preset-react`
* `@pmmmwh/react-refresh-webpack-plugin`

Then follow the [React Plugin](/plugins/list/plugin-react.md) documentation to register and use it as follows:

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

export default defineConfig({
  plugins: [pluginReact()], // [!code highlight]
});
```

Most common webpack loaders and plugins still work in Rsbuild, but we recommend prioritizing Rsbuild's plugins to simplify your configuration. The following shows how they map:

| webpack                                                                                    | Rsbuild                                                                                                   |
| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| [@babel/preset-react](https://npmjs.com/package/@babel/preset-react)                       | [React Plugin](/plugins/list/plugin-react.md)                                                                |
| [vue-loader](https://npmjs.com/package/vue-loader)                                         | [Vue Plugin](/plugins/list/plugin-vue.md) or [Vue 2 Plugin](https://github.com/rstackjs/rsbuild-plugin-vue2) |
| [svelte-loader](https://npmjs.com/package/svelte-loader)                                   | [Svelte Plugin](/plugins/list/plugin-svelte.md)                                                              |
| [babel-preset-solid](https://npmjs.com/package/babel-preset-solid)                         | [Solid Plugin](/plugins/list/plugin-solid.md)                                                                |
| [babel-loader](https://npmjs.com/package/babel-loader)                                     | [Babel Plugin](/plugins/list/plugin-babel.md)                                                                |
| [sass-loader](https://npmjs.com/package/sass-loader)                                       | [Sass Plugin](/plugins/list/plugin-sass.md)                                                                  |
| [less-loader](https://npmjs.com/package/less-loader)                                       | [Less Plugin](/plugins/list/plugin-less.md)                                                                  |
| [stylus-loader](https://npmjs.com/package/stylus-loader)                                   | [Stylus Plugin](/plugins/list/plugin-stylus.md)                                                              |
| [mdx-loader](https://npmjs.com/package/mdx-loader)                                         | [MDX Plugin](https://github.com/rstackjs/rsbuild-plugin-mdx)                                              |
| [pug-loader](https://npmjs.com/package/pug-loader)                                         | [Pug Plugin](https://github.com/rstackjs/rsbuild-plugin-pug)                                              |
| [yaml-loader](https://npmjs.com/package/yaml-loader)                                       | [Yaml Plugin](https://github.com/rstackjs/rsbuild-plugin-yaml)                                            |
| [toml-loader](https://npmjs.com/package/toml-loader)                                       | [TOML Plugin](https://github.com/rstackjs/rsbuild-plugin-toml)                                            |
| [@svgr/webpack](https://npmjs.com/package/@svgr/webpack)                                   | [SVGR Plugin](/plugins/list/plugin-svgr.md)                                                                  |
| [fork-ts-checker-webpack-plugin](https://npmjs.com/package/fork-ts-checker-webpack-plugin) | [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check)                       |
| [node-polyfill-webpack-plugin](https://npmjs.com/package/node-polyfill-webpack-plugin)     | [Node Polyfill Plugin](https://github.com/rstackjs/rsbuild-plugin-node-polyfill)                          |
| [@vue/babel-plugin-jsx](https://npmjs.com/package/@vue/babel-plugin-jsx)                   | [Vue JSX Plugin](https://github.com/rstackjs/rsbuild-plugin-vue-jsx)                                      |
| [@vue/babel-preset-jsx](https://npmjs.com/package/@vue/babel-preset-jsx)                   | [Vue 2 JSX Plugin](https://github.com/rstackjs/rsbuild-plugin-vue2-jsx)                                   |
| [eslint-webpack-plugin](https://npmjs.com/package/eslint-webpack-plugin)                   | [ESLint Plugin](https://github.com/rstackjs/rsbuild-plugin-eslint)                                        |
| [babel-plugin-styled-components](https://npmjs.com/package/babel-plugin-styled-components) | [Styled Components Plugin](https://github.com/rsbuild-contrib/rsbuild-plugin-styled-components)           |

### Configure dev server

Rsbuild does not support Rspack's [devServer](https://rspack.rs/config/dev-server) config. See [Rspack Dev Server](/guide/basic/server.md#rspack-dev-server) for alternatives.

## Babel migration

Rsbuild uses SWC by default, so most commonly used Babel plugins are no longer required. Here are some common Babel plugins migration examples.

### @babel/preset-env

`@babel/preset-env` is no longer required, Rsbuild will automatically downgrade code based on the [browserslist](/guide/advanced/browserslist.md) configuration.

Note that Rsbuild does not inject polyfill by default. You can refer to [Polyfill mode](/guide/advanced/browser-compatibility.md#polyfill-mode) for how to inject.

### @babel/preset-typescript

`@babel/preset-typescript` is no longer required, as Rsbuild enables SWC's TypeScript transformation by default.

### @babel/preset-react

`@babel/preset-react` is no longer required, replace it with [@rsbuild/plugin-react](/plugins/list/plugin-react.md).

### @babel/plugin-transform-runtime

`@babel/plugin-transform-runtime` is no longer required, Rsbuild has built-in equivalent `@swc/helpers` as runtime helpers.

### babel-plugin-import

`babel-plugin-import` can be replaced with the [source.transformImport](/config/source/transform-import.md) configuration in Rsbuild.

* Babel configuration:

```js title="babel.config.js"
module.exports = {
  plugins: [
    [
      'import',
      { libraryName: 'some-library', libraryDirectory: 'es', style: true },
    ],
  ],
};
```

* Rsbuild configuration:

```ts title="rsbuild.config.ts"
export default {
  source: {
    transformImport: [
      { libraryName: 'some-library', libraryDirectory: 'es', style: true },
    ],
  },
};
```

## Validating results

After completing the above steps, you have completed the basic migration from webpack to Rsbuild. You can now run the `npm run dev` command to try starting the dev server.

If you encounter any issues during the build process, please debug according to the error log, or check the webpack configuration to see if there are any necessary configurations that have not been migrated to Rsbuild.

## 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 pull request 🤝.

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

---

# Source: https://rsbuild.dev/config/dev/write-to-disk.md

# dev.writeToDisk

* **Type:** `boolean | ((filename: string) => boolean)`
* **Default:** `false`

Controls whether the build output from development mode is written to disk.

:::tip
In development mode, Rsbuild stores the build outputs in memory on the dev server by default, rather than writing them to disk. This can reduce the overhead of fs operations. You can refer to [View Static Assets](/guide/basic/server.md#view-static-assets) to view all static assets generated in the current build.
:::

## Writing to disk

You can choose to write the build output to disk, which is usually used for inspecting the content of the build output or configuring proxy rules for static assets.

Simply set the `dev.writeToDisk` option to `true`:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    writeToDisk: true,
  },
};
```

:::tip
Setting `writeToDisk: true` is used for viewing the build output from development mode. It does not change the behavior of the dev server. When accessing files through a browser, the dev server will still read the file content from memory.
:::

## Matching specific files

You can also set `dev.writeToDisk` to a function to match only certain files. When the function returns `false`, the file will not be written; when it returns `true`, the file will be written to disk.

For example, to write files to disk while excluding hot-update temporary files:

```ts title="rsbuild.config.ts"
export default {
  dev: {
    writeToDisk: (file) => !file.includes('.hot-update.'),
  },
};
```