---
url: /guide/start/introduction.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.


# Introduction


Rspack (pronounced as 
`/'ɑrespæk/`
, 

) is a fast Rust-based bundler for the web.
 It modernizes the webpack API to
 enable seamless replacement of webpack while
 delivering lightning-fast build speeds.



## Why Rspack?

Rspack was initially created to solve performance problems encountered at ByteDance, a tech company that maintains many large monolithic app projects with complex bundling requirements. Production build times had grown to ten minutes or even half an hour in some cases, and cold start times could exceed several minutes. After experimenting with many bundlers and optimization ideas, a common set of requirements emerged:

- **Dev mode startup performance.** `npm run dev` is a command that developers may invoke many times per hour. Engineering productivity suffers if startup time exceeds 10-15 seconds.
- **Fast builds.** `npm run build` is used in CI/CD pipelines and directly impacts merging productivity and application delivery time. Large applications may spend 20-30 minutes running these pipelines, and bundling time is often a major contributor.
- **Flexible configuration.** From experimenting with various popular bundlers, we found that one-size-fits-all configurations encountered many problems when trying to accommodate real world projects. A major advantage of webpack is its flexibility and ease of accommodating customized requirements for each project. That same flexibility means legacy projects often face steep migration costs when moving away from webpack.
- **Production optimization capabilities.** All of the existing bundling solutions also had various limitations when optimizing for a production environment, such as insufficiently fine-grained code splitting. Rspack has an opportunity to rethink these optimizations from the ground up, leveraging Rust-specific features such as multithreading.

## Current status of Rspack

As of August 2024, we have released [Rspack 1.0](/blog/announcing-1-0.md), which we consider production-ready because it covers most of webpack's APIs and features.

Rspack is currently compatible with almost all loaders in the community. For the 50 most downloaded [webpack plugins](/plugins/community-plugin-compatibility.md), more than 85% can be used in Rspack or have an alternative.

:::tip Learn more

- See [Rspack blogs](/blog/index.md) for the latest updates on Rspack.
- See [Roadmap](/misc/planning/roadmap.md) for the future plans of Rspack.

:::

## Comparisons with other tools

### Compared with webpack

[webpack](https://webpack.js.org/) is perhaps the most mature modern bundler, with an active ecosystem, flexible configuration, and rich features.

- **Rust language efficiency:** webpack's competitors frequently challenge it based on performance, especially for larger projects. Rspack solves this using the Rust language, which was specifically designed to prioritize performance, topping benchmarks for both speed and memory management. Rust also provides many compiler safeguards to avoid common pitfalls of other native languages such as C++.

- **Highly parallelized architecture:** webpack is limited by JavaScript's weak support for multithreading. By contrast, Rspack's native code takes full advantage of modern multi-core CPUs.

- **Built-in implementations of essential bundling features:** webpack's hook system famously enables a vast landscape of loaders and plugins contributed by the community. Unfortunately these third-party packages can frequently lead to performance bottlenecks, sometimes because the authors did not have deep knowledge of webpack internals, and sometimes because the hook system by nature limits how algorithms can interact. Rspack provides built-in plugins for key features to improve performance.

- **Optimized hot module replacement (HMR):** No matter how large your project is, ensuring a great experience for HMR places even steeper demands on build times than ordinary bundling. Rspack incorporates a specialized incremental compilation strategy to address this requirement.

### Compared with Vite

If you are looking for an out-of-the-box development experience similar to Vite, we recommend using [Rsbuild](https://rsbuild.rs/), a build tool powered by Rspack. See [Rsbuild's comparison with Vite](https://rsbuild.rs/guide/start/#vite) to learn about their differences.

### Compared with esbuild

[esbuild](https://esbuild.github.io/) achieves very good performance by implementing nearly all operations in Golang except for some JavaScript plugins. However, esbuild's feature set is not as complete as webpack, for example missing HMR and [optimization.splitChunks](/config/optimization.md#optimizationsplitchunks) features.

### Compared with Turbopack

Turbopack is implemented in Rust like Rspack, but Turbopack started over with a redesigned architecture and configuration. This brings some benefits, but presents a steeper migration cost for projects that rely on webpack and its extensive ecosystem.

### Compared with Rollup

Rollup is built around ES modules and supports multiple output formats. Rspack covers a broader range of build scenarios, including ESM and CJS library outputs as well as application bundles, while continuously improving build performance and memory usage.

### Compared with Parcel

The overall architecture of Rspack shares many similarities with [Parcel](https://parceljs.org/). For example, both treat CSS assets as built-in supported modules and both support filter-based transformers. However, Parcel focuses more on out-of-the-box usability, while Rspack focuses more on providing flexible configuration for higher-level frameworks and tools. Parcel introduced features like the Unified Graph and built-in HTML support. Rspack also plans to support these features in the future.

## Online example

Try Rspack online with the [Rsbuild StackBlitz example](https://stackblitz.com/~/github.com/rstackjs/rsbuild-stackblitz-example).

## Next steps

Please read [Quick start](/guide/start/quick-start.md) to start using Rspack.

Welcome to the [GitHub Discussions](https://github.com/web-infra-dev/rspack/discussions) and [Discord](https://discord.gg/sYK4QjyZ4V) to communicate with us.



---
url: /guide/start/quick-start.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Quick start

Get up to speed quickly with a new Rspack based project.

- [Create a new project](#create-a-new-project): Use the CLI to create a brand-new Rspack or Rsbuild project.
- [Migrating from existing projects](#migrating-from-existing-projects): Migrate from a webpack-based project to Rspack.

## Ecosystem

As a low-level bundler, Rspack has a rich ecosystem that includes various frameworks, tools, and solutions. These ecosystem projects cover different aspects from frameworks to development tools, meeting diverse development needs across scenarios and providing an out-of-the-box experience.

See the [Ecosystem](/guide/start/ecosystem.md) page to explore these ecosystem projects.

## Environment preparation

Rspack supports using [Node.js](https://nodejs.org/), [Deno](https://deno.com/), or [Bun](https://bun.sh/) as the JavaScript runtime.

You can refer to the following installation guides and choose one 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

- Rspack v2 requires Node.js version 20.19+, 22.12+.
- Rspack v1 requires Node.js 18.12.0 or higher.

:::

:::details For unsupported platforms

If you are using a niche platform, Rspack may not provide native support for it. In this case, please manually install `@rspack/binding-wasm32-wasi` as a fallback. The Wasm build is compatible with most platforms.

Currently supported platforms:

- `darwin-arm64`
- `darwin-x64`
- `linux-arm64-gnu`
- `linux-arm64-musl`
- `linux-riscv64-gnu`
- `linux-riscv64-musl`
- `linux-ppc64-gnu`
- `linux-s390x-gnu`
- `linux-x64-gnu`
- `linux-x64-musl`
- `win32-arm64-msvc`
- `win32-ia32-msvc`
- `win32-x64-msvc`

:::

## Create a new project

### Using Rsbuild

Rsbuild is a high-performance build tool powered by Rspack and developed by the Rspack team. It provides a set of thoughtfully designed default build configs, offering an out-of-the-box development experience and can fully unleash the performance advantages of Rspack.

We recommend using [Rsbuild](https://rsbuild.rs/) to create new projects, simply run the following command:


```sh [npm]
npm create rsbuild@latest
```

```sh [yarn]
yarn create rsbuild
```

```sh [pnpm]
pnpm create rsbuild@latest
```

```sh [bun]
bun create rsbuild@latest
```

```sh [deno]
deno init --npm rsbuild@latest
```

> For more information, refer to [Rsbuild - Quick start](https://rsbuild.rs/guide/start/quick-start).

### Using Rspack CLI

Rspack CLI is a tool comparable to webpack CLI, offering the basic `serve` and `build` commands.

Run the following command to create an Rspack CLI project:


```sh [npm]
npm create rspack@latest
```

```sh [yarn]
yarn create rspack
```

```sh [pnpm]
pnpm create rspack@latest
```

```sh [bun]
bun create rspack@latest
```

```sh [deno]
deno init --npm rspack@latest
```

Then follow the prompts in your terminal.

### Non-interactive mode

[create-rspack](https://www.npmjs.com/package/create-rspack) and [create-rsbuild](https://www.npmjs.com/package/create-rsbuild) support a non-interactive mode through command-line options. This mode lets you skip all prompts and create a project directly, which is useful for scripts, CI, and coding agents.

For example, the following command creates a React app in the `my-app` directory:

```bash
# Rspack CLI
npx -y create-rspack --dir my-app --template react

# Rsbuild
npx -y create-rsbuild --dir my-app --template react

# Using abbreviations
npx -y create-rsbuild -d my-app -t react
```

## Manual installation

Start by creating a project directory and generating an npm \`package.json':

```bash
mkdir rspack-demo
cd rspack-demo
npm init -y
```

Then installing [@rspack/core](https://www.npmjs.com/package/@rspack/core) and [@rspack/cli](https://www.npmjs.com/package/@rspack/cli) as dev dependencies:


```sh [npm]
npm add @rspack/core @rspack/cli -D
```

```sh [yarn]
yarn add @rspack/core @rspack/cli -D
```

```sh [pnpm]
pnpm add @rspack/core @rspack/cli -D
```

```sh [bun]
bun add @rspack/core @rspack/cli -D
```

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

Update your build scripts to use Rspack CLI:

```js title="package.json"
{
  "scripts": {
    "dev": "rspack dev",
    "build": "rspack build",
    "preview": "rspack preview"
  }
}
```

Next, see [Configure Rspack](/config/index.md) to learn about how to configure Rspack.

## Migrating from existing projects

If you need to migrate from an existing project to Rspack, you can refer to the following guides:

- [Migrating from webpack to Rspack](/guide/migration/webpack.md)
- [Migrating from webpack to Rsbuild](https://rsbuild.rs/guide/migration/webpack)
- [Migrating from Create React App to Rsbuild](https://rsbuild.rs/guide/migration/cra)
- [Migrating from Vue CLI to Rsbuild](https://rsbuild.rs/guide/migration/vue-cli)
- [Migrating from Vite to Rsbuild](https://rsbuild.rs/guide/migration/vite)
- [Migrating from Tsup to Rslib](https://rslib.rs/guide/migration/tsup)
- [Migrating from Storybook](/guide/migration/storybook.md)

## Install canary version

When you need to test or verify the features of Rspack that are not yet released to the stable version, you may need to use the canary version.

The canary version of Rspack has a `-canary` suffix in the package scope. For example, the canary package name of `@rspack/core` is `@rspack-canary/core`. To use these versions, you can configure the overrides of the package manager (npm/yarn/pnpm/bun).

Here is an example of using pnpm overrides:

```json title="package.json"
{
  "pnpm": {
    "overrides": {
      "@rspack/core": "npm:@rspack-canary/core@latest"
    },
    "peerDependencyRules": {
      "allowAny": ["@rspack/*"]
    }
  }
}
```

Rspack community also provides [install-rspack](https://github.com/rstackjs/install-rspack) tool to easily install canary version:

```shell
npx install-rspack --version latest # Install the latest version
npx install-rspack --version canary # Install the canary version
npx install-rspack --version 1.0.0-canary-d614005-20250101082730 # Install the specified canary version
```



---
url: /guide/start/ecosystem.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Ecosystem

## Rstack

Rspack is part of Rstack, the fast, unified JavaScript toolchain for developers and agents.

### Rsbuild

Build tool

[Rsbuild](https://github.com/web-infra-dev/rsbuild) is a high-performance build tool powered by Rspack. It provides a set of thoughtfully designed default build configs, offering an out-of-the-box development experience and can fully unleash the performance advantages of Rspack.

### Rslib

Library development tool

[Rslib](https://github.com/web-infra-dev/rslib) is a library development tool based on Rsbuild, which reuses the carefully designed build configuration and plugin system of Rsbuild. It allows developers to create JavaScript libraries in a simple and intuitive way.

### Rspress

Static site generator

React

[Rspress](https://github.com/web-infra-dev/rspress) is a static site generator based on Rsbuild, React and MDX. It comes with a default documentation theme, and you can quickly build a documentation site with Rspress. You can also customize the theme to meet your personalized static site needs, such as blog sites, product homepages, etc.

### Rsdoctor

Build analyzer

[Rsdoctor](/guide/diagnostics/use-rsdoctor.md) is a build analyzer that can visually display the build process, such as compilation time, code changes before and after compilation, module reference relationships, duplicate modules, etc.

### Rstest

Testing framework

[Rstest](/guide/integrations/rstest.md) is a testing framework powered by Rspack. It delivers comprehensive, first-class support for the Rspack ecosystem, enabling seamless integration into existing Rspack-based projects.

### Rslint

Linter

[Rslint](https://github.com/web-infra-dev/rslint) is a high-performance JavaScript and TypeScript linter based on typescript-go. It offers strong compatibility with the ESLint and TypeScript-ESLint ecosystem, allowing for seamless replacement, and provides lightning-fast linting speeds.

## Community integrations

### Angular Rspack

Build tool

Angular

[Angular Rspack](https://nx.dev/docs/technologies/angular/angular-rspack) is a set of plugins and tools to make it easy and straightforward to build Angular applications with Rspack and Rsbuild.

### Docusaurus

Static site generator

React

[Docusaurus](https://docusaurus.io/) is a static site generator for building, deploying, and maintaining open source project websites easily.

Docusaurus supports Rspack as the bundler since v3.6, see [Docusaurus Faster](https://docusaurus.io/blog/releases/3.6#docusaurus-faster) for details.

### Modern.js

Web framework

React

[Modern.js](https://modernjs.dev/) is a Rsbuild-based progressive React framework that supports nested routes, SSR, and provides out-of-the-box CSS solutions such as styled components and Tailwind CSS.

### Meteor

Web framework

[Meteor](https://www.meteor.com/) is a full-stack JavaScript platform for developing modern web and mobile applications.

[Meteor 3.4](https://blog.meteor.com/meteor-3-4-is-out-rspack-integration-4x-faster-builds-8x-smaller-bundles-and-extended-bundler-36600fb45976) provides an Rspack integration with faster builds and smaller bundles.

### Next.js

Web framework

React

[Next.js](https://nextjs.org/) is a React framework for building full-stack web applications. You use React Components to build user interfaces, and Next.js for additional features and optimizations.

Rspack team and Next.js team have partnered to provide the `next-rspack` plugin. This plugin allows you to use Rspack as the bundler for Next.js, see [Next.js guide](/guide/integrations/next.md) for details.

### Nuxt

Web framework

Vue

[Nuxt](https://nuxt.com/) is a free and open-source framework with an intuitive and extendable way to create type-safe, performant and production-grade full-stack web applications and websites with Vue.js.

Nuxt v3.14 introduces a new first-class Nuxt builder for Rspack, see [Nuxt 3.14](https://nuxt.com/blog/v3-14) for details.

### Nx

Build system

Monorepo

[Nx](https://nx.dev/) is a powerful open-source build system that provides tools and techniques for enhancing developer productivity, optimizing CI performance, and maintaining code quality.

Rspack team and Nx team have collaborated to provide the [Rspack Nx plugin](https://nx.dev/nx-api/rspack). This plugin contains executors, generators, and utilities for managing Rspack projects in an Nx Workspace.

### Rspeedy

Build tool

Lynx

[Rspeedy](https://lynxjs.org/rspeedy/) is an Rspack-based build tool designed specifically for Lynx applications. [Lynx](https://lynxjs.org/) is a family of technologies empowering developers to use their existing web skills to create truly native UIs for both mobile and web from a single codebase.

### Re.Pack

Build tool

React Native

[Re.Pack](https://github.com/callstack/repack) is a build tool for building your React Native application.

Re.Pack v5 uses Rspack and React Native community CLI's plugin system to allow you to bundle your application using Rspack and easily switch from Metro.

### Remotion

Video framework

React

[Remotion](https://www.remotion.dev/) is a React-based framework for creating videos programmatically.

The [`@remotion/bundler`](https://www.remotion.dev/docs/bundle#rspack) package can use Rspack to bundle Remotion projects.

### Shakapacker

Build tool

Rails

[Shakapacker](https://shakapacker.com/) handles compiling rails frontend assets. See [Rspack setup Docs](https://github.com/shakacode/shakapacker/blob/main/docs/rspack.md)

### Storybook

UI development

[Storybook Rsbuild](https://storybook.rsbuild.rs/) allows you to use Rsbuild as the build tool for Storybook, and provides UI framework integrations like React and Vue.

### TanStack Router

Router

React

[TanStack Router](https://tanstack.com/router/latest) is a type-safe router for building React applications with features like nested routes, route-level data loading, and search params APIs.

You can integrate TanStack Router with Rspack through the [Rspack plugin](https://tanstack.com/router/latest/docs/installation/with-rspack).

### TanStack Start

Web framework

React

Solid

[TanStack Start](https://tanstack.com/start/latest) is a full-stack framework powered by TanStack Router for React and Solid.

TanStack Start provides official support for Rsbuild, allowing you to use Rsbuild to build full-stack web applications. See [TanStack Start Adds First-Class Rsbuild Support](https://tanstack.com/blog/start-adds-rsbuild-support) for details.

## More

Visit [awesome-rstack](https://github.com/rstackjs/awesome-rstack) to discover more projects within the Rspack ecosystem.



---
url: /guide/start/ai.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# AI

To help AI better understand Rspack's features, configuration, and best practices so it can provide more accurate assistance during day-to-day development and troubleshooting, Rspack provides the following capabilities:

- [Agent Skills](#agent-skills)
- [llms.txt](#llmstxt)
- [Markdown docs](#markdown-docs)
- [AGENTS.md](#agentsmd)

## Agent Skills

Agent Skills are domain-specific knowledge packs that can be installed into Agents, enabling them to give more accurate and professional suggestions or perform actions in specific scenarios.

In the [rstackjs/agent-skills](https://github.com/rstackjs/agent-skills) repository, there are many skills for the Rstack ecosystem. The skills related to Rspack include:

- [rspack-best-practices](https://github.com/rstackjs/agent-skills#rspack-best-practices): Best practices for Rspack.
- [rspack-v2-upgrade](https://github.com/rstackjs/agent-skills#rspack-v2-upgrade): Upgrade an existing Rspack 1.x project to v2.
- [rspack-debugging](https://github.com/rstackjs/agent-skills#rspack-debugging): Debug crashes or deadlocks/hangs in the Rspack build process using LLDB.
- [rspack-tracing](https://github.com/rstackjs/agent-skills#rspack-tracing): Diagnose Rspack build failures or performance bottlenecks.

In Coding Agents that support skills, you can use the [skills](https://www.npmjs.com/package/skills) package to install a specific skill with the following command:


```sh [npx]
npx skills add rstackjs/agent-skills --skill rspack-best-practices
```

```sh [yarn]
yarn dlx skills add rstackjs/agent-skills --skill rspack-best-practices
```

```sh [pnpm]
pnpm dlx skills add rstackjs/agent-skills --skill rspack-best-practices
```

```sh [bunx]
bunx skills add rstackjs/agent-skills --skill rspack-best-practices
```

```sh [deno]
deno run -A npm:skills add rstackjs/agent-skills --skill rspack-best-practices
```

After installation, simply use natural language prompts to trigger the skill, for example:

```
Help me migrate this Rspack 1.x project to v2
```

## llms.txt

[llms.txt](https://llmstxt.org/) is a standard that helps LLMs discover and use project documentation. Rspack follows this standard and publishes the following two files:

- [llms.txt](https://rspack.rs/llms.txt): A structured index file containing the titles, links, and brief descriptions of all documentation pages.

```
https://rspack.rs/llms.txt
```

- [llms-full.txt](https://rspack.rs/llms-full.txt): A full-content file that concatenates the complete content of every documentation page into a single file.

```
https://rspack.rs/llms-full.txt
```

You can choose the file that best fits your use case:

- `llms.txt` is smaller and consumes fewer tokens, making it suitable for AI to fetch specific pages on demand.
- `llms-full.txt` contains the complete documentation content, so AI doesn't need to follow individual links — ideal when you need AI to have a comprehensive understanding of Rspack, though it consumes more tokens and is best used with AI tools that support large context windows.

## Markdown docs

Every Rspack documentation page has a corresponding `.md` plain-text version that can be provided directly to AI. On any doc page, you can click “Copy Markdown” or “Copy Markdown Link” under the title to get the Markdown content or link.

```
https://rspack.rs/guide/start/introduction.md
```

Providing the Markdown link or content allows AI to focus on a specific chapter, which is useful for targeted troubleshooting or looking up a particular topic.

## AGENTS.md

When you create a new project with [create-rspack](https://www.npmjs.com/package/create-rspack), the generated project includes an `AGENTS.md` file. This file follows the [AGENTS.md](https://agents.md/) specification and provides key project information to Agents.

Example `AGENTS.md` content:

```markdown wrapCode
# AGENTS.md

## Commands

- `npm run dev` - Start the dev server
- `npm run build` - Build the app for production
- `npm run preview` - Preview the production build locally

## Docs

- Rspack: https://rspack.rs/llms.txt
```

You can also customize it for your project, adding more details about the project structure, overall architecture, and other relevant information so Agents can better understand your project.

::: tip

If you are using Claude Code, you can create a `CLAUDE.md` file and reference the `AGENTS.md` file in it.

```markdown title="CLAUDE.md"
@AGENTS.md
```

:::



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

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Plugins

If [loaders](/guide/features/loader.md) are the workhorse for file transformations, then plugins are the workhorse for the overall Rspack build process. Most of Rspack's native implementations rely on the Rust side of the plugin system.

For Node.js users, you don't need to worry about interoperability issues with Node.js and Rust, because Rspack takes care of those details for you automatically. You can just focus on how to use the plugins.

## Plugin usage

Rspack provides the [plugins](/config/plugins.md) configuration, which is used to register a set of Rspack or webpack plugins to customize the build process.

Here is an example of using the [webpack-bundle-analyzer](https://github.com/webpack/webpack-bundle-analyzer) in Rspack configuration:


**ESM**

```js title="rspack.config.mjs"
import { BundleAnalyzerPlugin } from 'webpack-bundle-analyzer';

export default {
  plugins: [
    new BundleAnalyzerPlugin({
      // options
    }),
  ],
};
```


**CJS**

```js title="rspack.config.cjs"
const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');

module.exports = {
  plugins: [
    new BundleAnalyzerPlugin({
      // options
    }),
  ],
};
```


If you're looking for more Rspack plugins, have a look at the great list of [supported plugins](/plugins/index.md).

You can also refer to [Community plugin compatibility](/plugins/community-plugin-compatibility.md) for the list of webpack plugins that have passed Rspack compatibility tests.

## Other plugins

### 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 Rspack, typically by importing the `/rspack` subpath of the plugin and registering it through `plugins`.

Here is an example of using [unplugin-vue-components](https://www.npmjs.com/package/unplugin-vue-components):


**ESM**

```js title="rspack.config.mjs"
import Components from 'unplugin-vue-components/rspack';

export default {
  plugins: [
    Components({
      // options
    }),
  ],
};
```


**CJS**

```js title="rspack.config.cjs"
const Components = require('unplugin-vue-components/rspack');

module.exports = {
  plugins: [
    Components.default({
      // options
    }),
  ],
};
```


### SWC plugins

In the built-in [swc-loader](/guide/features/builtin-swc-loader.md) of Rspack, you can use SWC's Wasm plugins, see [jsc.experimental.plugins](/guide/features/builtin-swc-loader.md#jscexperimentalplugins).

### Rsbuild plugins

[Rsbuild](https://rsbuild.rs) is a build tool based on Rspack, and Rsbuild has its own plugin system.

Please note that you cannot use Rsbuild plugins in Rspack, because Rspack is a more low-level tool, but you can use Rspack plugins in Rsbuild.

Here is a comparison table for the plugins that can be used in Rspack and Rsbuild:

| Tool used | Rspack plugins | webpack plugins | Rsbuild plugins | Unplugins | SWC plugins |
| --------- | -------------- | --------------- | --------------- | --------- | ----------- |
| Rspack    | ✅              | ✅               | ❌               | ✅         | ✅           |
| Rsbuild   | ✅              | ✅               | ✅               | ✅         | ✅           |

> Please refer to the [Rsbuild plugin documentation](https://rsbuild.rs/plugins/list/index) for more information.

## Write a plugin

### Plugin structure

As a plugin author, the structure of a plugin is very simple: just implement an `apply` method that accepts a `Compiler` instance. It will be called when the Rspack plugin is initialized. The detailed API can be found in the [Plugin API](/api/plugin-api/index.md).


**ESM**

```js title="MyPlugin.mjs"
const PLUGIN_NAME = 'MyPlugin';

export class MyPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
      console.log('The Rspack build process is starting!');
    });
  }
}
```


**CJS**

```js title="MyPlugin.cjs"
const PLUGIN_NAME = 'MyPlugin';

class MyPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
      console.log('The Rspack build process is starting!');
    });
  }
}

module.exports = MyPlugin;
```


### Write with TypeScript

If you use TypeScript to write Rspack plugins, you can import `Compiler` and `RspackPluginInstance` to declare the types of your plugins:

```ts title="MyPlugin.ts"
import type { Compiler, RspackPluginInstance } from '@rspack/core';

const PLUGIN_NAME = 'MyPlugin';

export class MyPlugin implements RspackPluginInstance {
  apply(compiler: Compiler) {
    compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
      console.log('The Rspack build process is starting!');
    });
  }
}
```

## Publishing plugins

### Declaring peer dependencies

When publishing a plugin as an npm package, declare the bundler packages it integrates with as optional peer dependencies. This documents the supported host bundlers without requiring users who only use one bundler to install the other.

If the plugin is designed only for Rspack, declare `@rspack/core` as an optional peer dependency. Set the version range according to the APIs the plugin relies on. For example, if the plugin uses an API introduced in a newer Rspack release, set that release as the minimum supported version.

```json title="package.json"
{
  "peerDependencies": {
    "@rspack/core": "^1.0.0 || ^2.0.0"
  },
  "peerDependenciesMeta": {
    "@rspack/core": {
      "optional": true
    }
  }
}
```

If the plugin is designed to work with both Rspack and webpack, declare both `@rspack/core` and `webpack` as optional peer dependencies:

```json title="package.json"
{
  "peerDependencies": {
    "@rspack/core": "^1.0.0 || ^2.0.0",
    "webpack": "^5.0.0"
  },
  "peerDependenciesMeta": {
    "@rspack/core": {
      "optional": true
    },
    "webpack": {
      "optional": true
    }
  }
}
```



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

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Loader

Rspack has built-in support for JavaScript, CSS, JSON, and static assets modules.

A loader is a transformer that converts various types of modules into Rspack supported types. By using different kinds of loaders, you can extend Rspack to process additional module types, including JSX, Markdown, Sass, Less, and more.

When Rspack bundles a module, it first pre-processes the module through loaders, transforming it into a Rspack supported module type, and then post-processes the module according to the [rules\[\].type](/config/module-rules.md#rulestype).

## Compatibility with webpack loaders

Rspack allows you to use most webpack loaders in the community. See [awesome-rstack - Rspack loaders](https://github.com/rstackjs/awesome-rstack?tab=readme-ov-file#rspack-loaders) to find loaders provided by the community.

If you find an unsupported loader, please feel free to communicate with us through [GitHub Issues](https://github.com/web-infra-dev/rspack/issues).

## Writing loaders

Refer to [Writing loaders](/api/loader-api/writing-loaders.md) to learn how to develop a loader.

## Example

### Using Less

You can use [less-loader](https://github.com/webpack/less-loader) to transform the contents of the `.less` file accordingly.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          {
            loader: 'less-loader',
          },
        ],
        type: 'css',
      },
    ],
  },
};
```

[less-loader](https://github.com/webpack/less-loader) can transform Less files to Rspack-supported CSS module types, so you can set the type to `'css'` to instruct Rspack to use the CSS handling method that is natively supported for post-processing.

### Combining multiple loaders

You can chain multiple loaders for a particular [Rule](/config/module-rules.md#rule) match, with the loaders executed in right-to-left order.

For example, you can use [less-loader](https://github.com/webpack/less-loader) to do the transformation between Less to CSS types and [postcss-loader](https://github.com/webpack/postcss-loader) for the transformed source code to perform a secondary transformation, which will then get passed to Rspack's CSS post-processor for further processing.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          {
            loader: 'postcss-loader',
          },
          {
            loader: 'less-loader',
          },
        ],
        type: 'css',
      },
    ],
  },
};
```

### Passing configuration items

You can use [rules\[\].use](/config/module-rules.md#rulesuse) to pass the relevant configuration to the loader, for example:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                // ...
              },
            },
          },
        ],
        type: 'css',
      },
    ],
  },
};
```

### Using a custom loader

You can use a custom loader with Rspack. In the example below, we'll use the loader API to write a simple banner-loader.

The purpose of the banner-loader is to prepend a banner comment at the header of each module, such as a license notice:

```js
/**
 * MIT Licensed
 * Copyright (c) 2022-present ByteDance, Inc. and its affiliates.
 * https://github.com/web-infra-dev/rspack/blob/main/LICENSE
 */
```

Create a new `banner-loader.js` file under the root of the project with the following content:

```js title="banner-loader.js"
const BANNER = `/**
 * MIT Licensed
 * Copyright (c) 2022-present ByteDance, Inc. and its affiliates.
 * https://github.com/web-infra-dev/rspack/blob/main/LICENSE
 */`;

module.exports = function (content) {
  return `${BANNER}\n${content}`;
};
```

The first input to this loader is the content of the file, allowing us to process the file content and return the transformed result. The script file must be imported using CommonJS `require()`.

For example, to add a banner to all `*.js` files, the configuration might look like this:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        loader: './banner-loader.js',
      },
    ],
  },
};
```

For details, you can refer to [loader-api](/api/loader-api/index.md)

### Using built-in loader

Built-in Loaders offer superior performance compared to JS Loaders, without sacrificing the composability of JS Loaders. The following are some built-in loaders.

- [builtin:swc-loader](/guide/features/builtin-swc-loader.md)
- [builtin:lightningcss-loader](/guide/features/builtin-lightningcss-loader.md)



---
url: /guide/features/builtin-swc-loader.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# SWC loader

[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.

Rspack provides a built-in loader for SWC, which is the Rust version of [swc-loader](https://github.com/swc-project/pkgs/tree/main/packages/swc-loader), aiming to deliver better performance. The loader's [options](https://swc.rs/docs/configuration/compilation) is aligned with the JS version of `swc-loader`.

## Example

If you need to use `builtin:swc-loader` in your project, configure it as follows:

### TypeScript transpilation

To transpile `.ts` files:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|ts)$/,
        exclude: [/node_modules/],
        loader: 'builtin:swc-loader',
        options: {
          detectSyntax: 'auto',
        },
      },
    ],
  },
};
```

### JSX transpilation

To transpile React's `.jsx` files:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              transform: {
                react: {
                  pragma: 'React.createElement',
                  pragmaFrag: 'React.Fragment',
                  throwIfNamespace: true,
                  development: false,
                },
              },
            },
          },
        },
      },
    ],
  },
};
```

### Syntax lowering

SWC provides [jsc.target](https://swc.rs/docs/configuration/compilation#jsctarget) and [env.targets](https://swc.rs/docs/configuration/compilation#envtargets) to specify the target of JavaScript syntax lowering.

:::tip Default target from Rspack
If neither `env.targets` nor `jsc.target` is configured, `builtin:swc-loader` will automatically derive a default target from Rspack's [`target`](/config/target.md) configuration.

This means you can rely on your Rspack `target` configuration without manually specifying the same targets in the loader options.
:::

#### jsc.target

[jsc.target](https://swc.rs/docs/configuration/compilation#jsctarget) is used to specify the ECMA version, such as `es5`, `es2015`, `es2016`, etc.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              target: 'es2015',
            },
            // ...other options
          },
        },
      },
    ],
  },
};
```

#### env.targets

[env.targets](https://swc.rs/docs/configuration/compilation#envtargets) uses the [browserslist](https://github.com/browserslist/browserslist) syntax to specify browser range, for example:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            env: {
              targets: [
                'chrome >= 87',
                'edge >= 88',
                'firefox >= 78',
                'safari >= 14',
              ],
            },
            // ...other options
          },
        },
      },
    ],
  },
};
```

:::tip
`jsc.target` and `env.targets` cannot be configured at the same time, choose one according to your needs.
:::

### Polyfill injection

When using higher versions of JavaScript syntax and APIs in your project, to ensure that the compiled code can run in lower version browsers, you will typically need to perform two parts of the downgrade: syntax downgrading and polyfill injection.

SWC supports injecting [core-js](https://github.com/zloirock/core-js) as an API polyfill, which can be configured using [env.mode](https://swc.rs/docs/configuration/compilation#envmode) and [env.coreJs](https://swc.rs/docs/configuration/compilation#envcorejs):

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules[\\/]core-js/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            env: {
              mode: 'usage',
              coreJs: '3.26.1',
              targets: [
                'chrome >= 87',
                'edge >= 88',
                'firefox >= 78',
                'safari >= 14',
              ],
            },
            isModule: 'unknown',
            // ...other options
          },
        },
      },
    ],
  },
};
```

Note:

- Make sure to [exclude](/config/module-rules.md#rulesexclude) the `core-js` package, as `core-js` will not work properly if compiled by SWC.
- When importing non-ES modules, add [isModule: 'unknown'](https://swc.rs/docs/configuration/compilation#ismodule) to allow SWC to correctly identify the module type.

## Type declaration

You can enable type hints using the `SwcLoaderOptions` type exported by `@rspack/core`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: {
          loader: 'builtin:swc-loader',
          /** @type {import('@rspack/core').SwcLoaderOptions} */
          options: {
            // some options
          },
        },
      },
    ],
  },
};
```

- `rspack.config.ts`:

```ts
import type { SwcLoaderOptions } from '@rspack/core';

export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            // some options
          } satisfies SwcLoaderOptions,
        },
      },
    ],
  },
};
```

## Options

The following is an introduction to some SWC configurations and Rspack specific configurations. Please refer to the [SWC Configurations](https://swc.rs/docs/configuration/swcrc) for the complete options.

### detectSyntax


[Added in v2.0.0](https://github.com/web-infra-dev/rspack/releases/tag/v2.0.0)

- Type: `false | "auto"`
- Default: `false`

When set to `"auto"`, `builtin:swc-loader` infers `jsc.parser` from the resource extension. This is useful when one rule needs to handle mixed module types such as `.js`, `.jsx`, `.ts`, and `.tsx`.

Inference rules:

- `.js`, `.jsx`, `.mjs`, `.cjs` -> `{ syntax: "ecmascript", jsx: true }`
- `.ts`, `.mts`, `.cts` -> `{ syntax: "typescript", tsx: false }`
- `.tsx` -> `{ syntax: "typescript", tsx: true }`
- Resources without a recognizable extension -> `{ syntax: "typescript", tsx: true }`

> If `jsc.parser.syntax` is explicitly provided, `detectSyntax` does not infer syntax.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
          },
        },
      },
    ],
  },
};
```

### jsc.experimental.plugins


Stability: Experimental

:::warning
The Wasm plugin is deeply coupled with the version of SWC, you need to choose a Wasm plugin that is compatible with the corresponding version of SWC in order to function normally.

See [FAQ - SWC Plugin Version Unmatched](/errors/swc-plugin-version.md) for more details.
:::

Rspack supports load Wasm plugin in `builtin:swc-loader`, you can specify the plugin name like

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              experimental: {
                plugins: [
                  [
                    '@swc/plugin-remove-console',
                    {
                      exclude: ['error'],
                    },
                  ],
                ],
              },
            },
          },
        },
      },
    ],
  },
};
```

this is an [example](https://github.com/rstackjs/rstack-examples/blob/d4b8aaef9915ed0f540edbe504217c3d1afe8989/rspack/builtin-swc-loader/rspack.config.js#L45) of Wasm plugin usage.

#### Set cache root

When you use SWC's Wasm plugin, SWC will generate cache files in the `.swc` directory of the current project by default. If you want to adjust this directory, you can modify the `cacheRoot` configuration, such as:

```js title="rspack.config.mjs"
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              experimental: {
                cacheRoot: path.join(__dirname, './node_modules/.cache/swc'),
              },
            },
          },
        },
      },
    ],
  },
};
```

### transformImport

Ported from [babel-plugin-import](https://github.com/umijs/babel-plugin-import), configurations are basically the same.

Function can't be used in configurations, such as `customName`, `customStyleName`, they will cause some performance overhead as these functions must be called from `Rust` , inspired by [modularize\_imports](https://crates.io/crates/modularize_imports), some simple function can be replaced by template string instead. Therefore, the function type configuration such as `customName`, `customStyleName` can be passed in strings as templates to replace functions and improve performance.

For example:

```ts
import { MyButton as Btn } from 'foo';
```

Apply following configurations:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        loader: 'builtin:swc-loader',
        options: {
          transformImport: [
            {
              libraryName: 'foo',
              customName: 'foo/es/{{ member }}',
            },
          ],
        },
      },
    ],
  },
};
```

`{{ member }}` will be replaced by the imported specifier:

```ts
import Btn from 'foo/es/MyButton';
```

Template `customName: 'foo/es/{{ member }}'` is the same as ``customName: (member) => `foo/es/${member}` ``, but template string has no performance overhead of Node-API.

There are some useful builtin helpers available in template string, take the above import statement as an example:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        loader: 'builtin:swc-loader',
        options: {
          transformImport: [
            {
              libraryName: 'foo',
              customName: 'foo/es/{{ kebabCase member }}',
            },
          ],
        },
      },
    ],
  },
};
```

Transformed to:

```ts
import Btn from 'foo/es/my-button';
```

In addition to `kebabCase`, there are `camelCase`, `snakeCase`, `upperCase`, `lowerCase` and `legacyKebabCase`/`legacySnakeCase` can be used as well.

The `legacyKebabCase`/`legacySnakeCase` works as babel-plugin-import versions before 1.13.7.

You can check the document of [babel-plugin-import](https://www.npmjs.com/package/babel-plugin-import) for other configurations.

Taking the classic 4.x version of [ant-design](https://4x.ant.design/) as an example, we only need to configure it as follows:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        loader: 'builtin:swc-loader',
        options: {
          transformImport: [
            {
              libraryName: 'antd',
              style: '{{member}}/style/index.css',
            },
          ],
        },
      },
    ],
  },
};
```

The above configuration will transform `import { Button } from 'antd'`; to:

```ts
import Button from 'antd/es/button';
import 'antd/es/button/style/index.css';
```

Then you can see the style file is automatically imported and applied on the page.

Of course, if you have already configured support for `less`, you can simply use the following configuration:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        loader: 'builtin:swc-loader',
        options: {
          transformImport: [
            {
              libraryName: 'antd',
              style: true,
            },
          ],
        },
      },
    ],
  },
};
```

The above configuration will transform `import { Button } from 'antd';` to:

```ts
import Button from 'antd/es/button';
import 'antd/es/button/style';
```

### rspackExperiments

Experimental features provided by rspack.

:::warning
`rspackExperiments.import` has been moved to the top-level [`transformImport`](#transformimport) option. The `rspackExperiments.import` option is deprecated and will be removed in a future version.
:::

### collectTypeScriptInfo


[Added in v1.7.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.7.0)

Collects information from TypeScript's AST for consumption by subsequent Rspack processes, providing better TypeScript development experience and smaller output bundle size.

To ensure the accuracy of the collected information, users must ensure that subsequent Normal Loaders after `builtin:swc-loader` do not modify the Abstract Syntax Tree (AST) corresponding to the collected information. This precaution is necessary to prevent discrepancies between the collected information and the actual code.

#### collectTypeScriptInfo.typeExports


[Added in v1.7.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.7.0)

- **Type:** `boolean`
- **Default:** `false`

Whether to collect type exports information for [`typeReexportsPresence`](/config/module-parser.md#javascripttypereexportspresence). This is used to check type exports of submodules when running in `'tolerant'` mode.

Please refer to [type reexports presence example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/type-reexports-presence) for more details.

#### collectTypeScriptInfo.exportedEnum


[Added in v1.7.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.7.0)

- **Type:** `boolean | 'const-only'`
- **Default:** `false`

Whether to collect information about exported `enum`s, so Rspack can perform cross-module inline optimization for enums.

- `true` will collect all `enum` information, including `const enum`s and regular `enum`s.
- `false` will not collect any `enum` information.
- `'const-only'` will gather only `const enum`s, then only perform cross-module inline optimization for `const enum`.

```js title="rspack.config.mjs"
const isProduction = process.env.NODE_ENV === 'production';

export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|ts)$/,
        use: [
          {
            loader: 'builtin:swc-loader',
            options: {
              detectSyntax: 'auto',
              collectTypeScriptInfo: {
                exportedEnum: isProduction,
              },
            },
          },
        ],
      },
    ],
  },
};
```

Since this feature relies on module export usage information ([optimization.usedExports](/config/optimization.md#optimizationusedexports)), it is recommended to enable it only when `mode = "production"`.

Please refer to [inline enum example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/inline-enum) for more details.

:::info
By default, Rspack will perform inline optimization for all enums. To inline only `const enum`, use `'const-only'` and configure `transform.tsEnumIsMutable = true`. For detailed examples, refer to: [inline const enum example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/inline-const-enum)
:::



---
url: /guide/features/builtin-lightningcss-loader.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Lightning CSS loader

[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 also provides a better compression ratio.

Rspack provides a built-in `builtin:lightningcss-loader`, which is based on Lightning CSS to transform CSS. It can replace the [postcss-loader](https://github.com/postcss/postcss-loader) and [autoprefixer](https://github.com/postcss/autoprefixer) for CSS syntax downgrading, prefixing, and other functionalities, offering better performance.

::: warning
Please note that Lightning CSS strictly requires standards-compliant CSS input. When non-standard CSS is processed by the `builtin:lightningcss-loader`, styles may be ignored or produce unexpected results (Undefined Behavior). To ensure that styles are correctly applied, avoid using non-standard CSS syntax or browser-specific proprietary syntax, and instead use standard CSS writing practices that conform to W3C specifications.
:::

## Example

To use `builtin:lightningcss-loader` in your project, you need to configure it as follows.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'builtin:lightningcss-loader',
            options: {
              targets: 'ie 10',
            },
          },
          // ... other loaders
        ],
      },
    ],
  },
};
```

## Type declarations

You can use the `LightningcssLoaderOptions` type exported by `@rspack/core` to enable type hints:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'builtin:lightningcss-loader',
            /** @type {import('@rspack/core').LightningcssLoaderOptions} */
            options: {
              targets: 'ie 10',
            },
          },
          // ... other loaders
        ],
      },
    ],
  },
};
```

## Options

Below are the configurations supported by `builtin:lightningcss-loader`. For detailed configuration, please refer to [lightningcss document](https://lightningcss.dev/transpilation.html).

```ts
type LightningcssFeatureOptions = {
  nesting?: boolean;
  notSelectorList?: boolean;
  dirSelector?: boolean;
  langSelectorList?: boolean;
  isSelector?: boolean;
  textDecorationThicknessPercent?: boolean;
  mediaIntervalSyntax?: boolean;
  mediaRangeSyntax?: boolean;
  customMediaQueries?: boolean;
  clampFunction?: boolean;
  colorFunction?: boolean;
  oklabColors?: boolean;
  labColors?: boolean;
  p3Colors?: boolean;
  hexAlphaColors?: boolean;
  spaceSeparatedColorNotation?: boolean;
  fontFamilySystemUi?: boolean;
  doublePositionGradients?: boolean;
  vendorPrefixes?: boolean;
  logicalProperties?: boolean;
  selectors?: boolean;
  mediaQueries?: boolean;
  color?: boolean;
};

type Targets = {
  android?: string;
  chrome?: string;
  edge?: string;
  firefox?: string;
  ie?: string;
  ios_saf?: string;
  opera?: string;
  safari?: string;
  samsung?: string;
};

type LightningcssLoaderOptions = {
  minify?: boolean;
  errorRecovery?: boolean;
  targets?: string[] | string | Targets;
  include?: LightningcssFeatureOptions;
  exclude?: LightningcssFeatureOptions;
  drafts?: Drafts;
  nonStandard?: NonStandard;
  pseudoClasses?: PseudoClasses;
  unusedSymbols?: Set<String>;
};
```

### targets

- **Type:** `string | string[] | Targets`

Browserslist query string or a `Targets` object specifying browser versions.

:::tip Default targets from Rspack
If `targets` is not configured, `builtin:lightningcss-loader` will automatically derive a default targets from Rspack's [`target`](/config/target.md) configuration when using browserslist-related targets (e.g., `browserslist` or `browserslist:modern`). Since Lightning CSS only supports browser-related targets, non-browser targets like `node` will not provide default targets for this loader.

This means you can rely on your Rspack `target` configuration without manually specifying the same targets in the loader options.
:::

Here are some examples of setting targets.

- Setting a browserslist query string:

```js
const loader = {
  loader: 'builtin:lightningcss-loader',
  /** @type {import('@rspack/core').LightningcssLoaderOptions} */
  options: {
    targets: 'ie 10',
  },
};
```

- Setting an array of browserslist query strings:

```js
const loader = {
  loader: 'builtin:lightningcss-loader',
  /** @type {import('@rspack/core').LightningcssLoaderOptions} */
  options: {
    targets: ['chrome >= 87', 'edge >= 88', '> 0.5%'],
  },
};
```

- Setting a `Targets` object:

```js
const loader = {
  loader: 'builtin:lightningcss-loader',
  /** @type {import('@rspack/core').LightningcssLoaderOptions} */
  options: {
    targets: {
      chrome: '95.0',
      safari: '13.2',
    },
  },
};
```

### errorRecovery

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

Control how Lightning CSS handles invalid CSS syntax.

By default, this option is enabled, meaning that when invalid CSS rules or declarations are parsed, Lightning CSS will skip them and emit warnings, while omitting them from the final output without interrupting the compilation process.

#### Ignoring warnings

If you confirm that these warnings can be ignored, you can use [ignoreWarnings](/config/other-options.md#ignorewarnings) to filter out the warnings from LightningCSS.

For example, ignore all warnings:

```js title="rspack.config.mjs"
export default {
  ignoreWarnings: [
    (warning) => /LightningCSS parse warning/.test(warning.message),
  ],
};
```

You can also use regular expressions to ignore specific warnings.

#### Disabling `errorRecovery`

If you set `errorRecovery` to `false`, Lightning CSS will throw a compilation error and interrupt the build process when parsing any invalid CSS syntax:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'builtin:lightningcss-loader',
            /** @type {import('@rspack/core').LightningcssLoaderOptions} */
            options: {
              errorRecovery: false,
            },
          },
        ],
      },
    ],
  },
};
```



---
url: /guide/features/dev-server.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Dev server

The `rspack dev` and `rspack serve` commands run a local development server through [@rspack/dev-server](https://npmjs.com/package/@rspack/dev-server). It provides hot module replacement (HMR), static file serving, proxying, and related development features.

## Install dev server

`@rspack/dev-server` is an optional peer dependency of `@rspack/cli`.

Install it before using `rspack dev`, `rspack serve`, or `rspack preview`:


```sh [npm]
npm add @rspack/dev-server -D
```

```sh [yarn]
yarn add @rspack/dev-server -D
```

```sh [pnpm]
pnpm add @rspack/dev-server -D
```

```sh [bun]
bun add @rspack/dev-server -D
```

```sh [deno]
deno add npm:@rspack/dev-server -D
```

## HMR

By default, Rspack enables HMR in dev mode. You can disable HMR by configuring the `devServer.hot` option in Rspack configuration.

```js title="rspack.config.mjs"
export default {
  devServer: {
    hot: false,
  },
};
```

:::warning
Do not include `[hash]` or `[contenthash]` in [output.cssFilename](/config/output.md#outputcssfilename), otherwise CSS HMR may not work.
:::

## Proxy

The dev server includes proxy support. Configure the `devServer.proxy` option to proxy matching requests. This feature is powered by [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware). For example, you can proxy `/api` to `http://localhost:3000` as follows:

```js title="rspack.config.mjs"
export default {
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'http://localhost:3000',
        changeOrigin: true,
      },
    ],
  },
};
```

For more devServer configuration options, please refer to [devServer](/config/dev-server.md).



---
url: /guide/features/asset-module.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Asset modules

Rspack has built-in support for assets (e.g. images, fonts, videos, etc.), which means you don't need any loader to process them.

Unlike other module types, assets usually stand alone, so they are generated at the granularity of a module.

:::tip Module and Chunk

Other module types, such as JavaScript modules, are usually bundled into one or more chunks for final bundle generation. In the case of asset modules, it is almost impossible to be bundled, so they usually exist independently. This is one of the most straightforward reasons why it is called a "asset module."

:::

## Supported asset module types

- **`'asset/inline'`**: Converts an asset to a DataURI, using Base64 encoding, no encoding configuration is supported at this time.
- **`'asset/resource'`**: Converts an asset to a separate file and exports the URL address.
- **`'asset'`**:
  - Automatically selects `'asset/inline'` or `'asset/resource'` depending on the size of the asset, depending on the configuration
  - By default, the `'asset/inline'` mechanism is applied if the asset size is less than or equal to 8096 bytes, otherwise the `'asset/resource'` mechanism is used.
- **`'asset/source'`**: Converts and exports the asset file as a raw string.
- **`'asset/bytes'`**: Converts and exports the asset file as a binary data `Uint8Array`.

## Example

### Using `type: 'asset'`

Using `type: 'asset'` to automatically select a mechanism based on conditions:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.png$/,
        type: 'asset',
      },
    ],
  },
};
```

By default, the `'asset/inline'` mechanism is applied if the asset size is less than or equal to 8096 bytes, otherwise the `'asset/resource'` policy is used.

If you wish to modify this behavior, you can use [`module.parser.asset.dataUrlCondition`](/config/module-parser.md#asset) to modify the global configuration, or use [`rules[].parser.dataUrlCondition`](/config/module-parser.md#assetdataurlcondition) to configure it separately for a specific eligible module.

### Replacing `url-loader`

Replacing `url-loader` with `type: 'asset/inline'`:

```diff title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.png$/,
-       use: [
-         {
-           loader: 'url-loader',
-         },
-       ],
+       type: 'asset/inline'
      },
    ],
  },
};
```

### Replacing `file-loader`

Replacing `file-loader` with `type: 'asset/resource'`:

```diff title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.png$/,
-       use: [
-         {
-           loader: 'file-loader',
-         },
-       ],
+       type: 'asset/resource'
      },
    ],
  },
};
```

### Replacing `raw-loader`

Replacing `raw-loader` with `type: 'asset/source'`:

```diff title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        resourceQuery: /raw/,
-       use: [
-         {
-           loader: 'raw-loader',
-         },
-       ],
+       type: 'asset/source'
      },
    ],
  },
};
```

### Using optimizers as loaders

There are times when we want to optimize a specific image, for example by compressing its size. We can still use these loaders.

For example, optimizing all files ending in `.png` with [image-minimizer-webpack-plugin](https://github.com/webpack/image-minimizer-webpack-plugin):

```js title="rspack.config.mjs"
import ImageMinimizerPlugin from 'image-minimizer-webpack-plugin';

export default {
  module: {
    rules: [
      {
        test: /\.png$/,
        use: [
          {
            loader: ImageMinimizerPlugin.loader,
            options: {
              // ...
            },
          },
        ],
        type: 'asset/resource',
      },
    ],
  },
};
```

The above condition uses `type: 'asset/resource'`, which will direct Rspack to complete individual file generation for all matching files and return the final asset URL address.



---
url: /guide/features/asset-base-path.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Asset base path

Rspack provides the [output.publicPath](/config/output.md#outputpublicpath) option, which sets the base URL path prefix for bundled static assets (such as JS, CSS, images, etc.).

## Use cases

Imagine the following scenarios:

- Your static assets need to be deployed to a CDN
- Your web application is not deployed under the root path of the domain
- You need to use different assets paths for different environments (development, testing, or production)

In these scenarios, configuring `output.publicPath` can help you load static assets correctly.

## Basic example

Set `output.publicPath` to `/`, then the assets path will be relative to the root path.

```js title="rspack.config.mjs"
export default {
  output: {
    publicPath: '/',
  },
};
```

With this configuration, the assets access path is `http://[domain]/`, for example `http://localhost:8080/main.js`.

## Subdirectory

If your application needs to be deployed under a subdirectory, you can set `output.publicPath` to the corresponding subdirectory path:

```js title="rspack.config.mjs"
export default {
  output: {
    publicPath: '/assets/',
  },
};
```

With this configuration, all assets will be loaded from the `/assets/` path, for example `http://localhost:8080/assets/main.js`.

:::tip

- The value of `output.publicPath` usually ends with `/`.
- Do not set `output.publicPath` to a relative path, such as `./assets/`. Using a relative path may cause assets to load incorrectly when they are located at different path depths.
- If setting `output.publicPath` to an empty string, the asset URL path will be relative to the HTML page (same directory).

:::

## Use CDN

When deploying static assets using CDN, you can set `output.publicPath` based on the environment variable, and set it to the CDN URL prefix during the production build.

```js title="rspack.config.mjs"
const isProd = process.env.NODE_ENV === 'production';

export default {
  output: {
    publicPath: isProd ? 'https://cdn.example.com/' : '/',
  },
};
```

With this configuration:

- In the development mode, the assets access path is `http://[domain]/`, for example `http://localhost:8080/main.js`.
- In the production mode, the assets access path is `https://cdn.example.com/`, for example `https://cdn.example.com/main.[hash].js`.

## Dynamically set publicPath

You can set `publicPath` dynamically using [`import.meta.rspackPublicPath`](/api/runtime-api/module-variables.md#importmetarspackpublicpath) in your JavaScript code.

The `import.meta.rspackPublicPath` will override the `output.publicPath` in the Rspack config, but it will only take effect for dynamically loaded assets, not for assets loaded via `<script src="...">`.

First create a `publicPath.js`:

```js title="publicPath.js"
import.meta.rspackPublicPath =
  location.hostname === 'foo.com'
    ? 'https://cdn1.com/assets/'
    : 'https://cdn2.com/assets/';
```

Then import it into the first line of the entry file to ensure that `publicPath` is set before async assets are loaded:

```js title="entry.js"
import './publicPath.js';
import './others.js';
```

## Automatic publicPath

There are chances that you don't know what the `publicPath` will be in advance, and Rspack can automatically calculate the `publicPath` value by parsing some variables like [import.meta.url](/api/runtime-api/module-variables.md#importmetaurl), [document.currentScript](https://developer.mozilla.org/en-US/docs/Web/API/Document/currentScript), `script.src` or `self.location`.

What you need is to set `output.publicPath` to `'auto'`:

```js title="rspack.config.mjs"
export default {
  output: {
    // this is the default value when `target` is `'web'` or `'webworker'`
    publicPath: 'auto',
  },
};
```



---
url: /guide/features/module-resolution.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Module resolution

Module resolution is the process of converting a module identifier to a module's file path.

Rspack uses [rspack-resolver](https://github.com/rstackjs/rspack-resolver) for module path resolution, which is an extension to the [Node.js module resolution algorithm](https://nodejs.org/api/esm.html#resolution-algorithm-specification) with the same interface as [enhanced-resolve](https://github.com/webpack/enhanced-resolve).

Refer to [resolve configuration](/config/resolve.md) for more information about module resolution configuration.

## Rspack

Rspack supports the following three kinds of file paths:

### Absolute paths

```js
import '/home/me/file';
```

Since this path is already an absolute path, there is usually no need to do further parsing, just return the path directly.

### Relative paths

```js
import './src/answer';
```

In this case, the directory where the resource files using import and require are located is considered the context directory. The relative path given in import/require is spelled out with that context directory path to generate the absolute path to the module.

### Module paths

```js
import 'lodash';
```

Module paths are those that do not start with `'./'`, `'../'`, `'/'`. In this case, Rspack will resolve the absolute path of the module according to the module resolution rules. The [node module resolution algorithm](https://nodejs.org/api/modules.html#modules_all_together) has a detailed description of the rules for resolve modules.

## package.json `imports`

Rspack's resolver supports the [imports](https://nodejs.org/api/packages.html#subpath-imports) field in `package.json` for resolving module identifiers that start with `#` within a package.

In the following example, both `#utils` and `#/main` are resolved from the current package's `imports` field:

```json title="package.json"
{
  "imports": {
    "#utils": "./src/utils/index.js",
    "#/*": "./src/*"
  }
}
```

```js title="src/index.js"
import utils from '#utils'; // resolves to ./src/utils/index.js
import main from '#/main.ts'; // resolves to ./src/main.ts
```

> Use the [`resolve.importsFields`](/config/resolve.md#resolveimportsfields) option to customize the field name used for `imports`.



---
url: /guide/features/web-workers.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Web Workers

Rspack provides built-in support for [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers), which means you don't need any loader to use Web Workers directly.

## Usage

Basic Worker creation syntax:

```js
new Worker(new URL('./worker.js', import.meta.url));
```

You can customize the Worker's chunk name through the `name` property (the property value must be statically analyzable). This name will replace the `[name]` placeholder in the generated chunk filename:

```js
new Worker(new URL('./worker.js', import.meta.url), {
  name: 'my-worker',
});
```

:::info
This syntax was chosen for its strong standards compliance. It's built on the standard ECMAScript module specification, which means it works seamlessly even without build tools. For example, it runs natively in modern browsers with ES module support.
:::

For usage examples, see:

- [examples/worker](https://github.com/rstackjs/rstack-examples/tree/main/rspack/worker)
- [examples/monaco-editor-js](https://github.com/rstackjs/rstack-examples/tree/main/rspack/monaco-editor-js)
- [examples/monaco-editor-ts-react](https://github.com/rstackjs/rstack-examples/tree/main/rspack/monaco-editor-ts-react)

### Limitations

1. Because Rspack relies on static analysis to identify worker usage, it has the following two limitations:
   - `new Worker` and other worker-like APIs can usually also accept a string representation of a URL, but Rspack only supports passing a URL object. In practice, you must pass `new URL('./worker.js', import.meta.url)`.
   - Rspack cannot statically analyze variables used in `new Worker`. For example, the following code will not work:

     ```js
     const url = new URL('./path/to/worker.js', import.meta.url);
     const worker = new Worker(url);
     ```

2. The `/* webpackEntryOptions: { filename: "workers/[name].js" } */` magic comment is not supported yet.

## Built-in syntax

In addition to `new Worker()`, Rspack also supports the following built-in forms by default:

- `new SharedWorker()`, see [SharedWorker](https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker)

```js
const sharedWorker = new SharedWorker(
  new URL('./shared-worker.js', import.meta.url),
);
sharedWorker.port.start();
```

- `import { Worker } from "worker_threads"`: commonly used in Node.js environments, see [Worker threads](https://nodejs.org/api/worker_threads.html)

```js
import { Worker } from 'worker_threads';

const worker = new Worker(new URL('./node-worker.js', import.meta.url));
```

- `navigator.serviceWorker.register()`: used to register Service Workers, see [ServiceWorkerContainer](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register)

```js
navigator.serviceWorker
  .register(new URL('./sw.js', import.meta.url))
  .then((registration) => {
    console.log('Service worker registration succeeded:', registration);
  });
```

## Custom syntax

Use [`module.parser.javascript.worker`](/config/module-parser.md#javascriptworker) to tell Rspack which expressions should be analyzed as worker-like entry creation:

- `true` keeps the built-in defaults and is equivalent to `['...']`.
- `false` disables worker syntax analysis and is equivalent to `[]`.
- An array replaces the defaults. Keep `'...'` in the array if you want to extend the built-in defaults instead of replacing them.

The built-in syntax is implemented using the same mechanism. The `'...'` placeholder can be expanded to the following entries:

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        worker: [
          'Worker',
          'SharedWorker',
          'navigator.serviceWorker.register()',
          'Worker from worker_threads',
        ],
      },
    },
  },
};
```

The following rules explain the custom syntax:

- A trailing `()` matches call syntax, while no trailing `()` matches constructor syntax.
  - `'worker'` will match `new worker(new URL("./worker.js", import.meta.url))`.
  - `'worker()'` will match `worker(new URL("./worker.js", import.meta.url))`.
- Member syntax is also supported, but the root object must be a free variable.
  - `'foo.bar'` will match `new foo.bar(new URL("./worker.js", import.meta.url))`.
  - `'foo.bar()'` will match `foo.bar(new URL("./worker.js", import.meta.url))`.
- Use `*` to match a root object by its exact variable name. Unlike plain member syntax, the root object here is a declared variable rather than a free variable.
  - `'*foo.bar()'` will match `const foo = new WorkletContext(); foo.bar(new URL("./processor.js", import.meta.url))`.
  - For now, `*`-prefixed syntax supports only call syntax; constructor syntax such as `'*foo.bar'` is not supported.
- Use `from` to match an imported binding from an exact ESM source.
  - `'Foo from pkg'` will match `import { Foo } from 'pkg'; new Foo(new URL("./worker.js", import.meta.url))`.
  - `'default from pkg'` will match `import Foo from 'pkg'; new Foo(new URL("./worker.js", import.meta.url))`.
  - `'foo() from pkg'` will match `import { foo } from 'pkg'; foo(new URL("./worker.js", import.meta.url))`.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        worker: [
          // custom syntax
          'MyWorker',
          'myWorker()',
          'CSS.paintWorklet.addModule()',
          '*audioContext.audioWorklet.addModule()',
          'default from web-worker',
          // extend built-in syntax
          '...',
        ],
      },
    },
  },
};
```

The following examples show how these custom syntax rules work in practice.

The first few examples are based on the built-in syntax. In practice, you do not need to add them to the config because they are already included in the default `'...'`. They are shown here only to explain how the custom syntax rules work:

- Built-in constructor syntax: `Worker` and `SharedWorker`

  `Worker` and `SharedWorker` are constructors, not functions, so the syntax string does not need trailing `()`.

  ```js
  const worker = new Worker(new URL('./worker.js', import.meta.url));

  const sharedWorker = new SharedWorker(
    new URL('./shared-worker.js', import.meta.url),
  );
  ```

- Built-in call syntax: `navigator.serviceWorker.register()`

  This example shows why trailing `()` matters: `register()` is a function call, not a constructor.

  ```js
  await navigator.serviceWorker.register(new URL('./sw.js', import.meta.url));
  ```

- Built-in import syntax: `Worker from worker_threads`

  This example shows the `from` rule. The import source must match exactly.

  ```js
  import { Worker } from 'worker_threads';

  const worker = new Worker(new URL('./node-worker.js', import.meta.url));
  ```

The remaining examples show some common patterns in the ecosystem that can be supported through custom syntax:

- CSS Worklet

  The syntax `CSS.paintWorklet.addModule()` is a direct member call, so the config string ends with `()`.

  ```js title="rspack.config.mjs"
  export default {
    module: {
      parser: {
        javascript: {
          worker: [
            'CSS.paintWorklet.addModule()',
            'CSS.layoutWorklet.addModule()',
            'CSS.animationWorklet.addModule()',
            '...',
          ],
        },
      },
    },
  };
  ```

  ```js
  await CSS.paintWorklet.addModule(
    new URL('./paint-worklet.js', import.meta.url),
  );

  await CSS.layoutWorklet.addModule(
    new URL('./layout-worklet.js', import.meta.url),
  );

  await CSS?.animationWorklet?.addModule(
    new URL('./animation-worklet.js', import.meta.url),
  );
  ```

- AudioWorklet

  Unlike CSS Worklet, the root object in `audioContext.audioWorklet.addModule(...)` is not a free variable. It is a variable declared by `const audioContext = new AudioContext();`, so the custom syntax needs to start with `*` to indicate that the root object is a declared variable.

  ```js title="rspack.config.mjs"
  export default {
    module: {
      parser: {
        javascript: {
          worker: ['*audioContext.audioWorklet.addModule()', '...'],
        },
      },
    },
  };
  ```

  ```js
  const audioContext = new AudioContext();

  await audioContext.audioWorklet.addModule(
    new URL('./noise-processor.js', import.meta.url),
  );
  ```

- Importing workers from third-party packages.

  These examples show how `from` works with different import styles.

  ```js title="rspack.config.mjs"
  export default {
    module: {
      parser: {
        javascript: {
          worker: [
            'default from web-worker',
            'createWorker() from @myorg/worker',
            '...',
          ],
        },
      },
    },
  };
  ```

  ```js
  import Worker from 'web-worker';

  const browserWorker = new Worker(
    new URL('./browser-worker.js', import.meta.url),
  );
  ```

  ```js
  import { createWorker } from '@myorg/worker';

  const helperWorker = createWorker(
    new URL('./helper-worker.js', import.meta.url),
  );
  ```

## worker-loader

:::warning
`worker-loader` is provided only as a temporary solution to facilitate project migration to Rspack. It is recommended to use the `new Worker()` syntax instead.
:::

Rspack also supports worker-loader. However, since [worker-loader](https://github.com/webpack-contrib/worker-loader) is no longer maintained, please use [worker-rspack-loader](https://github.com/rstackjs/worker-rspack-loader) as a replacement.

Use [resolveLoader](/config/resolve-loader.md) to replace worker-loader with worker-rspack-loader:


**ESM**

```js title="rspack.config.mjs"
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);

export default {
  resolveLoader: {
    alias: {
      'worker-loader': require.resolve('worker-rspack-loader'),
    },
  },
};
```


**CJS**

```js title="rspack.config.cjs"
module.exports = {
  resolveLoader: {
    alias: {
      'worker-loader': require.resolve('worker-rspack-loader'),
    },
  },
};
```



This page is adapted from [webpack documentation](https://webpack.js.org/guides/web-workers/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




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

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# ESM output

Rspack supports building with ESM format output. When building applications, Rspack generates IIFE-based bundled output by default instead of standard CommonJS or ESM format. You can configure [output.module](/config/output.md#outputmodule) to generate ESM format output. The following sections introduce how to [build application ESM output](#building-application-esm-output) and [build library ESM output](#building-library-esm-output), and finally list the [configuration checklist](#configuration-checklist) related to ESM output.

## Building application ESM output

When building applications, Rspack generates CommonJS-like format output by default. If you need to generate ESM format output, you can configure it in `rspack.config.mjs` as follows:

```js title="rspack.config.mjs"
export default {
  //...
  output: {
    module: true,
    chunkFormat: 'module',
    chunkLoading: 'import',
    workerChunkLoading: 'import',
  },
};
```

You can check out examples of [building React applications to ESM output](https://github.com/rstackjs/rstack-examples/tree/main/rspack/react-refresh-esm) and [React ESM SSR](https://github.com/rstackjs/rstack-examples/tree/main/rspack/react-ssr-esm) in rspack-examples.

## Building library ESM output

We recommend using [Rslib](https://rslib.rs) to build library output. Rslib is built on top of Rspack and can build multiple formats including ES Module, CommonJS, and UMD. Rslib provides higher-level APIs that simplify the library building process. Compared to using Rspack directly, using Rslib for library building is more convenient and efficient.

If you need to use Rspack directly to build ESM format output for libraries (npm library), `modern-module` is the recommended starting point:

```js title="rspack.config.mjs"
export default {
  //...
  output: {
    library: {
      type: 'modern-module',
    },
  },
  optimization: {
    avoidEntryIife: true,
    minimize: false,
  },
};
```

Unlike application-oriented `output.module: true`, `modern-module` switches Rspack onto a dedicated ESM library rendering path. It automatically enables `output.module` and moves chunk loading to `import`, so you usually do not need to manually set `chunkFormat: 'module'` or `chunkLoading: 'import'`. If your library also needs ESM worker chunk loading, configure `workerChunkLoading: 'import'` explicitly. Also, do not enable `optimization.concatenateModules`, because `modern-module` uses its own linking and scope-hoisting pipeline.

You can check out this [rspack-examples](https://github.com/rstackjs/rstack-examples/tree/main/rspack/library-esm) ESM library example.

Building ESM output also requires handling various detailed issues, which are not listed exhaustively here. You can refer to the [ESM format related configurations in Rslib](https://github.com/web-infra-dev/rslib/blob/f727b18805767b99fb85ae67ebff959aa644536e/packages/core/src/config.ts), or use Rslib directly for out-of-the-box library building.

## Future plans for ESM output

Compared with earlier versions, `modern-module` now covers the more important library capabilities, including code splitting, custom splitChunks, [`output.library.preserveModules`](/config/output.md#outputlibrarypreservemodules), and external-module re-exports such as `export *` / `export * as`.

The remaining work is now more about spec alignment and edge cases than basic ESM availability:

1. Better application-oriented ESM output and development experience, including HMR and lazy compilation
2. Namespace objects still differ from native ESM in a few places, such as `null` prototype behavior, frozen / non-extensible semantics, and observable own-key ordering
3. Some string-export-name edge cases are still being completed, for example quoted names that affect temporary identifier generation
4. `preserveModules` currently only works with `modern-module`; using the same module as the output root of multiple entries is also discouraged, and currently errors
5. `modern-module` cannot be mixed with other `library.type` values in the same compilation, because it takes over chunk rendering, chunk loading, and splitChunks behavior

In other words, the focus has been shifting from "can Rspack emit ESM at all?" to "can Rspack make library ESM closer to native semantics across more edge cases?".

## Configuration checklist

Below are the main configuration options related to ESM and their descriptions, which are used when building both applications and libraries.

1. [output.module](/config/output.md#outputmodule): Set to `true` to generate ESM format output. When this option is enabled, it affects the following configurations:
   1. Affects [externalsType](/config/externals.md#externalstype) default value: When `output.module` is `true`, `externalsType` defaults to `'module-import'`. For compatibility, `output.library.type: 'modern-module'` currently keeps this default unless you explicitly configure `externalsType: 'modern-module'`; `modern-module` externals will become the default for `modern-module` libraries in the next major version.
   2. Affects [output.filename](/config/output.md#outputfilename) default value: When `output.module` is `true`, the default filename is `'[name].mjs'` instead of `'[name].js'`
   3. Affects [output.chunkFilename](/config/output.md#outputchunkfilename) default value indirectly: It is derived from `output.filename`, so the default is `'[name].mjs'` with ESM output. A custom `output.filename` can change this; when it is a function, `output.chunkFilename` defaults to `'[id].js'`.
   4. Affects [output.hotUpdateChunkFilename](/config/output.md#outputhotupdatechunkfilename) default value: When `output.module` is `true`, defaults to `'[id].[fullhash].hot-update.mjs'`
   5. Affects [output.hotUpdateMainFilename](/config/output.md#outputhotupdatemainfilename) default value: When `output.module` is `true`, defaults to `'[runtime].[fullhash].hot-update.json.mjs'`
   6. Affects [output.iife](/config/output.md#outputiife) default value: When `output.module` is `true`, `output.iife` defaults to `false`
   7. If [`output.library`](/config/output.md#outputlibrary) is also configured and [`output.library.type`](/config/output.md#outputlibrarytype) is not set explicitly, the default becomes `'modern-module'` instead of `'var'`
   8. Affects [output.scriptType](/config/output.md#outputscripttype) default value: When `output.module` is `true`, defaults to `'module'`
   9. Affects [output.environment.dynamicImport](/config/output.md#outputenvironment) default value: Enabled when `output.module` is `true`
   10. Affects [output.environment.dynamicImportInWorker](/config/output.md#outputenvironment) default value: Enabled when `output.module` is `true`
   11. Affects [output.environment.module](/config/output.md#outputenvironment) default value: Enabled when `output.module` is `true`
   12. Affects Node.js related configuration defaults: In Node.js environment, when `output.module` is `true`, `__filename` and `__dirname` default to `'node-module'`
2. [output.chunkFormat](/config/output.md#outputchunkformat): When building application ESM output, this is typically set to `'module'` to use ESM-format chunks.
3. [output.library.type](/config/output.md#outputlibrarytype): When building library ESM output, this is typically set to `'modern-module'` to use Rspack's dedicated ESM library rendering path.
4. [output.chunkLoading](/config/output.md#outputchunkloading): When building application ESM output, this is typically set to `'import'`; for `modern-module`, Rspack switches chunk loading to `import` automatically.
5. [output.workerChunkLoading](/config/output.md#outputworkerchunkloading): When your application or library also needs ESM worker chunk loading, this is typically set to `'import'`.
6. [optimization.avoidEntryIife](/config/optimization.md#optimizationavoidentryiife): In some cases, Rspack wraps ESM output in an IIFE, which breaks ESM's modular characteristics.
7. [HtmlRspackPlugin.scriptLoading](/plugins/html-rspack-plugin.md#scriptloading): Set to `'module'` to use ESM `<script type="module">` for loading `.mjs` modules.



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

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 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).

The Rspack team works closely with the Module Federation development team and provides first-class support for Module Federation.

## 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.
- Different teams working on different parts of the same application without needing to recompile the entire application.
- Dynamic code loading and sharing between applications at runtime.

Module Federation can help you:

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

## How to use

Module Federation (MF) currently has multiple major versions, and you can choose one based on your needs.

Here are the characteristics of several versions:

| Version                                      | Description                                                                                        | Features                                                                                                                                                                                                                                                                  | Use Cases                                                                                                           |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| <a href="#module-federation-v20">MF v2.0</a> | - Enhanced version of Module Federation <br /> - Implemented based on Module Federation v1.5<br /> | - Provides additional out-of-the-box features such as dynamic TS type hints, Chrome Devtools, preloading, etc.<br />- More suitable for micro-frontend architecture supporting large-scale Web applications <br />- Includes all features of Module Federation 1.5 <br /> | Projects that need to use advanced capabilities of Module Federation 2.0                                            |
| <a href="#module-federation-v15">MF v1.5</a> | Version built into Rspack                                                                          | - Supports module export, module loading, dependency sharing capabilities of Module Federation v1.0<br />- Added runtime plugin functionality, allowing users to extend the behavior and functionality of module federation <br />                                        | Projects that don't need to use the extra capabilities of Module Federation 2.0                                     |
| <a href="#module-federation-v10">MF v1.0</a> | Version implemented based on webpack.container.ModuleFederationPlugin                              | - No longer being iterated <br /> - We recommend using Module Federation v1.5 or v2.0 versions                                                                                                                                                                            | Projects migrating from webpack to Rspack and wanting to keep the logic as consistent as possible with the original |

### Module Federation v2.0

[Module Federation 2.0](https://module-federation.io/blog/announcement.html) provides some additional out-of-the-box features based on Module Federation, such as dynamic TS type hints, Chrome devtools, Runtime plugins, preloading, making Module Federation more suitable for micro-frontend architecture supporting large-scale Web applications. Module Federation v2.0 is implemented based on v1.5.

You need to install the additional `@module-federation/enhanced` plugin to use Module Federation v2.0.

```js title="rspack.config.mjs"
import { ModuleFederationPlugin } from '@module-federation/enhanced/rspack';

export default {
  plugins: [
    new ModuleFederationPlugin({
      // options
    }),
  ],
};
```

Please refer to the [Module Federation v2.0 official documentation](https://module-federation.io/) for specific usage details.

### 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, allowing users to extend the behavior and functionality of module federation.

In Rspack 2.0, `ModuleFederationPlugin` also further improves shared dependency Tree Shaking. You can use `shared.treeShaking` to optimize shared dependencies based on actual usage. For related options, see [ModuleFederationPlugin](/plugins/module-federation-plugin.md#shared).

You can use it through Rspack's [ModuleFederationPlugin](/plugins/module-federation-plugin.md) without installing any additional plugins.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  output: {
    // set uniqueName explicitly to make HMR works
    uniqueName: 'app',
  },
  plugins: [
    new rspack.container.ModuleFederationPlugin({
      // options
    }),
  ],
};
```

> Reference: [Module Federation v1.5 example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/module-federation-v1.5).

### Module Federation v1.0

This version is implemented for compatibility with [webpack.container.ModuleFederationPlugin](https://webpack.js.org/plugins/module-federation-plugin/).

You can use it through Rspack's [ModuleFederationPluginV1](/plugins/module-federation-plugin-v1.md).

:::tip
Module Federation v1.0 is no longer being iterated on, we recommend using Module Federation v1.5 or v2.0 versions.
:::



---
url: /guide/advanced/lazy-compilation.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Lazy compilation

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're 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.
:::

## How to use

### Rspack CLI

For users of `@rspack/cli`, you can enable lazy compilation through [lazyCompilation](/config/lazy-compilation.md) configuration. Assuming you are developing a multi-page application (MPA), when developing one of these pages, Rspack will only build the entry point you are currently accessing.

```js title="rspack.config.mjs"
import { defineConfig } from '@rspack/cli';

export default defineConfig({
  entry: {
    Home: './src/Home.js',
    About: './src/About.js',
  },
  lazyCompilation: true,
});
```

`lazyCompilation: true` is equivalent to:

```js title="rspack.config.mjs"
import { defineConfig } from '@rspack/cli';

export default defineConfig({
  entry: {
    Home: './src/Home.js',
    About: './src/About.js',
  },
  lazyCompilation: {
    // lazy compile entries
    entries: true,
    // lazy compile dynamic imports
    imports: true,
  },
});
```

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

:::info
When lazy compilation is enabled for entries, entry modules will actually be asynchronously dynamically imported. Therefore if you have configured [splitChunks](/config/optimization.md#optimizationsplitchunks), entry modules will be treated as async chunk, which may result in slight differences between development and production artifacts.
:::

### Rsbuild

Use the [dev.lazyCompilation](https://rsbuild.rs/config/dev/lazy-compilation) option to enable lazy compilation with Rsbuild.

## Under the hood

The principle of lazy compilation is to proxy the unexecuted entries and dynamically imported modules. When the module is executed during runtime it sends a request to the dev server, triggering rebuild by Compiler along with module hot updates.

Only when corresponding entries and modules are executed will Rspack compile their respective entries and Modules along with all their dependencies.

![image](https://assets.rspack.rs/rspack/assets/lazy-proxy-module.png)

## Filtering modules

In addition to the [`entries`](/config/lazy-compilation.md#entries) and [`imports`](/config/lazy-compilation.md#imports) options, you can use [`test`](/config/lazy-compilation.md#test) to filter which modules are lazily compiled.

For example, if you want to disable lazy compilation for the `About` entry point, you can refer to the following configuration:

```js title="rspack.config.mjs"
import { defineConfig } from '@rspack/cli';

export default defineConfig({
  entry: {
    Home: './src/Home.js',
    About: './src/About.js',
  },
  lazyCompilation: {
    entries: true,
    imports: true,
    test(module) {
      const name = module.nameForCondition();
      return name && !/src\/About/.test(name);
    },
  },
});
```

### Exclude HMR client

If you do not use Rspack's own dev server and instead use your own server as the dev server, you generally need to add another client modules in the entry configuration to enable capabilities such as HMR. It is best to exclude these client module from lazy compilation by configuring `test`.

If not excluded and lazy compilation of entry is enabled, this client will not be compiled when accessing the page for the first time, so an additional refresh is needed to make it take effect.

For example:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

const options = {
  lazyCompilation: {
    test(module) {
      const isMyClient = module.nameForCondition().endsWith('dev-client.js');
      // make sure that dev-client.js won't be lazy compiled
      return !isMyClient;
    },
  },
};
const compiler = rspack(options);

new compiler.rspack.EntryPlugin(compiler.context, 'dev-client.js', {
  // name: undefined means this is global entry
  name: undefined,
}).apply(compiler);
```

## Integrating with custom server

If you are not using Rspack CLI or Rsbuild and are using your own development server, you need to manually integrate `rspack.lazyCompilationMiddleware` into your development server.

```js title="start.mjs"
import { rspack } from '@rspack/core';
import config from './rspack.config.mjs';
import DevServer from '@rspack/dev-server';

const compiler = rspack(config);

const middleware = rspack.lazyCompilationMiddleware(compiler);

const server = new DevServer(
  {
    port: 3000,
    setupMiddlewares(other) {
      return [middleware, ...other];
    },
  },
  compiler,
);

server.start();
```

`lazyCompilationMiddleware` accepts one parameter:

- `compiler`: The current [Compiler](/api/javascript-api/compiler.md) instance, use `lazyCompilation` config from it.

## Customizing lazy compilation endpoint

By default, the lazy compilation middleware uses the `/_rspack/lazy/trigger` prefix for handling requests. If you need to customize this prefix, you can use the [`prefix`](/config/lazy-compilation.md#prefix) option:

```js title="rspack.config.mjs"
import { defineConfig } from '@rspack/cli';

export default defineConfig({
  lazyCompilation: {
    entries: true,
    imports: true,
    // Customize the lazy compilation endpoint prefix
    prefix: '/custom-lazy-endpoint-',
  },
});
```

This is particularly useful when you're integrating with an existing system that has specific routing requirements or when you need to avoid prefix conflicts.



---
url: /guide/advanced/lazy-barrel.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Barrel file optimization

Rspack's barrel file optimization, also known as lazy barrel, improves build performance by skipping the building of unused re-export modules in side-effect-free barrel files.

## What is a barrel file

A barrel file is a module that re-exports functionality from other modules, commonly used to create a cleaner public API for a package or directory:

```js title="components/index.js (barrel file)"
export { Button } from './Button';
export { Card } from './Card';
export { Modal } from './Modal';
export { Tabs } from './Tabs';
// ... dozens more components
```

This allows consumers to import from a single entry point:

```js
import { Button, Card } from './components';
```

However, barrel files can cause performance issues because bundlers traditionally need to build all re-exported modules, even if only a few are actually used.

## How lazy barrel works

When lazy barrel optimization is enabled (which it is by default), Rspack will skip building unused re-export modules in side-effect-free barrel files until they're actually needed.

### Example

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

console.log(Button);
```

```js title="src/components/index.js (barrel file)"
export { Button } from './Button';
export { Card } from './Card';
export { Modal } from './Modal';
// ... many more exports
```

With lazy barrel optimization:

- ✅ Only `Button.js` is built
- ✅ `Card.js`, `Modal.js`, and other unused modules are not built
- ✅ Faster build times, especially in large projects

Without lazy barrel optimization:

- ❌ All modules (`Button.js`, `Card.js`, `Modal.js`, etc.) would be built
- ❌ Slower build times, even though most modules are unused

## Requirements

For lazy barrel optimization to work, barrel files must be side-effect-free. A module is considered side-effect-free when it meets one of the following conditions:

1. Package-level declaration: The `package.json` file declares `"sideEffects": false`

   ```json title="package.json"
   {
     "name": "my-components",
     "sideEffects": false
   }
   ```

   See [Side effects analysis](/guide/optimization/tree-shaking.md#side-effects-analysis) for more details.

2. Module-level declaration: Modules explicitly marked as side-effect-free through [`rules[].sideEffects`](/config/module-rules.md#rulessideeffects)

   ```js title="rspack.config.mjs"
   export default {
     module: {
       rules: [
         {
           test: /\.js$/,
           sideEffects: false,
         },
       ],
     },
   };
   ```

## Supported export patterns

Lazy barrel optimization works with the following export patterns:

### Named re-exports

```js
export { Component } from './Component';
export { utils } from './utils';
```

### Namespace re-exports

```js
export * as Components from './components';
```

### Named exports from local declarations

```js
export const API_URL = 'https://api.example.com';
export function helper() {
  /* ... */
}
```

### Default exports

```js
export default function App() {
  /* ... */
}
// The name is "default" for lazy barrel purposes
```

## Star re-exports (`export *`)

Star re-exports (`export * from "./module"`) are not fully optimized by lazy barrel and remain a performance concern.

```js title="components/index.js (barrel file with star re-exports)"
export * from './Button';
export * from './Card';
export * from './Modal';
export const API_VERSION = '1.0';
```

### When lazy barrel can still optimize

Lazy barrel will skip building star re-exports only when:

1. The barrel file is side-effect-free, and
2. The imported specifier is found in the barrel's named exports

Example scenario where optimization works:

```js title="src/index.js"
import { API_VERSION } from './components';
console.log(API_VERSION);
```

In this case:

- ✅ `API_VERSION` is a named export in the barrel file itself
- ✅ Rspack can optimize this—no modules are built (`Button.js`, `Card.js`, `Modal.js` are all skipped)

Example scenario where optimization fails:

```js title="src/index.js"
import { Button } from './components';
console.log(Button);
```

In this case:

- ❌ `Button` is not a named export in the barrel file—it's from `export * from './Button'`
- ❌ Rspack must build `./Button.js` and potentially all other star re-exports to find which module exports `Button`

## FAQ

### 1. Does lazy barrel support CommonJS?

Currently, lazy barrel only supports ES modules (ESM). CommonJS support would require improvements to Rspack's CommonJS tree shaking, particularly the static analysis capabilities. Support for CommonJS may be added in a future release.

### 2. Can Rspack automatically detect side-effect-free modules?

Rspack can analyze whether a module has side effects (this capability is already used by [`optimization.sideEffects`](/config/optimization.md#optimizationsideeffects) for tree shaking). However, this analysis requires checking the module's dependencies recursively—a module is only truly side-effect-free when all its dependencies are also side-effect-free.

During the make phase, dependencies must be built before their side effects can be analyzed. Lazy barrel is specifically designed to avoid building those dependencies. Therefore, it relies on explicit markers like `"sideEffects": false` in `package.json` or `rules[].sideEffects`, which don't require dependency checking since they declare the entire package or matched modules as side-effect-free.

## Related optimization: skipping side-effect-only import builds

This optimization is not a part of lazy barrel, but it was inspired by lazy barrel, so it is documented here separately.

For the following ESM import that is only used to trigger side effects:

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

If `./module` has already been marked as side-effect-free through `"sideEffects": false` in `package.json`, or [`rules[].sideEffects`](/config/module-rules.md#rulessideeffects), Rspack will directly skip building this module during the make phase.

This kind of `import './module'` would be removed later by side-effects optimization anyway, so continuing to run loader, parser, and build would not affect the final output and would only add overhead to the make phase. Therefore, Rspack determines its side effects early during the make phase, and if it is side-effect-free, directly skips building it.

## Further reading

- [RFC: Lazy make for reexports in side effects free barrel file](https://github.com/web-infra-dev/rspack/discussions/11273)
- [Tree shaking](/guide/optimization/tree-shaking.md)
- [Side effects analysis](/guide/optimization/tree-shaking.md#side-effects-analysis)



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

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Module layers

Module layers let you categorize and manage modules in Rspack. By assigning different layers to modules, you can perform differentiated processing for different types of modules, such as:

- Using different compilation targets based on different layers
- Splitting modules from different layers into different output directories
- Applying different compilation strategies for code in different environments (such as server-side and client-side)

## Ways to specify layers

When a module is assigned a layer, all its dependent modules will also be assigned to that layer. For example, if you specify the layer as `client` for the root module, all modules starting from the root module and their dependencies will be assigned to the `client` layer.

## Ways to specify layers

You can specify layers for modules in the following ways:

### 1. Specify via entry

Directly specify layers for different entry points in the [entry configuration using the `layer`](/config/entry.md#entrydescriptionlayer) option:

```js title="rspack.config.mjs"
export default {
  entry: {
    server: {
      import: './src/server.js',
      layer: 'server',
    },
    client: {
      import: './src/client.js',
      layer: 'client',
    },
  },
};
```

### 2. Specify via loader rules

You can use the [`rules[].layer`](/config/module-rules.md#ruleslayer) option to specify a layer for all modules that match the rule:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        layer: 'yourLayer',
      },
    ],
  },
};
```

The layer assigned by [`rules[].layer`](/config/module-rules.md#ruleslayer) will override the module's own layer. For example, if a module has been assigned a layer through Entry configuration, the layer assigned through Rule will override the layer specified by Entry.

## Layer inheritance

To better understand how Layer works, we categorize modules into two types:

- **Regular modules**: Modules that are not explicitly assigned a layer
- **Layer modules**: Modules that have been assigned a layer

### Layer inheritance rules

**1. Downward Inheritance**

All dependent modules of a Layer module will inherit the same layer. For example, when you specify the layer as `'client'` for an entry module, all modules in the entire dependency tree starting from that entry will be assigned to the `'client'` layer.

**2. Mid-path Override**

If a module in the dependency chain is reassigned to a different layer (such as `'server'`) through Loader rules, then all subsequent dependencies starting from that module will follow the new layer.

When a regular module is depended upon by multiple modules with different layers, that module will generate multiple copies in the build output, with each copy corresponding to a layer.

**Example:** If both `'client'` layer and `'server'` layer depend on the same `lib.js` module, then:

- The build output will contain two copies of `lib.js`: one belonging to the `'client'` layer and another to the `'server'` layer
- The dependency modules of these two copies will also be duplicated and assigned according to the same rules

## Applying different processing rules to different layers

You can use [`issuerLayer`](/config/module-rules.md#rulesissuerlayer) to filter modules from specific layers and apply different processing rules to them. The following example shows how to use different compilation targets for different layers:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        oneOf: [
          {
            issuerLayer: 'client',
            use: [
              {
                loader: 'builtin:swc-loader',
                options: {
                  jsc: {
                    target: 'es5',
                  },
                },
              },
            ],
          },
          {
            issuerLayer: 'server',
            use: [
              {
                loader: 'builtin:swc-loader',
                options: {
                  jsc: {
                    target: 'es2020',
                  },
                },
              },
            ],
          },
        ],
      },
    ],
  },
};
```

## Layer-based code splitting

During the build optimization phase, you can assign modules to different chunks based on different layers:

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        server: {
          layer: 'server',
          filename: 'server/[name].js',
        },
        client: {
          layer: 'client',
          filename: 'client/[name].js',
        },
      },
    },
  },
};
```

Through the above configuration, we successfully output server and client code to different directories respectively, achieving layer-based code separation.



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

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# TypeScript

## How to use

Enabling TypeScript support can be done through [`builtin:swc-loader`](/guide/features/builtin-swc-loader.md).

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|ts)$/,
        exclude: [/node_modules/],
        loader: 'builtin:swc-loader',
        options: {
          detectSyntax: 'auto',
        },
      },
    ],
  },
};
```

## Transpile only

For maximum speed, `builtin:swc-loader` transpiles TypeScript source code without performing any type checking. An external tool such as `tsc` must be used for type checking.

## Enable isolatedModules

To maximize parallelism, `builtin:swc-loader` will transpile each module separately. This requires that [`isolatedModules`](https://www.typescriptlang.org/tsconfig#isolatedModules) must be enabled in your TypeScript configuration to ensure type check of source code by tsc. Certain language features such as [const enums](https://www.typescriptlang.org/docs/handbook/enums.html#const-enums) rely on parsing the entire project, and thus cannot be used with isolated module transpilation. Enable `isolatedModules` in your `tsconfig.json ` file to ensure that your IDE hints and type checker accurately reflect Rspack's module handling behavior:

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

## Type checking

You can use the [ts-checker-rspack-plugin](https://github.com/rstackjs/ts-checker-rspack-plugin) to perform TypeScript type checking during compilation. However, it's important to note that TypeScript's type checking can be time-consuming, especially for larger projects. This means that the time required for type checking may exceed the build time of Rspack itself.

If you are using the plugin in development mode, it won't block the build and you can continue with the build process. However, in build mode, the plugin will block the build until the type checking is complete which may lead to longer build times.

Based on your actual needs, you should decide whether to enable this plugin. If the type checking process becomes a bottleneck in your build process, we recommend using TypeScript's incremental build feature. This feature can greatly speed up the type checking process by only analyzing the changed files since the last build.

To enable TypeScript's incremental build, you can use `tsc --incremental` independently or [enabling incremental mode](https://github.com/rstackjs/ts-checker-rspack-plugin#enabling-incremental-mode) in the plugin.

Enabling incremental build can help reduce type checking time, especially when only a few files have been modified. This way, you can optimize your build process without sacrificing the benefits of type checking.

Remember to evaluate the trade-off between build speed and the accuracy of type checking in your specific project, and choose the best approach accordingly.

## JSX and TSX

Enabling TSX|JSX support can be done through [`builtin:swc-loader`](/guide/features/builtin-swc-loader.md).

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              transform: {
                react: {
                  pragma: 'React.createElement',
                  pragmaFrag: 'React.Fragment',
                  throwIfNamespace: true,
                  development: false,
                },
              },
            },
          },
        },
      },
    ],
  },
};
```

## Alias

See [resolve.tsConfig](/config/resolve.md#resolvetsconfig) for details.

## Client types

It's possible to use the type of Rspack specific features in your TypeScript code, such as [import.meta.glob](/api/runtime-api/module-variables.md#importmetaglob).

Rspack provides client module types via `@rspack/core/module`, you can declare them in different ways:

1. Add the TypeScript reference directive to declare:

   Add the following content to the global d.ts declarattion file:

   ```ts title="src/index.ts"
   /// <reference types="@rspack/core/module" />
   ```

   It can then be used in any TypeScript file:

   ```ts title="src/index.ts"
   const modules = import.meta.glob('./dir/*.js'); // without reference declared above, TypeScript will throw an error
   ```

2. You can also add `@rspack/core/module` to the `types` field of tsconfig.json. You could refer to the [tsconfig types document](https://www.typescriptlang.org/tsconfig/#types) for more details.

   ```json title="tsconfig.json"
   {
     "compilerOptions": {
       "types": ["@rspack/core/module"]
     }
   }
   ```



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

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# CSS

Rspack has built-in support for CSS and provides several features to support CSS bundling.

## Enabling CSS support

You can choose from the following options:

### Built-in CSS support

Rspack supports the following four [CSS Modules](#css-modules) types which you can configure manually:

- `css/auto`: Automatically determines whether a file is a normal CSS file or CSS Modules based on the file extension. Files ending with `*.module.css` or `*.modules.css` are treated as CSS Modules.
- `css`: Used to handle normal CSS files without CSS Modules features.
- `css/global`: Used to handle CSS Modules in global scope mode.
- `css/module`: Used to handle CSS Modules.

The difference between `css/auto`, `css/global`, and `css/module` is how CSS Modules scope affects the generated CSS:

- `css/auto` chooses the behavior by filename. `style.css` is handled as plain CSS, while `style.module.css` and `style.modules.css` are handled like `css/module`.
- `css/module` enables CSS Modules with local scope by default. A selector like `.button` is renamed in the generated CSS. Use `:global(.button)` when you want a selector to stay global.
- `css/global` enables CSS Modules with global scope by default. A selector like `.button` stays global. Use `:local(.button)` when you want a selector to be renamed in the generated CSS.

For example:

```css title="style.css"
.button {
  color: red;
}

:local(.title) {
  color: blue;
}
```

With `type: 'css'`, the file is emitted as plain CSS without applying CSS Modules scope transforms.

With `type: 'css/module'`, `.button` and `.title` are local selectors and are renamed in the generated CSS. Use `:global(.button)` if `.button` should stay global.

With `type: 'css/global'`, `.button` stays global, while `.title` is renamed because it is wrapped in `:local(...)`.

The generated CSS would look like this:


**css/auto style.css**

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

:local(.title) {
  color: blue;
}
```


**css/auto style.module.css**

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

._title_hash {
  color: blue;
}
```


**css/module style.css**

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

._title_hash {
  color: blue;
}
```


**css/global style.css**

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

._title_hash {
  color: blue;
}
```


To enable CSS support, add CSS rules to your configuration:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.module\.css$/i,
        type: 'css/module',
      },
      {
        test: /\.global\.css$/i,
        type: 'css/global',
      },
      {
        test: /\.css$/i,
        type: 'css/auto',
      },
    ],
  },
};
```

You can also configure `type: 'css/auto'` to customize which files are treated as CSS files. For example, treat `.less` files as CSS files:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        type: 'css/auto', // 👈
        use: ['less-loader'],
      },
    ],
  },
};
```

### CSS export type

Built-in CSS support uses `exportType: 'link'` by default. This emits CSS as stylesheet output and loads it with the built-in CSS loading runtime. You can set `module.parser.css.exportType` or the parser options for `css/auto`, `css/global`, and `css/module` to change how CSS is exported to JavaScript.

Supported values:

- `link`: emit CSS as stylesheet output.
- `text`: export the generated CSS text as the default export.
- `css-style-sheet`: export a `CSSStyleSheet` instance as the default export.
- `style`: inject CSS into the document through `<style>` tags at runtime.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        type: 'css/auto',
        parser: {
          exportType: 'text',
        },
      },
    ],
  },
};
```

```js title="index.js"
import cssText from './style.css';

console.log(cssText);
```

See [module.parser\["css/auto"\].exportType](/config/module-parser.md#cssautoexporttype) for details.

### Using CssExtractRspackPlugin

Rspack supports using [css-loader](https://github.com/webpack/css-loader) and [CssExtractRspackPlugin](/plugins/css-extract-rspack-plugin.md) to generate standalone CSS files.

If you are migrating a webpack project that uses [mini-css-extract-plugin](https://github.com/webpack/mini-css-extract-plugin), it is recommended to replace it with CssExtractRspackPlugin. Their functionality and options are basically the same.

- Install css-loader:


```sh [npm]
npm add css-loader -D
```

```sh [yarn]
yarn add css-loader -D
```

```sh [pnpm]
pnpm add css-loader -D
```

```sh [bun]
bun add css-loader -D
```

```sh [deno]
deno add npm:css-loader -D
```

- Add configuration:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
        type: 'javascript/auto',
      },
    ],
  },
  plugins: [new rspack.CssExtractRspackPlugin({})],
};
```

> Refer to the [migration guide](/guide/migration/webpack.md#mini-css-extract-plugin) to learn how to migrate from webpack.

:::tip
CssExtractRspackPlugin cannot be used with `type: 'css'`, `type: 'css/auto'`, `type: 'css/global'`, or `type: 'css/module'` as these types are provided by native css support.
:::

### Using style-loader

Rspack supports using [css-loader](https://github.com/webpack/css-loader) and [style-loader](https://github.com/webpack/style-loader) to inject CSS via `<style>` tags. This method does not generate standalone CSS files but inline the CSS content into JS files.

- Install css-loader and style-loader:


```sh [npm]
npm add css-loader style-loader -D
```

```sh [yarn]
yarn add css-loader style-loader -D
```

```sh [pnpm]
pnpm add css-loader style-loader -D
```

```sh [bun]
bun add css-loader style-loader -D
```

```sh [deno]
deno add npm:css-loader npm:style-loader -D
```

- Add configuration:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['style-loader', 'css-loader'],
        type: 'javascript/auto',
      },
    ],
  },
};
```

:::tip
style-loader cannot be used with `type: 'css'`, `type: 'css/auto'`, `type: 'css/global'`, or `type: 'css/module'` as these types are provided by native css support.
:::

## CSS Modules

[CSS Modules](https://github.com/css-modules/css-modules) is a way of organizing CSS files that localizes the scope of CSS by automatically generating unique identifiers for class names. This allows you to use the same class name in different files without worrying about collisions.

### Built-in support

If you enable [Built-in CSS support](#built-in-css-support), Rspack will treat files with a `*.module.css` extension as CSS Modules by default. You can import them into your JavaScript files, and then access each class defined in the CSS file as an export from the module.

```css title="index.module.css"
.red {
  color: red;
}
```

You can use namespace import:

```ts title="index.js"
import * as styles from './index.module.css';
document.getElementById('element').className = styles.red;
```

You can also use named import:

```ts
import { red } from './index.module.css';
document.getElementById('element').className = red;
```

To enable default imports in Rspack, you need to set `namedExports` to `false` in your Rspack configuration file. This allows you, when using CSS Modules, to import the entire style module by default import, in addition to namespace imports and named imports:

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        namedExports: false,
      },
    },
  },
};
```

Now you can use default import:

```js
import styles from './index.module.css';
document.getElementById('element').className = styles.red;
```

:::tip

Rspack provides options to customize the parsing and generation of CSS Modules:

- Parser options:
  - [module.parser\["css/auto"\]](/config/module-parser.md#cssauto)
  - [module.parser\["css/global"\]](/config/module-parser.md#cssglobal)
  - [module.parser\["css/module"\]](/config/module-parser.md#cssmodule)
- Generator options:
  - [module.generator\["css/auto"\]](/config/module-generator.md#cssauto)
  - [module.generator\["css/global"\]](/config/module-generator.md#cssglobal)
  - [module.generator\["css/module"\]](/config/module-generator.md#cssmodule)

:::

### Using css-loader

If you do not enable Rspack's built-in CSS support, you can use [css-loader](https://github.com/webpack/css-loader) to provide CSS Modules support.

Enable the `modules` option of `css-loader`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        type: 'javascript/auto',
        options: {
          modules: true,
        },
      },
    ],
  },
};
```

For more usage, please refer to [css-loader - modules](https://github.com/webpack/css-loader#modules).

## PostCSS

Rspack supports [postcss-loader](https://github.com/webpack/postcss-loader), which you can configure like this:


```sh [npm]
npm add postcss postcss-loader -D
```

```sh [yarn]
yarn add postcss postcss-loader -D
```

```sh [pnpm]
pnpm add postcss postcss-loader -D
```

```sh [bun]
bun add postcss postcss-loader -D
```

```sh [deno]
deno add npm:postcss npm:postcss-loader -D
```

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                // ...
              },
            },
          },
        ],
        // set to 'css/auto' if you want to support '*.module.css' as CSS Modules, otherwise set type to 'css'
        type: 'css/auto',
      },
    ],
  },
};
```

The above configuration will have all `*.css` files processed by [postcss-loader](https://github.com/webpack/postcss-loader). The output will be passed to Rspack for CSS post-processing.

## Sass

Rspack supports [sass-loader](https://github.com/webpack/sass-loader), which you can configure like this:


```sh [npm]
npm add sass-embedded sass-loader -D
```

```sh [yarn]
yarn add sass-embedded sass-loader -D
```

```sh [pnpm]
pnpm add sass-embedded sass-loader -D
```

```sh [bun]
bun add sass-embedded sass-loader -D
```

```sh [deno]
deno add npm:sass-embedded npm:sass-loader -D
```

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(sass|scss)$/,
        use: [
          {
            loader: 'sass-loader',
            options: {
              // using `modern-compiler` and `sass-embedded` together significantly improve build performance,
              // requires `sass-loader >= 14.2.1`
              api: 'modern-compiler',
              implementation: require.resolve('sass-embedded'),
            },
          },
        ],
        // set to 'css/auto' if you want to support '*.module.(scss|sass)' as CSS Modules, otherwise set type to 'css'
        type: 'css/auto',
      },
    ],
  },
};
```

The above configuration runs all `*.sass` and `*.scss` files through the [sass-loader](https://github.com/webpack/sass-loader) and passes the resulting results to Rspack for CSS post-processing.

## Less

Rspack supports [less-loader](https://github.com/webpack/less-loader), which you can configure like this:


```sh [npm]
npm add less less-loader -D
```

```sh [yarn]
yarn add less less-loader -D
```

```sh [pnpm]
pnpm add less less-loader -D
```

```sh [bun]
bun add less less-loader -D
```

```sh [deno]
deno add npm:less npm:less-loader -D
```

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          {
            loader: 'less-loader',
            options: {
              // ...
            },
          },
        ],
        // set to 'css/auto' if you want to support '*.module.less' as CSS Modules, otherwise set type to 'css'
        type: 'css/auto',
      },
    ],
  },
};
```

The above configuration runs all `*.less` files through the [less-loader](https://github.com/webpack/less-loader) and passes the generated results to Rspack for CSS post-processing.

## Tailwind CSS

[Tailwind CSS](https://tailwindcss.com/) is a CSS framework and design system based on utility class, which can quickly add common styles to components, and support flexible extension of theme styles.

Tailwind CSS documentation provides integration guides for Rspack, please refer to:

- [Install Tailwind CSS v4 with Rspack](https://tailwindcss.com/docs/installation/framework-guides/rspack/react)
- [Install Tailwind CSS v3 with Rspack](https://v3.tailwindcss.com/docs/guides/rspack)



---
url: /guide/languages/html.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# HTML

Rspack can generate HTML through plugins and automatically inject emitted JavaScript and CSS assets. This guide covers two plugin options and how they differ in performance, features, and `html-webpack-plugin` compatibility.

## Choose a plugin

Rspack provides two plugin options for generating HTML:

- The built-in [`rspack.HtmlRspackPlugin`](/plugins/html-rspack-plugin.md) is implemented in Rust and focuses on performance and common HTML generation needs.
- The standalone [`html-rspack-plugin`](https://github.com/rstackjs/html-rspack-plugin) is a JavaScript fork of `html-webpack-plugin` that prioritizes compatibility with its behavior.

### Performance

The built-in Rust implementation provides better build performance, especially when generating many HTML files. The JavaScript plugin also includes Rspack-specific optimizations but prioritizes compatibility.

### Features

`rspack.HtmlRspackPlugin` supports most `html-webpack-plugin` features, but cannot fully match all behaviors of the JavaScript implementation because its core logic runs in Rust. Use it when its features meet your needs and performance is the priority. Use `html-rspack-plugin` when migrating an existing `html-webpack-plugin` setup or when you need an unsupported option, capability, or behavior.

:::tip
`rspack.HtmlRspackPlugin` supports only a subset of EJS-style syntax and does not execute arbitrary JavaScript. For compatibility with `html-webpack-plugin` template processing behavior, use `html-rspack-plugin` and see its [template documentation](https://github.com/rstackjs/html-rspack-plugin#writing-your-own-templates).
:::

## Built-in HtmlRspackPlugin

`rspack.HtmlRspackPlugin` is included in `@rspack/core`, so no additional package is required.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.HtmlRspackPlugin()],
};
```

For all configuration options, see the [plugin documentation](/plugins/html-rspack-plugin.md).

## html-rspack-plugin

Install `html-rspack-plugin` separately:


```sh [npm]
npm add html-rspack-plugin -D
```

```sh [yarn]
yarn add html-rspack-plugin -D
```

```sh [pnpm]
pnpm add html-rspack-plugin -D
```

```sh [bun]
bun add html-rspack-plugin -D
```

```sh [deno]
deno add npm:html-rspack-plugin -D
```

```js title="rspack.config.mjs"
import HtmlRspackPlugin from 'html-rspack-plugin';

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

For configuration options, see [Options](https://github.com/rstackjs/html-rspack-plugin#options).

If you are migrating from `html-webpack-plugin`, see the [webpack migration guide](/guide/migration/webpack.md#html-webpack-plugin).



---
url: /guide/languages/json.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# JSON

Rspack has built-in support for [JSON](https://en.wikipedia.org/wiki/JSON), and you can import JSON files directly.

## Default import

```json title="example.json"
{
  "foo": "bar"
}
```

```ts title="index.js"
import json from './example.json';
console.log(json.foo); // "bar"
```

## Named import

In non-`.mjs` non-strict ESM files, you can directly import properties from JSON.

```json title="example.json"
{
  "foo": "bar"
}
```

```ts title="index.js"
import { foo } from './example.json';
console.log(foo); // "bar"
```

## Import attributes

Rspack supports [import attributes](https://github.com/tc39/proposal-import-attributes), and you can use import attributes to import JSON:

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



---
url: /guide/integrations/react.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# React

## How to use

Rspack provides two solutions to support React:

- **Use Rsbuild**: Rsbuild provides out-of-the-box support for React, allowing you to quickly create a React project. See [Rsbuild - React](https://rsbuild.rs/guide/framework/react) for details.
- **Manual configure Rspack**: You can refer to the current document to manually add configurations for React.

## Configure JSX/TSX

Rspack leverages SWC transformer for supporting JSX and TSX.

You can add [builtin:swc-loader](/guide/features/builtin-swc-loader.md) loader to support `.jsx` and `.tsx` files:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
          },
        },
      },
    ],
  },
};
```

Refer to [builtin:swc-loader](/guide/features/builtin-swc-loader.md) for detailed configurations.

## Fast Refresh

There are currently two ways to enable React Fast Refresh in Rspack:

First you need to install [@rspack/plugin-react-refresh](https://www.npmjs.com/package/@rspack/plugin-react-refresh) to support React Fast Refresh.


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

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

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

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

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

Enabling [React Fast Refresh](https://reactnative.dev/docs/fast-refresh) functionality primarily involves two aspects: code injection and code transformation.

- Code injection will inject some code from the `react-refresh` package, as well as some custom runtime code, all of which are integrated in the [@rspack/plugin-react-refresh](https://github.com/rstackjs/rspack-plugin-react-refresh) plugin and can be injected through this plugin.
- Code transformation can be added through loaders, such as [jsc.transform.react.refresh](https://swc.rs/docs/configuration/compilation#jsctransformreactrefresh) for swc-loader or the [react-refresh/babel](https://github.com/facebook/react/tree/main/packages/react-refresh) for babel-loader.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';
import { ReactRefreshRspackPlugin } from '@rspack/plugin-react-refresh';

const isDev = process.env.NODE_ENV === 'development';

export default {
  mode: isDev ? 'development' : 'production',
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              transform: {
                react: {
                  development: isDev,
                  refresh: isDev,
                },
              },
            },
          },
        },
      },
    ],
  },
  plugins: [
    isDev && new ReactRefreshRspackPlugin(),
    isDev && new rspack.HotModuleReplacementPlugin(),
  ],
};
```

Compared to the previous approach, this method decouples the React Fast Refresh code injection logic from the transformation logic. The code injection logic is handled uniformly by the @rspack/plugin-react-refresh plugin, while the code transformation is handled by loaders. This means that this plugin can be used in conjunction with `builtin:swc-loader`, `swc-loader`, or `babel-loader`:

- For usage with `builtin:swc-loader`, you can refer to the example at [examples/react-refresh](https://github.com/rstackjs/rstack-examples/tree/main/rspack/react-refresh), When using with `swc-loader`, simply replace `builtin:swc-loader` with `swc-loader`.
- For usage with `babel-loader`, you can refer to the example at [examples/react-refresh-babel-loader](https://github.com/rstackjs/rstack-examples/tree/main/rspack/react-refresh-babel-loader)

## React Compiler

React Compiler is an experimental compiler introduced in React 19 that can automatically optimize your React code.

Before you start using React Compiler, it's recommended to read the [React Compiler documentation](https://react.dev/learn/react-compiler) to understand the functionality, current state, and usage of the React Compiler.

### Using `builtin:swc-loader`

The steps to use React Compiler in Rspack:

1. Upgrade `@rspack/core` to v2.1.0 or later.
2. Upgrade versions of `react` and `react-dom` to 19. If you are unable to upgrade, you can install the extra [react-compiler-runtime](https://www.npmjs.com/package/react-compiler-runtime) package which will allow the compiled code to run on versions prior to 19.
3. Enable React Compiler in `builtin:swc-loader` through `jsc.transform.reactCompiler`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              transform: {
                react: {
                  runtime: 'automatic',
                },
                reactCompiler: true,
              },
            },
          },
        },
      },
    ],
  },
};
```

For React 17 and 18 projects, set the compiler target:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              transform: {
                react: {
                  runtime: 'automatic',
                },
                reactCompiler: {
                  target: '18',
                },
              },
            },
          },
        },
      },
    ],
  },
};
```

The `reactCompiler` options are aligned with the React Compiler configuration. For example, you can use [`compilationMode`](https://react.dev/reference/react-compiler/compilationMode) to control which functions are compiled.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              transform: {
                react: {
                  runtime: 'automatic',
                },
                reactCompiler: {
                  compilationMode: 'annotation',
                },
              },
            },
          },
        },
      },
    ],
  },
};
```

For more options, refer to the official [React Compiler configuration documentation](https://react.dev/reference/react-compiler/configuration).

### Using Babel

You can also use the Babel plugin published by React Compiler. This is useful if you need Babel-specific integration or options that are not available in the SWC transform yet.

To use Babel, install:

- [@babel/core](https://www.npmjs.com/package/@babel/core)
- [babel-loader](https://www.npmjs.com/package/babel-loader)
- [babel-plugin-react-compiler](https://www.npmjs.com/package/babel-plugin-react-compiler)
- [@babel/plugin-syntax-jsx](https://www.npmjs.com/package/@babel/plugin-syntax-jsx)

Register `babel-loader` in your Rspack config file:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        use: [
          {
            loader: 'builtin:swc-loader',
            options: {
              // SWC options for JS
            },
          },
        ],
      },
      {
        test: /\.jsx$/,
        use: [
          {
            loader: 'builtin:swc-loader',
            options: {
              // SWC options for JSX
            },
          },
          { loader: 'babel-loader' },
        ],
      },
    ],
  },
};
```

Create a `babel.config.js` and configure the plugins:

```js title="babel.config.js"
const ReactCompilerConfig = {/* ... */};

module.exports = function () {
  return {
    plugins: [
      ['babel-plugin-react-compiler', ReactCompilerConfig], // must run first!
      '@babel/plugin-syntax-jsx',
    ],
  };
};
```

For React 17 and 18 projects, you need to install [react-compiler-runtime](https://www.npmjs.com/package/react-compiler-runtime) and specify the `target`:

```js title="babel.config.js"
const ReactCompilerConfig = {
  target: '18', // '17' | '18' | '19'
};
```

### Examples

You can refer to the following example projects:

- [Rspack + React Compiler](https://github.com/rstackjs/rstack-examples/tree/main/rspack/react-compiler-babel)
- [Rspack + React Compiler + TypeScript](https://github.com/rstackjs/rstack-examples/tree/main/rspack/react-compiler-babel-ts)

## Integrating SVGR

[SVGR](https://react-svgr.com/) is an universal tool for transforming [Scalable Vector Graphics (SVG)](https://en.wikipedia.org/wiki/SVG) files into React components.

The usage of SVGR with Rspack is exactly the same as with Webpack.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.svg$/i,
        issuer: /\.[jt]sx?$/,
        use: ['@svgr/webpack'],
      },
    ],
  },
};
```

For detailed usage of SVGR, please refer to [SVGR Documentation - webpack](https://react-svgr.com/docs/webpack/).

## React Server Components

If you need to use React Server Components, please refer to [Rspack - React Server Components](/guide/integrations/rsc.md).



---
url: /guide/integrations/rsc.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# React Server Components

Server Components are a new type of Component that renders ahead of time, before bundling, in an environment separate from your client app or SSR server. Rspack v2.0.0 and later have built-in full support for Server Components.

## How to use

Rspack provides two solutions to support React Server Components:

- **Using Rsbuild**: Rsbuild provides out-of-the-box support for React Server Components, allowing you to quickly create a React Server Component project. See [rsbuild-plugin-rsc](https://github.com/rstackjs/rsbuild-plugin-rsc) for details.
- **Manually Configuring Rspack**: You can refer to this document to manually add configurations related to React Server Components.

## Example

The [rstack-examples](https://github.com/rstackjs/rstack-examples/tree/main/rspack/rspack-rsc) repository contains full examples of building React Server Component applications using Rspack.

## Install dependencies


```sh [npm]
npm install react react-dom react-server-dom-rspack
```

```sh [yarn]
yarn add react react-dom react-server-dom-rspack
```

```sh [pnpm]
pnpm add react react-dom react-server-dom-rspack
```

```sh [bun]
bun add react react-dom react-server-dom-rspack
```

```sh [deno]
deno add npm:react npm:react-dom npm:react-server-dom-rspack
```

:::tip
React Server Components rely on the new architecture of React 19. Please ensure that both `react` and `react-dom` are version v19.1.0 or higher.
:::

## Basic concepts

React Server Component artifacts require cooperative execution across both server and browser environments. To support this architecture, Rspack launches **two Compiler instances** to separately build the server and browser artifacts. The diagram below illustrates the overall build flow:

![RSC Build Flow](https://assets.rspack.rs/rspack/assets/rspack-rsc-build-flow.jpg)

- **Client Compiler** (`target: 'web'`): Responsible for generating code that runs in the browser. It primarily bundles Client Components, as well as CSS and static resources required by the application, and handles the hydration logic for components.
- **Server Compiler** (`target: 'node'`): Responsible for generating code that runs on the server. It handles the pre-rendering of React Server Components, bundles the execution logic for Server Actions, and handles code related to Server-Side Rendering (SSR).

In the configuration file, this corresponds to two Compiler configurations:

```js title="rspack.config.mjs"
export default [
  // Client Compiler: Builds browser-side resources
  {
    target: 'web',
    // ...client-specific config
  },
  // Server Compiler: Builds RSC Payload and Server Actions
  {
    target: 'node',
    // ...server-specific config
  },
];
```

## Configure plugin

Rspack supports React Server Components through a pair of coordinating plugins. You must **call `rsc.createPlugins()` once** to get `ServerPlugin` and `ClientPlugin`, then attach each to the corresponding Compiler:

```js title="rspack.config.mjs"
import { experiments } from '@rspack/core';

const { createPlugins, Layers } = experiments.rsc;
const { ServerPlugin, ClientPlugin } = createPlugins();

export default [
  {
    // Client Compiler
    target: 'web',
    plugins: [new ClientPlugin()],
    // ...client-specific config
  },
  {
    // Server Compiler
    target: 'node',
    plugins: [new ServerPlugin()],
    // ...server-specific config
  },
];
```

These two plugins internally schedule the build processes of the Client Compiler and Server Compiler, establishing a communication mechanism to synchronize compilation state, module info, and generate the client reference manifest.

## Configuring build entries

You need to configure entries for the Client Compiler and Server Compiler respectively. There **must** be an entry in the Client Compiler with the exact same name as the one in the Server Compiler.

```js title="rspack.config.mjs"
export default [
  {
    target: 'web',
    entry: {
      // A 'main' entry with the same name as the server entry must exist,
      // acting as the module graph root node for the client RSC runtime.
      main: { import: './src/entry.client.tsx' },
    },
  },
  {
    target: 'node',
    entry: {
      // The server entry name is 'main'
      main: { import: './src/entry.rsc.tsx' },
    },
  },
];
```

When the Server Compiler finds `"use client"` components, it delegates those modules to the Client Compiler. Because the client config can have multiple entries, the RSC plugin uses a **same-name convention**: the client entry that has the **same name** as a server entry is treated as the RSC runtime mount for that entry.

Discovered `"use client"` modules are injected into that matching entry’s module graph. If no client entry with the same name exists, the plugin reports an "RSC Client Entry Mismatch" diagnostic and client components will not load correctly in the browser.

## Configure layer

In the Server Compiler, Rspack uses [layer](/guide/advanced/layer.md) to distinguish RSC from SSR. The RSC plugin uses these layer names:

- **`Layers.rsc`** (`'react-server-components'`): RSC environment. Only modules in this layer have `"use client"` turned into client references and `"use server"` registered as Server Actions.
- **`Layers.ssr`** (`'server-side-rendering'`): SSR environment. Use this to mark the SSR entry; if no modules are assigned to this layer, Rspack skips SSR output.

```js title="rspack.config.mjs"
import path from 'node:path';

const ssrEntry = path.resolve(
  import.meta.dirname,
  'src/framework/entry.ssr.tsx',
);
const rscEntry = path.resolve(
  import.meta.dirname,
  'src/framework/entry.rsc.tsx',
);

export default [
  // ...
  {
    target: 'node',
    module: {
      rules: [
        { resource: ssrEntry, layer: Layers.ssr },
        {
          resource: rscEntry,
          layer: Layers.rsc,
          resolve: { conditionNames: ['react-server', '...'] },
        },
        {
          issuerLayer: Layers.rsc,
          exclude: ssrEntry,
          resolve: { conditionNames: ['react-server', '...'] },
        },
      ],
    },
    // ...
  },
];
```

## Server entry

`"use server-entry"` is a specific directive introduced by Rspack, designed primarily for framework developers. It is used to mark a Server Component as the logical entry point for a page or route.

When compiling a component with `"use server-entry"`, Rspack generates the complete set of resources required to initialize the RSC application in the browser and records this information by mounting static properties directly onto the exported component:

- **entryJsFiles**: Bootstrap scripts. These correspond to the output of the build entry with the same name in the Client Compiler. They are responsible for initializing the React runtime and rendering flow on the browser side.
- **entryCssFiles**: Style resources. Rspack collects all CSS files depended upon by this Server Component and its descendant component tree.

![RSC Server Entry](https://assets.rspack.rs/rspack/assets/rspack-rsc-server-entry.jpg)

```tsx title="Todos.tsx"
'use server-entry';

import './Todos.css';
import { Dialog } from './Dialog';
import { TodoDetail } from './TodoDetail';
import { TodoCreate } from './TodoCreate';
import { TodoList } from './TodoList';

export async function Todos({ id }: { id?: number }) {
  // ...component logic
}
```

During the server runtime, you can directly access these static properties mounted on the component to construct HTML head resources:

```tsx title="entry.rsc.tsx"
import type { ServerEntry } from 'react-server-dom-rspack/server.node';

const { Todos } = await import('../Todos.tsx');
const serverEntry = Todos as ServerEntry<typeof Todos>;

const root = (
  <>
    {/* Read static properties from the component to inject CSS for the current route */}
    {serverEntry.entryCssFiles
      ? serverEntry.entryCssFiles.map((href) => (
          <link
            key={href}
            rel="stylesheet"
            href={href}
            precedence="default"
          ></link>
        ))
      : null}
    <Todos id={id} />
  </>
);

const response = await handleRequest({
  request,
  getRoot: () => root,
  // Read static properties from the component to use as bootstrap scripts
  bootstrapScripts: serverEntry.entryJsFiles,
  nonce,
});
```

## Configure JSX/TSX

Add `builtin:swc-loader` for `.jsx` / `.tsx` and enable `rspackExperiments.reactServerComponents` so Rspack parses and transforms RSC directives such as `"use client"`, `"use server"`, and `"use server-entry"`.

```js title="rspack.config.mjs"
const rscRule = {
  test: /\.(?:js|mjs|jsx|ts|tsx)$/,
  use: {
    loader: 'builtin:swc-loader',
    options: {
      detectSyntax: 'auto',
    },
    rspackExperiments: {
      reactServerComponents: true,
    },
  },
};

export default [
  {
    target: 'web',
    module: {
      rules: [rscRule],
    },
  },
  {
    target: 'node',
    module: {
      rules: [rscRule],
    },
  },
];
```

The loader executes different transformation logic for `"use client"` and `"use server"` directives based on the `layer` to which the module belongs:

1. **When the module belongs to `Layers.rsc` (Server Component environment)**, `react-server-dom-rspack` is invoked for transformation:
   - Modules with `"use client"` are transformed into **Client References**.
   - Modules with `"use server"` are registered as **Server Actions**, enabling them to respond to remote calls from the client.

2. **When the module does not belong to `Layers.rsc` (e.g., client or SSR environments)**:
   - `"use server"`: The module is transformed into a **Server Reference**.

The RSC plugin uses the loader’s directive info to tell client and server components apart, and uses it to inject client entries, collect Server Actions, and generate the RSC manifest.

## Dev server

The RSC architecture requires handling client and server builds, responding to RSC requests, and managing server component HMR. Consequently, Rspack's built-in Dev Server cannot meet these requirements. You need to implement a custom development server to provide the following core capabilities:

- **Handling RSC Requests**: Intercept and process RSC (or SSR) requests initiated by the client, invoke the render logic using artifacts generated by the Server Compiler, and return the serialized RSC Payload (or HTML stream).
- **Server Runtime Management**: Execute server build artifacts in an isolated context (such as Worker Threads or child processes) to ensure environment isolation. Additionally, ensure that when server code updates, the old instance is cleanly destroyed and restarted to execute the new code.
- **Server Component HMR**: Monitor build changes in server components and notify the browser via communication mechanisms like WebSocket. Upon receiving the signal, the browser should trigger a re-request for RSC to update the page content.

To support Server Component HMR, Rspack provides the `onServerComponentChanges` hook on `ServerPlugin` (it runs after a build when server component output has changed). In your custom dev server, use this callback to notify the browser (e.g. via WebSocket) so it can re-request RSC and refresh the page.

```js title="rspack.config.mjs"
export default [
  // ...
  {
    target: 'node',
    plugins: [
      new ServerPlugin({
        onServerComponentChanges() {
          // Invoke a method on your custom server to notify the client to refresh
        },
      }),
    ],
  },
];
```



---
url: /guide/integrations/preact.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Preact

## How to use

Rspack provides two solutions to support Preact:

- **Use Rsbuild**: Rsbuild provides out-of-the-box support for Preact, allowing you to quickly create a Preact project. See [Rsbuild - Preact](https://rsbuild.rs/guide/framework/preact) for details.
- **Manually configure Rspack**: You can refer to the current document to manually add configurations for Preact.

## Configure JSX/TSX

Rspack leverages SWC transformer for JSX/TSX.

Add `builtin:swc-loader` loader to support `jsx` and `tsx`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
          },
        },
      },
    ],
  },
};
```

Refer to [Builtin swc-loader](/guide/features/builtin-swc-loader.md) for detailed configurations.

Refer to [examples/preact](https://github.com/rstackjs/rstack-examples/blob/main/rspack/preact) for the full example.

## Preact Refresh

To enable Preact Refresh, the following steps are required:

- Add the `@rspack/plugin-preact-refresh` plugin to inject runtime code
- Add the loader for code transformation

### @rspack/plugin-preact-refresh

First you need to install the dependencies:


```sh [npm]
npm add @rspack/plugin-preact-refresh @prefresh/core @prefresh/utils -D
```

```sh [yarn]
yarn add @rspack/plugin-preact-refresh @prefresh/core @prefresh/utils -D
```

```sh [pnpm]
pnpm add @rspack/plugin-preact-refresh @prefresh/core @prefresh/utils -D
```

```sh [bun]
bun add @rspack/plugin-preact-refresh @prefresh/core @prefresh/utils -D
```

```sh [deno]
deno add npm:@rspack/plugin-preact-refresh npm:@prefresh/core npm:@prefresh/utils -D
```

The enabling of the [Preact Refresh](https://github.com/preactjs/prefresh) is divided into two parts: code injection and code transformation

- Code injection: injects code that interacts with `@prefresh/core` and `@prefresh/utils`, which has been integrated in the [@rspack/plugin-preact-refresh](https://github.com/rstackjs/rspack-plugin-preact-refresh) plugin
- Code transformation requires a loader
  - Use `builtin:swc-loader` or [`swc-loader`](https://swc.rs/docs/usage/swc-loader)
    - Enable `jsc.transform.react.refresh` to support common react transformation
    - Add [`@swc/plugin-prefresh`](https://github.com/swc-project/plugins/tree/main/packages/prefresh) into `jsc.experimental.plugins` to support the specific transformation of preact
  - Use `babel-loader` and add official [babel plugin](https://github.com/preactjs/prefresh/tree/main/packages/babel) of prefresh.

```js title="rspack.config.mjs"
import PreactRefreshPlugin from '@rspack/plugin-preact-refresh';

const isDev = process.env.NODE_ENV === 'development';

export default {
  mode: isDev ? 'development' : 'production',
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              experimental: {
                plugins: [
                  [
                    '@swc/plugin-prefresh', // enable prefresh specific transformation
                    {
                      library: ['preact-like-framework'], // the customizable preact name, default is `["preact", "preact/compat", "react"]`
                    },
                  ],
                ],
              },
              transform: {
                react: {
                  development: isDev,
                  refresh: isDev, // enable common react transformation
                },
              },
            },
          },
        },
      },
    ],
  },
  plugins: [
    isDev && new PreactRefreshPlugin(),
    isDev && new rspack.HotModuleReplacementPlugin(),
  ],
};
```

Refer to [examples/preact-refresh](https://github.com/rstackjs/rstack-examples/tree/main/rspack/preact-refresh) for the full example.



---
url: /guide/integrations/vue.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Vue

## How to use

Rspack provides two solutions to support Vue:

- **Use Rsbuild**: Rsbuild provides out-of-the-box support for Vue 3 and Vue 2, allowing you to quickly create a Vue project. See ["Rsbuild - Vue 3"](https://rsbuild.rs/guide/framework/vue#vue-3) or ["Rsbuild - Vue 2"](https://rsbuild.rs/guide/framework/vue#vue-2) for details.
- **Manually configure Rspack**: You can refer to the current document to manually add configurations for Vue.

## Vue 3

Currently, Vue 3 is supported by Rspack. Please make sure your [rspack-vue-loader](https://github.com/rstackjs/rspack-vue-loader) version is >= 17.2.2 and configure as follows:

```js title="rspack.config.mjs"
import { defineConfig } from '@rspack/cli';
import { VueLoaderPlugin } from 'rspack-vue-loader';

export default defineConfig({
  plugins: [new VueLoaderPlugin()],
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'rspack-vue-loader',
        options: {
          // Note, for the majority of features to be available, make sure this option is `true`
          experimentalInlineMatchResource: true,
        },
      },
    ],
  },
});
```

As Rspack natively supports the compilation of CSS modules, you do not need to configure loaders related to CSS. In addition, when you try to use a CSS preprocessor (such as: less), you only need to add the following configuration:

```diff title="rspack.config.mjs"
export default {
  module: {
    rules: [
+      {
+        test: /\.less$/,
+        loader: "less-loader",
+        type: "css",
+      }
    ],
  },
};
```

At this time, Rspack will use the built-in CSS processor for post-processing.

If you don't want to generate CSS files, you can also use a combination of [`css-loader`](https://github.com/webpack/css-loader) and [`vue-style-loader`](https://github.com/vuejs/vue-style-loader):

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: ['vue-style-loader', 'css-loader', 'less-loader'],
        type: 'javascript/auto',
      },
    ],
  },
};
```

Besides, as Rspack has built-in TS support, we also support `lang="ts"` configuration by default:

```html
<script lang="ts">
  export default {
    // ...
  };
</script>
```

You can refer to the related example [example-vue3](https://github.com/rstackjs/rstack-examples/tree/main/rspack/vue).

## Vue 2

Rspack has completed compatibility with Vue 2 (using vue-loader\@15).

Please make sure to use `rules[].type = "javascript/auto"` in CSS-related rules:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['vue-style-loader', 'css-loader'],
        type: 'javascript/auto',
      },
      {
        test: /\.(?:js|mjs|ts)$/, // add this rule when you use TypeScript in Vue SFC
        loader: 'builtin:swc-loader',
        options: {
          detectSyntax: 'auto',
        },
      },
    ],
  },
  experiments: {
    css: false,
  },
};
```

TypeScript is supported using Rspack's native `builtin:swc-loader`, see [this](/guide/features/builtin-swc-loader.md) for details.

You can refer to the related example [example-vue2](https://github.com/rstackjs/rstack-examples/tree/main/rspack/vue2) and [example-vue2-ts](https://github.com/rstackjs/rstack-examples/tree/main/rspack/vue2-ts).

## Vue 3 JSX

Since Rspack supports using `babel-loader`, you can directly use the [@vue/babel-plugin-jsx](https://github.com/vuejs/babel-plugin-jsx) plugin to support Vue 3 JSX syntax.

### Install

First, you need to install [babel-loader](https://www.npmjs.com/package/babel-loader), [@babel/core](https://www.npmjs.com/package/@babel/core) and [@vue/babel-plugin-jsx](https://www.npmjs.com/package/@vue/babel-plugin-jsx):


```sh [npm]
npm add babel-loader @babel/core @vue/babel-plugin-jsx -D
```

```sh [yarn]
yarn add babel-loader @babel/core @vue/babel-plugin-jsx -D
```

```sh [pnpm]
pnpm add babel-loader @babel/core @vue/babel-plugin-jsx -D
```

```sh [bun]
bun add babel-loader @babel/core @vue/babel-plugin-jsx -D
```

```sh [deno]
deno add npm:babel-loader npm:@babel/core npm:@vue/babel-plugin-jsx -D
```

### Configure

Then add the following configuration to support Vue 3 JSX syntax in `.jsx` files:

```js title="rspack.config.mjs"
import { defineConfig } from '@rspack/cli';

export default defineConfig({
  entry: {
    main: './src/index.jsx',
  },
  module: {
    rules: [
      {
        test: /\.jsx$/,
        use: [
          {
            loader: 'babel-loader',
            options: {
              plugins: ['@vue/babel-plugin-jsx'],
            },
          },
        ],
      },
    ],
  },
});
```

Rspack provides a [example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/vue-jsx) of Vue JSX for reference.

## Vue DevTools

Vue DevTools is designed to enhance the Vue developer experience; it can significantly improve your productivity and debugging capabilities when working with Vue applications.

For Vue applications built with Rspack, use [vue-devtools-rstack](https://github.com/OskarLebuda/vue-devtools-rstack) to integrate Vue DevTools.



---
url: /guide/integrations/next.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Next.js

[next-rspack](https://www.npmjs.com/package/next-rspack) is a community-driven plugin that enables Next.js projects to use Rspack as the bundler (experimental).

:::tip
See the [Rspack joins the Next.js ecosystem](/blog/rspack-next-partner.md) blog post to learn more details.
:::

## Installation

Install the `next-rspack` package:


```sh [npm]
npm add next-rspack -D
```

```sh [yarn]
yarn add next-rspack -D
```

```sh [pnpm]
pnpm add next-rspack -D
```

```sh [bun]
bun add next-rspack -D
```

```sh [deno]
deno add npm:next-rspack -D
```

:::tip
If you are using a Next.js version below 15.3.0, please upgrade to >= 15.3.0 first, see [Next.js - Upgrading](https://nextjs.org/docs/pages/building-your-application/upgrading).
:::

## Usage

Wrap your existing configuration in the project's `next.config.mjs` or `next.config.ts`:


**next.config.ts**

```ts
import withRspack from 'next-rspack';
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {/* config options here */};

export default withRspack(nextConfig);
```


**next.config.mjs**

```js
import withRspack from 'next-rspack';

/** @type {import('next').NextConfig} */
const nextConfig = {/* config options here */};

export default withRspack(nextConfig);
```


> Example: [next.js/examples/with-rspack](https://github.com/vercel/next.js/tree/canary/examples/with-rspack).

## Customizing Rspack configuration

Through Rspack's compatibility with webpack, when using `next-rspack`, you can customize configurations in the same way as you would with webpack.

In `next.config.mjs`, modify Rspack's configuration by adding the following callback function:

```js title="next.config.mjs"
export default {
  webpack: (
    config,
    { buildId, dev, isServer, defaultLoaders, nextRuntime, webpack },
  ) => {
    // Important: return the modified config
    return config;
  },
};
```

> For more details, see the [Next.js - Custom Webpack Config](https://nextjs.org/docs/app/api-reference/config/next-config-js/webpack).

## Usage with next-compose-plugins

Alternatively, you can use [next-compose-plugins](https://www.npmjs.com/package/next-compose-plugins) to quickly integrate `next-rspack` with other Next.js plugins:

```js title="next.config.mjs"
import withPlugins from 'next-compose-plugins';
import withRspack from 'next-rspack';

export default withPlugins([
  [withRspack],
  // your other plugins here
]);
```



---
url: /guide/integrations/node.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Node.js applications

Rspack can build Node.js applications by bundling application code, transforming TypeScript with SWC, keeping runtime dependencies external, and emitting assets that Node.js can load at runtime.

For modern Node.js applications, see [Use ESM output](#use-esm-output).

## Install dependencies

Install Rspack and the helper dependencies used by the examples on this page:


```sh [npm]
npm add @rspack/core @rspack/cli @rspack/dev-server webpack-node-externals run-script-webpack-plugin -D
```

```sh [yarn]
yarn add @rspack/core @rspack/cli @rspack/dev-server webpack-node-externals run-script-webpack-plugin -D
```

```sh [pnpm]
pnpm add @rspack/core @rspack/cli @rspack/dev-server webpack-node-externals run-script-webpack-plugin -D
```

```sh [bun]
bun add @rspack/core @rspack/cli @rspack/dev-server webpack-node-externals run-script-webpack-plugin -D
```

```sh [deno]
deno add npm:@rspack/core npm:@rspack/cli npm:@rspack/dev-server npm:webpack-node-externals npm:run-script-webpack-plugin -D
```

## Basic concepts

- **Node.js target** ([`target: 'node'`](/config/target.md)): Generates output suitable for Node.js instead of the browser.
- **External dependencies**: Server applications usually do not need to bundle every package in `node_modules`. Externalizing dependencies keeps the bundle smaller and allows Node.js to load packages normally at runtime.
- **Development HMR**: In development, the Node.js process needs to restart or accept updates after Rspack rebuilds the server bundle.
- **Native addons**: Dependencies or application code may reference `.node` files. These files need to be emitted as separate assets and loaded by Node.js at runtime.

## Configure Rspack

The following configuration targets Node.js, externalizes `node_modules`, writes development output to disk, and starts the generated bundle during development:

```js title="rspack.config.mjs"
// @ts-check
import { defineConfig } from '@rspack/cli';
import { RunScriptWebpackPlugin } from 'run-script-webpack-plugin';
import nodeExternals from 'webpack-node-externals';

export default defineConfig({
  context: import.meta.dirname,
  target: 'node',
  entry: {
    main:
      process.env.NODE_ENV === 'production'
        ? './src/main.ts'
        : ['@rspack/core/hot/poll?100', './src/main.ts'],
  },
  output: {
    clean: true,
  },
  resolve: {
    extensions: ['...', '.ts', '.tsx', '.jsx'],
  },
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|ts)$/,
        exclude: [/node_modules/],
        loader: 'builtin:swc-loader',
        options: {
          detectSyntax: 'auto',
        },
      },
      {
        test: /\.node$/,
        type: 'asset/resource',
      },
    ],
  },
  externals: [
    nodeExternals({
      allowlist: [/@rspack\/core\/hot\/poll/],
    }),
  ],
  plugins: [
    process.env.NODE_ENV !== 'production' &&
      new RunScriptWebpackPlugin({
        name: 'main.js',
        autoRestart: false,
      }),
  ],
  devServer: {
    devMiddleware: {
      writeToDisk: true,
    },
  },
});
```

## Configure scripts

Use `rspack dev` for development and `rspack build` for production builds:

```json title="package.json"
{
  "scripts": {
    "build": "rspack build",
    "dev": "rspack dev",
    "start": "node dist/main.js"
  }
}
```

- `dev`: Runs Rspack Dev Server, writes the server bundle to disk, and starts `dist/main.js`.
- `build`: Creates a production bundle without the HMR polling entry.
- `start`: Runs the production output with Node.js.

## Configure development HMR

Add `@rspack/core/hot/poll` only to the development entry, since including it in the production bundle will crash the Node.js application because HMR is not available in build mode:

```js title="rspack.config.mjs"
export default {
  entry: {
    main:
      process.env.NODE_ENV === 'production'
        ? './src/main.ts'
        : ['@rspack/core/hot/poll?100', './src/main.ts'],
  },
};
```

Because the server process is started from the generated bundle, `devServer.devMiddleware.writeToDisk` must be enabled:

```js title="rspack.config.mjs"
export default {
  devServer: {
    devMiddleware: {
      writeToDisk: true,
    },
  },
};
```

`RunScriptWebpackPlugin` starts the generated `main.js` file during development:

```js title="rspack.config.mjs"
import { RunScriptWebpackPlugin } from 'run-script-webpack-plugin';

export default {
  plugins: [
    new RunScriptWebpackPlugin({
      name: 'main.js',
      autoRestart: false,
    }),
  ],
};
```

The HMR polling runtime must be allowlisted when `webpack-node-externals` is used so it is bundled into the server output instead of being treated as an external dependency.

## Externalize dependencies

Use [webpack-node-externals](https://www.npmjs.com/package/webpack-node-externals) to externalize packages from `node_modules`:

```js title="rspack.config.mjs"
import nodeExternals from 'webpack-node-externals';

export default {
  externals: [
    nodeExternals({
      allowlist: [/@rspack\/core\/hot\/poll/],
    }),
  ],
};
```

## Use ESM output

For modern Node.js applications, follow the [ESM guide](/guide/features/esm.md) to output ESM bundles. When using `webpack-node-externals` with ESM output, add `importType: 'module'` so external dependencies are loaded with ESM imports:

```js title="rspack.config.mjs"
import nodeExternals from 'webpack-node-externals';

export default {
  output: {
    module: true,
  },
  externals: [
    nodeExternals({
      importType: 'module',
      allowlist: [/@rspack\/core\/hot\/poll/],
    }),
  ],
};
```

## Native node modules

When building Node.js applications with Rspack, you may encounter dependencies that include Node.js native addon dependencies (`.node` modules). Because `.node` modules cannot be packaged into JavaScript artifacts, emit them as assets and load them with Node.js.

```js title="rspack.config.mjs"
export default {
  target: 'node',
  output: {
    // Use the default publicPath or `publicPath: 'auto'` so emitted addon
    // URLs stay relative to the generated bundle.
  },
  module: {
    rules: [
      {
        test: /\.node$/,
        type: 'asset/resource',
      },
    ],
  },
};
```

Then load the emitted addon from application code with `dlopen`:

```js title="src/addon.mjs"
import { dlopen } from 'node:process';
import { fileURLToPath } from 'node:url';

const file = new URL('./file.node', import.meta.url);
const addon = { exports: {} };

try {
  dlopen(addon, fileURLToPath(file));
} catch (error) {
  // Handle addon loading errors here.
}

export default addon.exports;
```



---
url: /guide/integrations/nestjs.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# NestJS

Rspack can build [NestJS](https://nestjs.com/) applications. Compared with `tsc`, Rspack can bundle application code, transform TypeScript with SWC, enable development HMR, and leave runtime dependencies external when needed.

## How to use

Start with the common [Node.js application configuration](/guide/integrations/node.md), then add the NestJS settings described below. You can also use the [NestJS example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/nestjs) in `rstack-examples` as a reference. It includes a complete `rspack.config.mjs`, development script, production build script, and HMR entry.

## Example

The [rstack-examples](https://github.com/rstackjs/rstack-examples/tree/main/rspack/nestjs) repository contains a complete NestJS application built with Rspack.

## Install dependencies

Install the common Node.js build dependencies from the [Node.js guide](/guide/integrations/node.md#install-dependencies), then install the NestJS runtime packages:


```sh [npm]
npm add @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata rxjs
```

```sh [yarn]
yarn add @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata rxjs
```

```sh [pnpm]
pnpm add @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata rxjs
```

```sh [bun]
bun add @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata rxjs
```

```sh [deno]
deno add npm:@nestjs/common npm:@nestjs/core npm:@nestjs/platform-express npm:reflect-metadata npm:rxjs
```

## Basic concepts

NestJS applications run in Node.js, so most configurations can follow the common [Node.js configuration](/guide/integrations/node.md). The main NestJS-specific requirement is decorator metadata, which NestJS uses at runtime.

- **Decorator metadata**: Enable TypeScript decorators and emitted metadata so dependency injection, controllers, routes, guards, interceptors, and other NestJS features work correctly.
- **HMR cleanup**: When development HMR updates the server bundle, close the previous Nest application instance before accepting the update.
- **Production minification**: Keep class and function names stable because NestJS may use them through metadata reflection and execution context APIs.

## Configure Rspack

The following configuration is adapted from the NestJS example. It combines the common Node.js setup with the decorator metadata options required by NestJS:

```js title="rspack.config.mjs"
// @ts-check
import { defineConfig } from '@rspack/cli';
import { rspack } from '@rspack/core';
import { RunScriptWebpackPlugin } from 'run-script-webpack-plugin';
import nodeExternals from 'webpack-node-externals';

export default defineConfig({
  context: import.meta.dirname,
  target: 'node',
  entry: {
    main:
      process.env.NODE_ENV === 'production'
        ? './src/main.ts'
        : ['@rspack/core/hot/poll?100', './src/main.ts'],
  },
  output: {
    clean: true,
  },
  resolve: {
    extensions: ['...', '.ts', '.tsx', '.jsx'],
  },
  module: {
    rules: [
      {
        test: /\.ts$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              parser: {
                decorators: true,
              },
              transform: {
                legacyDecorator: true,
                decoratorMetadata: true,
              },
            },
          },
        },
      },
    ],
  },
  optimization: {
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin({
        minimizerOptions: {
          compress: {
            keep_classnames: true,
            keep_fnames: true,
          },
          mangle: {
            keep_classnames: true,
            keep_fnames: true,
          },
        },
      }),
    ],
  },
  plugins: [
    process.env.NODE_ENV !== 'production' &&
      new RunScriptWebpackPlugin({
        name: 'main.js',
        autoRestart: false,
      }),
  ],
  devServer: {
    devMiddleware: {
      writeToDisk: true,
    },
  },
  externals: [
    nodeExternals({
      allowlist: [/@rspack\/core\/hot\/poll/],
    }),
  ],
});
```

## Configure scripts

Use `rspack dev` during development and `rspack build` for production:

```json title="package.json"
{
  "scripts": {
    "build": "rspack build",
    "dev": "rspack dev",
    "start": "node dist/main.js"
  }
}
```

- `dev`: Runs Rspack Dev Server, writes the server bundle to disk, and starts `dist/main.js`.
- `build`: Creates a production bundle without the HMR polling entry.
- `start`: Runs the production bundle with Node.js.

## Configure TypeScript decorators

NestJS uses decorators such as `@Module()`, `@Controller()`, `@Injectable()`, and `@Get()`. Configure `builtin:swc-loader` so SWC can parse these decorators and emit the metadata NestJS needs:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.ts$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              parser: {
                decorators: true,
              },
              transform: {
                legacyDecorator: true,
                decoratorMetadata: true,
              },
            },
          },
        },
      },
    ],
  },
};
```

If your project also runs `tsc`, keep `experimentalDecorators` and `emitDecoratorMetadata` enabled in `tsconfig.json` so TypeScript and Rspack use the same decorator assumptions:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}
```

## Configure development HMR

Add `@rspack/core/hot/poll` only in development. If it is included in the production bundle, the Node.js application will fail at runtime because HMR is not available in build mode:

```js title="rspack.config.mjs"
export default {
  entry: {
    main:
      process.env.NODE_ENV === 'production'
        ? './src/main.ts'
        : ['@rspack/core/hot/poll?100', './src/main.ts'],
  },
};
```

Add HMR handling to the NestJS bootstrap file. This closes the old application instance before accepting the updated module:

```ts title="src/main.ts"
declare const module: any;

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
  if (module.hot) {
    module.hot.accept();
    module.hot.dispose(() => app.close());
  }
}

bootstrap();
```

See [Node.js - Configure development HMR](/guide/integrations/node.md#configure-development-hmr) for the shared Rspack entry, `writeToDisk`, `RunScriptWebpackPlugin`, and externals allowlist settings used with this bootstrap code. If your project needs ESM output, see [Node.js - Use ESM output](/guide/integrations/node.md#use-esm-output).

## Configure production minification

When minifying a NestJS server bundle, keep class names and function names. NestJS can rely on stable class and handler references through metadata reflection and execution context APIs.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  optimization: {
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin({
        minimizerOptions: {
          compress: {
            keep_classnames: true,
            keep_fnames: true,
          },
          mangle: {
            keep_classnames: true,
            keep_fnames: true,
          },
        },
      }),
    ],
  },
};
```

## Native node modules

If a NestJS dependency includes a Node.js native addon (`.node` module), follow [Node.js - Native node modules](/guide/integrations/node.md#native-node-modules) to emit the addon with `asset/resource` and let Node.js load it at runtime.



---
url: /guide/integrations/solid.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Solid

## How to use

Rspack provides two solutions to support Solid:

- **Use Rsbuild**: Rsbuild provides out-of-the-box support for Solid, allowing you to quickly create a Solid project. See [Rsbuild - Solid](https://rsbuild.rs/guide/framework/solid) for details.
- **Manually configure Rspack**: You can refer to the current document to manually add configurations for Solid.

## Configure Solid

Thanks to the good compatibility of Rspack with the babel-loader, it is very easy to use Solid in Rspack. All you need is babel-loader and Solid babel preset. Rspack provides Solid [example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/solid) for reference.

```js title="rspack.config.mjs"
import { defineConfig } from '@rspack/cli';

export default defineConfig({
  entry: {
    main: './src/index.jsx',
  },
  module: {
    rules: [
      {
        test: /\.jsx$/,
        use: [
          {
            loader: 'babel-loader',
            options: {
              presets: ['solid'],
              plugins: ['solid-refresh/babel'],
            },
          },
        ],
      },
    ],
  },
});
```



---
url: /guide/integrations/svelte.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Svelte

## How to use

Rspack provides two solutions to support Svelte:

- **Use Rsbuild**: Rsbuild provides out-of-the-box support for Svelte, allowing you to quickly create a Svelte project. See ["Rsbuild - Svelte"](https://rsbuild.rs/guide/framework/svelte) for details.
- **Manually configure Rspack**: You can refer to the current document to manually add configurations for Svelte.

## Configure svelte-loader

Thanks to the good compatibility of Rspack with the [svelte-loader](https://github.com/sveltejs/svelte-loader), it is very easy to use Svelte in Rspack. All you need is to configure svelte-loader. Rspack provides Svelte [example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/svelte) for reference.

```js title="rspack.config.mjs"
import path from 'node:path';
import { defineConfig } from '@rspack/cli';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);

export default defineConfig({
  entry: {
    main: './src/main.ts',
  },
  resolve: {
    alias: {
      svelte: path.dirname(require.resolve('svelte/package.json')),
    },
    extensions: ['.mjs', '.js', '.ts', '.svelte'],
    mainFields: ['svelte', 'browser', 'module', 'main'],
  },
  module: {
    rules: [
      {
        test: /\.svelte$/,
        use: [
          {
            loader: 'svelte-loader',
            options: {
              compilerOptions: {
                dev: !prod,
              },
              emitCss: prod,
              hotReload: !prod,
              preprocess: sveltePreprocess({ sourceMap: !prod, postcss: true }),
            },
          },
        ],
      },
    ],
  },
});
```



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

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Rstest

[Rstest](https://rstest.rs/) is a JavaScript testing framework powered by Rspack. It runs tests through Rspack's bundling pipeline, and its official adapter can reuse module resolution, transforms, and plugins from an existing Rspack configuration.

This guide covers unit testing with Rstest and end-to-end testing with [`@rstest/playwright`](https://rstest.rs/guide/advanced/playwright).

## Set up Rstest

### Create a new project

When creating a project, follow the [Quick start](/guide/start/quick-start.md) guide and select **Rstest - testing** in the prompts. The generated project includes the Rstest dependencies, configuration, and test scripts.

### Add Rstest to an existing project

Install Rstest and the official Rspack adapter as development dependencies:


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

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

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

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

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

Then add scripts for running tests and watching for changes:

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

### Reuse the Rspack configuration

Create an `rstest.config.ts` file in the project root and use `withRspackConfig` to reuse the existing Rspack configuration:

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

export default defineConfig({
  extends: withRspackConfig(),
});
```

The adapter loads `rspack.config.ts`, maps compatible Rspack options to Rstest, and merges them with the rest of the Rstest configuration.

:::note

By default, the adapter looks for the Rspack configuration in `process.cwd()`. It also disables Rstest's built-in CSS plugins so that the Rspack CSS configuration takes effect. For monorepos, custom configuration paths, named configurations, and complete mapping details, see [Rstest - Rspack integration](https://rstest.rs/guide/integration/rspack).

:::

## Unit testing

Unit tests verify individual modules and functions in isolation.

### Write tests

Create a source file and a corresponding test file:

```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('adds two numbers correctly', () => {
  expect(add(1, 2)).toBe(3);
  expect(add(-1, 1)).toBe(0);
});
```

### Run tests

```bash
# Run all tests
pnpm run test

# Run tests in watch mode
pnpm run test:watch

# Run tests whose names match a pattern
pnpm run test -- -t 'adds two numbers'
```

See the [Rstest documentation](https://rstest.rs/guide/) for test APIs, mocking, snapshots, coverage, and other features.

## End-to-end testing

[`@rstest/playwright`](https://rstest.rs/guide/advanced/playwright) is Rstest's Playwright integration. It provides Playwright-style assertions and fixtures for testing local, preview, or deployed applications while sharing Rstest's runner, configuration, and reporting workflow with unit tests.

:::tip

If you need the full Playwright Test runner and its `playwright.config.ts` configuration model, use [native Playwright](https://playwright.dev/docs/test-intro).

:::

### Install `@rstest/playwright`

Install the Rstest integration and the Playwright browser automation runtime:


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

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

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

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

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

Then install the Chromium browser binary:

```bash
pnpm exec playwright install chromium
```

### Test a running application

Import `test` and `expect` from `@rstest/playwright` and navigate to the application served by Rspack:

```ts title="tests/home.e2e.test.ts"
import { expect, test } from '@rstest/playwright';

test('home page', async ({ page }) => {
  await page.goto('http://localhost:3000');
  await expect(page).toHaveTitle(/Rspack/);
});
```

### Test local build output

Use Rstest's `serve` fixture to start a static application from local files. The server is cleaned up automatically after the test:

```ts title="tests/home.e2e.test.ts"
import { expect, test } from '@rstest/playwright';

test('home page', async ({ page, serve }) => {
  const { url } = await serve('./dist/index.html');

  await page.goto(url);
  await expect(page.locator('h1')).toHaveText('Home');
});
```

End-to-end tests use the Rstest runner, so they can live alongside unit tests and run with the same command:

```bash
pnpm run test
```

For more fixtures, browser options, tracing, and debugging, see [Rstest - Playwright](https://rstest.rs/guide/advanced/playwright).



---
url: /guide/optimization/production.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Production optimization

## Code splitting

Rspack supports code splitting, which allows splitting the code into other chunks. You have the full control about size and number of generated assets, which allow you to gain performance improvements in loading time.

See [Code splitting](/guide/optimization/code-splitting.md) for more details.

## Tree shaking

Rspack supports tree shaking, a terminology widely used within the JavaScript ecosystem defined as the removal of unused code, commonly referred to as "dead code".

See [Tree shaking](/guide/optimization/tree-shaking.md) for more details.

## Minification

During the production build, Rspack uses the built-in minimizer to minify JavaScript and CSS code by default.

If you need to customize the minification options, you can use [SwcJsMinimizerRspackPlugin](/plugins/swc-js-minimizer-rspack-plugin.md) and [LightningCssMinimizerRspackPlugin](/plugins/lightning-css-minimizer-rspack-plugin.md) for configuration.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  optimization: {
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin({
        // JS minimizer configuration
      }),
      new rspack.LightningCssMinimizerRspackPlugin({
        // CSS minimizer configuration
      }),
    ],
  },
};
```

If the built-in minimizer cannot meet your needs, you can also use [optimization.minimizer](/config/optimization.md#optimizationminimizer) to set custom minimizers.



---
url: /guide/optimization/code-splitting.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Code splitting

Rspack supports code splitting, letting you divide your code into separate chunks. You have full control over the size and number of generated assets to improve loading performance.

Here, a Chunk refers to a resource that a browser needs to load.

## Dynamic import

Rspack uses the [import()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) syntax that conforms to the ECMAScript proposal for dynamic imports.

In `index.js`, we dynamically import two modules through `import()`, separating them into a new chunk.

```js title=index.js
import('./foo.js');
import('./bar.js');
```

```js title=foo.js
import './shared.js';
console.log('foo.js');
```

```js title=bar.js
import './shared.js';
console.log('bar.js');
```

Building this project produces three chunks: `src_bar_js.js`, `src_foo_js.js`, and `main.js`. Inspecting them shows that `shared.js` exists in both `src_bar_js.js` and `src_foo_js.js`. We will cover how to remove duplicated modules later.

:::tip

1. Refer to [Module methods - Dynamic import()](/api/runtime-api/module-methods.md#dynamic-import) for the detailed dynamic import API, as well as how to use dynamic expressions and magic comments in dynamic import.
2. Although `shared.js` exists in two chunks, it is executed only once, so you don't have to worry about multiple instances.
3. Use the [output.asyncChunks option](/config/output.md#outputasyncchunks) to control whether dynamically imported modules generate independent async chunks.

:::

## Entry point

This is the simplest and most intuitive way to split the code, but it requires manual configuration. Let's start by looking at how to create multiple Chunks from multiple entry points.

```js title="rspack.config.mjs"
export default {
  mode: 'development',
  entry: {
    index: './src/index.js',
    another: './src/another-module.js',
  },
  stats: 'normal',
};
```

```js title=index.js
import './shared';
console.log('index.js');
```

```js title=another-module.js
import './shared';
console.log('another-module');
```

This will yield the following build result:

```
...
     Asset      Size   Chunks             Chunk Names
another.js  1.07 KiB  another  [emitted]  another
  index.js  1.06 KiB    index  [emitted]  index
Entrypoint another = another.js
Entrypoint index = index.js
[./src/index.js] 41 bytes {another} {index}
[./src/shared.js] 24 bytes {another} {index}
```

Similarly, examining the output shows that they all include the repeated `shared.js`.

## Configuring chunk splitting

The splitting approach above is intuitive, but most modern browsers support concurrent network requests. If we split a single-page application into one chunk per page, the browser still has to fetch a large chunk when users switch pages, which wastes that concurrency. Instead, we can break the chunk into smaller ones and request those smaller chunks at the same time to use the browser's network capacity more effectively.

Rspack defaults to splitting files in the `node_modules` directory and duplicate modules, extracting these modules from their original Chunk into a separate new Chunk. Why does `shared.js` still appear repeatedly in our example above? The `shared.js` file here is very small, and splitting such a small module into its own Chunk can actually slow down loading.

We can configure the minimum split size through [splitChunks.minSize](/plugins/split-chunks-plugin.md#splitchunksminsize) to 0 to allow `shared.js` to be extracted on its own.

```diff title="rspack.config.mjs"
export default {
  entry: {
    index: './src/index.js',
  },
+  optimization: {
+    splitChunks: {
+      minSize: 0,
+    }
+  }
};
```

After rebuilding, you will find that `shared.js` has been extracted separately, and there is an additional Chunk in the output that contains only `shared.js`.

If `shared.js` still appears duplicated after lowering [`splitChunks.minSize`](/plugins/split-chunks-plugin.md#splitchunksminsize), check [`splitChunks.minSizeReduction`](/plugins/split-chunks-plugin.md#splitchunksminsizereduction), [`splitChunks.minChunks`](/plugins/split-chunks-plugin.md#splitchunksminchunks), and request limits such as [`splitChunks.maxAsyncRequests`](/plugins/split-chunks-plugin.md#splitchunksmaxasyncrequests) / [`splitChunks.maxInitialRequests`](/plugins/split-chunks-plugin.md#splitchunksmaxinitialrequests) before reaching for [`splitChunks.cacheGroups.{cacheGroup}.enforce`](/plugins/split-chunks-plugin.md#splitchunkscachegroupscachegroupenforce).

If you want sufficiently large candidates to keep splitting after hitting those request limits, prefer [`splitChunks.enforceSizeThreshold`](/plugins/split-chunks-plugin.md#splitchunksenforcesizethreshold) before forcing an entire cache group with `enforce`.

For most production applications, a good baseline is:

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      chunks: 'all',
    },
  },
};
```

while keeping the default cache groups. This usually deduplicates both initial and async chunks while still allowing the runtime to fetch only the chunks reachable from the current page.

### Force the splitting of certain modules

We can use [`optimization.splitChunks.cacheGroups.{cacheGroup}.name`](/plugins/split-chunks-plugin.md#splitchunkscachegroupscachegroupname) to force specific modules to be grouped into the same chunk, for example, with the following configuration:

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      cacheGroups: {
        someLib: {
          test: /\/some-lib\//,
          name: 'lib',
        },
      },
    },
  },
};
```

With the above configuration, all files that include the `some-lib` directory in their path can be extracted into a single Chunk named `lib`. If the modules in `some-lib` are rarely changed, this Chunk will consistently hit the user's browser cache, thus a well-considered configuration like this can increase the cache hit rate.

However, separating `some-lib` into an independent Chunk can also have downsides. Suppose a Chunk only depends on a very small file within `some-lib`, but since all files of `some-lib` are split into a single Chunk, this Chunk has to rely on the entire `some-lib` Chunk, resulting in a larger load volume. Therefore, when using `cacheGroups.{cacheGroup}.name`, careful consideration is needed.

More importantly, `name` is not just a filename choice. A fixed `name` can force different split candidates to be merged into the same shared chunk, which may cause a route to fetch modules from unrelated dependency chains. For most projects, avoid adding `name` unless you intentionally want one shared asset and accept the tradeoff.

This tradeoff is about chunk grouping and network fetch boundaries. It does not change JavaScript execution order, and it is unrelated to tree shaking. CSS is a separate caveat: in extracted CSS flows, splitChunks can affect final CSS order. See the [SplitChunksPlugin documentation](/plugins/split-chunks-plugin.md#faq) for details.

Here is an example showing the effect of the `name` configuration of cacheGroup.

![](https://assets.rspack.rs/rspack/assets/rspack-splitchunks-name-explain.png)

## Prefetching/Preloading modules

Adding these inline directives to your imports allows Rspack to output resource hints that tell the browser that:

- **prefetch**: resource is probably needed for some navigation in the future
- **preload**: resource will also be needed during the current navigation

An example of this is having a `HomePage` component, which renders a `LoginButton` component which then on demand loads a `LoginModal` component after being clicked.

```js title=LoginButton.js
//...
import(/* webpackPrefetch: true */ './path/to/LoginModal.js');
```

This will result in `<link rel="prefetch" href="login-modal-chunk.js">` being appended in the head of the page, which will instruct the browser to prefetch in idle time the `login-modal-chunk.js` file.

:::info
Rspack will add the prefetch hint once the parent chunk has been loaded.
:::

Preload directive has a bunch of differences compared to prefetch:

- A preloaded chunk starts loading in parallel to the parent chunk. A prefetched chunk starts after the parent chunk finishes loading.
- A preloaded chunk has medium priority and is instantly downloaded. A prefetched chunk is downloaded while the browser is idle.
- A preloaded chunk should be instantly requested by the parent chunk. A prefetched chunk can be used anytime in the future.
- Browser support is different.

An example of this can be having a `Component` which always depends on a big library that should be in a separate chunk.

Let's imagine a component `ChartComponent` which needs a huge `ChartingLibrary`. It displays a `LoadingIndicator` when rendered and instantly does an on demand import of `ChartingLibrary`:

```js title=ChartComponent.js
//...
import(/* webpackPreload: true */ 'ChartingLibrary');
```

When a page which uses the `ChartComponent` is requested, the charting-library-chunk is also requested via `<link rel="preload">`. Assuming the page-chunk is smaller and finishes faster, the page will be displayed with a `LoadingIndicator`, until the already requested `charting-library-chunk` finishes. This will give a little load time boost since it only needs one round-trip instead of two. Especially in high-latency environments.

:::info
Using webpackPreload incorrectly can actually hurt performance, so be careful when using it.
:::

Sometimes you need to have your own control over preload. For example, preload of any dynamic import can be done via async script. This can be useful in case of streaming server side rendering.

```js
const lazyComp = () =>
  import('DynamicComponent').catch((error) => {
    // Do something with the error.
    // For example, we can retry the request in case of any net error
  });
```

If the script loading will fail before Rspack starts loading of that script by itself (Rspack creates a script tag to load its code, if that script is not on a page), that catch handler won't start till chunkLoadTimeout is not passed. This behavior can be unexpected. But it's explainable — Rspack can not throw any error, cause Rspack doesn't know, that script failed. Rspack will add onerror handler to the script right after the error has happen.

To prevent such problem you can add your own onerror handler, which removes the script in case of any error:

```html
<script
  src="https://example.com/dist/dynamicComponent.js"
  async
  onerror="this.remove()"
></script>
```

In that case, errored script will be removed. Rspack will create its own script and any error will be processed without any timeouts.


This page is adapted from [webpack documentation](https://webpack.js.org/guides/code-splitting/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /guide/optimization/tree-shaking.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Tree shaking

Rspack supports [tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking), a term commonly used in the JavaScript ecosystem for removing unused code, also known as "dead code". Dead code occurs when module exports are unused and have no side effects, allowing them to be safely removed to reduce bundle size.

## What is tree shaking

Think of your application as a tree. The source code and libraries you actually use are the green, living leaves. Dead code is like the brown, dead leaves consumed by autumn. To remove the dead leaves, you shake the tree and they fall off.

Rspack doesn't directly remove dead code—it marks unused exports as potential "dead code". Minification tools then recognize and process these markers. If [minimize](/config/optimization.md#optimizationminimize) is disabled, you won't see any actual code removal.

:::tip What is dead code
[Dead code](https://en.wikipedia.org/wiki/Dead_code) is code that's no longer executed, typically due to refactoring, optimization, or logical errors. It may be a remnant from previous versions or code that never executes under any condition.
:::

## Prerequisites

To effectively leverage tree shaking, you need to:

- Set Rspack's [mode](/config/mode.md) to `production` to enable tree shaking optimizations.
  - In production builds, `mode` defaults to `production`.
- Use ES module syntax (`import` and `export`).
  - When using compilers like SWC or Babel, ensure they don't transform ES modules to CommonJS.
  - For example, in [@babel/preset-env](https://babeljs.io/docs/en/babel-preset-env), set `modules` to `false`.

## Configurations

When [mode](/config/mode.md) is set to `production`, Rspack enables several tree shaking optimizations:

- [usedExports](/config/optimization.md#optimizationusedexports): Detects which module exports are used, enabling removal of unused exports.
- [sideEffects](/config/optimization.md#optimizationsideeffects): Analyzes modules for side effects. Modules without side effects can be further optimized through re-exports.
- [providedExports](/config/optimization.md#optimizationprovidedexports): Analyzes all exports and tracks their re-export sources.
- [innerGraph](/config/optimization.md#optimizationinnergraph): Tracks variable usage to more accurately determine if exports are actually used.

The following examples illustrate how these options work. For clarity, we'll use simplified code to demonstrate code removal.

Let's look at an example with `src/main.js` as the entry point:

```js title='src/main.js'
import { foo } from './util.js';

console.log(foo);
// `bar` is not used
```

```js title='src/util.js'
export const foo = 1;
export const bar = 2;
```

In this example, `bar` from `util.js` is unused. In `production` mode, Rspack enables [usedExports](/config/optimization.md#optimizationusedexports) by default, which detects which exports are used. Unused exports like `bar` are removed. The final output looks like this:

```js title='dist/main.js'
const foo = 1;

console.log(foo);
```

## Side effects analysis

In `production` mode, Rspack also analyzes modules for side effects. If all exports from a module are unused and the module has no side effects, the entire module can be removed. Let's modify the previous example:

```diff title='src/main.js'
import { foo } from './util.js';

- console.log(foo);
// `bar` is not used
```

In this case, none of the exports from `util.js` are used, and it’s analyzed as having no side effects, permitting the entire deletion of `util.js`.

You can manually indicate whether a module has side effects via `package.json` or `module.rules`. To do this, enable [optimization.sideEffects](/config/optimization.md#optimizationsideeffects).

In `package.json`, you can use `true` or `false` to indicate whether all modules in the package have side effects.

```json title="package.json"
{
  "name": "package",
  "version": "1.0.0",
  "sideEffects": false
}
```

This `package.json` indicates that all modules in this package are side-effect-free.

You can also use glob patterns to specify which modules have side effects. Unmatched modules are automatically treated as side-effect-free. If you manually mark side effects, ensure all unmarked modules truly have no side effects.

```json title="package.json"
{
  "name": "package",
  "version": "1.0.0",
  "sideEffects": ["./src/main.js", "*.css"]
}
```

This `package.json` indicates that only `./src/main.js` and all `.css` files have side effects, while all other modules are side-effect-free.

## Re-export analysis

Re-exports are common in development. However, a module might import many other modules while only needing a few exports. Rspack optimizes this by allowing consumers to access the actual exported modules directly. Consider this re-export example:

```js title='src/main.js'
import { value } from './re-exports.js';
console.log(value);
```

```js title='src/re-exports.js'
export * from './value.js';
export * from './other.js'; // this can be removed if `other.js` does not have any side effects
```

```js title='src/value.js'
export const value = 42;
export const foo = 42; // not used
```

Rspack enables [providedExports](/config/optimization.md#optimizationprovidedexports) by default, which analyzes all exports from a re-exporting module and identifies their origins.

If `src/re-exports.js` has no side effects, Rspack can convert the import in `src/main.js` to import directly from `src/value.js`:

```diff title='src/main.js'
- import { value } from './re-exports.js';
+ import { value } from './value.js';
console.log(value);
```

This allows Rspack to completely skip the `src/re-exports.js` module.

By analyzing all re-exports in `src/re-exports.js`, Rspack determines that `foo` from `src/value.js` is unused and removes it from the final output.

## Variable transmission

Sometimes exports are imported but not actually used. For example:

```js title='src/main.js'
import { foo } from './value.js';

function log() {
  console.log(foo);
} // `log` is not used

const bar = foo; // `foo` is not used
```

In this scenario, even though the `log` function and the `bar` variable depend on `foo`, neither is used, so `foo` is considered dead code and removed.

When [innerGraph](/config/optimization.md#optimizationinnergraph) is enabled (the default in `production` mode), Rspack can track variable usage across modules to achieve precise code optimization.

```js title='src/main.js'
import { value } from './bar.js';
console.log(value);
```

```js title='src/bar.js'
import { foo } from './foo.js';
const bar = foo;
export const value = bar;
```

```js title='src/foo.js'
export const foo = 42;
```

Since `value` is used, the `foo` it depends on is retained.

## Pure annotation

Use the [`/*#__PURE__*/`](https://github.com/javascript-compiler-hints/compiler-notations-spec/blob/main/pure-notation-spec.md) annotation to tell Rspack that a function call is side-effect-free (pure). Place it before function calls to mark them as having no side effects.

When an unused variable's initial value is marked as side-effect-free (pure), it's treated as dead code and removed by the minimizer.

```js
/*#__PURE__*/ double(55);
```

:::tip

- Function arguments aren't marked by the annotation and may need to be marked individually.
- This behavior is enabled when [optimization.innerGraph](/config/optimization.md#optimizationinnergraph) is set to true.

:::

## NO\_SIDE\_EFFECTS annotation

`/*#__NO_SIDE_EFFECTS__*/` is a feature that follows the community [JavaScript Compiler Hints Spec](https://github.com/javascript-compiler-hints/compiler-notations-spec/blob/main/no-side-effects-notation-spec.md). Unlike `/*#__PURE__*/` which marks call sites, `/*#__NO_SIDE_EFFECTS__*/` is used to mark **function definitions**, declaring that the function has no side effects when called with arguments.

### Configuration

This feature is currently experimental and controlled by `experiments.pureFunctions`, which is enabled by default in production mode. It also depends on [optimization.sideEffects](/config/optimization.md#optimizationsideeffects) being `true` (`sideEffects` is `true` by default in production mode):

```js title="rspack.config.mjs"
export default {
  experiments: {
    pureFunctions: true,
  },
};
```

### Usage

You can place this annotation before function declarations, function expressions, arrow functions, or export statements, check [spec](https://github.com/javascript-compiler-hints/compiler-notations-spec/blob/main/no-side-effects-notation-spec.md) for details:

```js
/*#__NO_SIDE_EFFECTS__*/
function foo() {
  console.log('foo');
}

/*#__NO_SIDE_EFFECTS__*/
const bar = () => {
  console.log('bar');
};

/*#__NO_SIDE_EFFECTS__*/
export default function baz() {}

/*#__NO_SIDE_EFFECTS__*/
export function baz() {}
```

If a function is marked as side-effect-free and its return value is unused, Rspack can safely remove the call. Compared to `/*#__PURE__*/`, the advantage is that you only need to mark it once at the definition, and all call sites will benefit.

## pureFunctions

`pureFunctions` lets you manually mark top-level identifiers in matched modules as side-effect-free for pure-function-based tree shaking. Each name must resolve to a top-level binding in the module — a function/class/variable declaration, an `import` specifier, or an export alias of one. This is useful for third-party libraries where source code cannot be modified, such as packages in `node_modules`, and for asserting that a particular import is pure on the consumer side.

For configuration details, see [`experiments.pureFunctions`](/config/experiments.md#experimentspurefunctions) and [`module.parser.javascript.pureFunctions`](/config/module-parser.md#javascriptpurefunctions).

:::warning
This option is experimental and only takes effect when `experiments.pureFunctions` is enabled, which is the default in production mode.
:::

:::note
For default exports configured on the source module, use `default` as the name.
:::

For business source code where modification is possible, it is recommended to use the `/*#__NO_SIDE_EFFECTS__*/` annotation.

### Usage

This option is configured in `module.rules[i].parser`:

```js title="rspack.config.mjs"
export default {
  experiments: {
    pureFunctions: true,
  },
  module: {
    rules: [
      // Mark exports of a third-party library as pure.
      {
        test: /node_modules\/some-library\/index.js/,
        parser: {
          pureFunctions: ['isString', 'default'],
        },
      },
      // Or mark the import on the consumer side.
      {
        test: /src\/styles\.js$/,
        parser: {
          pureFunctions: ['cva'],
        },
      },
    ],
  },
};
```

Rspack validates each configured name against the matched module. If a configured name does not appear as a top-level binding in the module, Rspack emits a warning.



---
url: /guide/diagnostics/analysis.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Bundle analysis

## Rsdoctor's bundle analysis

[Rsdoctor](/guide/diagnostics/use-rsdoctor.md) provides the `Bundle Size` module, which is mainly used to analyze the information of the outputs of Rspack, including the size of resources, duplicate packages, and module reference relationships:

- **Bundle Overview**: Displays the total number and size of artifacts, as well as the number and size of each file type. It also shows the duplicate packages and their reference chains.
- **Bundle Analysis Module**: Analyzes the size and code information of the build artifacts' resources (**Assets**) and the included **Modules**. In this module, you can view the **actual code size of modules after packaging** in the Assets, as well as the original code or **packaged code segments** and **module reference relationships**.

![](https://assets.rspack.rs/others/assets/rsdoctor/bundle-size.jpg)
Click on the **"Bundle Size"** option in the navigation bar to view the Bundle analysis report. You can see more details from this page: [Bundle Size](https://rsdoctor.rs/guide/usage/bundle-size)

### Reduce duplicate dependencies

Bundle size optimization is an important part in production build because it directly affects the user experience of online users. In this document, we will introduce some common bundle size optimization methods in Rspack.

It is common for web projects to bundle multiple versions of third-party dependencies. Duplicate dependencies can lead to increased bundle size and slower build speed.

- Detect duplicate dependencies

You can use [Rsdoctor](https://rsdoctor.rs) to detect whether there are duplicate dependencies in the project. Rsdoctor will analyze during the build process, find any duplicate bundled dependencies and display them visually:

![](https://assets.rspack.rs/others/assets/rsdoctor/overall-alerts.jpg)

For more details, see [Rsdoctor - Duplicate Dependency Problem](https://rsdoctor.rs/blog/topic/duplicate-pkg-problem).

## bundle-stats and statoscope

You can also generate a `stats.json` file for further analysis with other bundle analysis tools like [bundle-stats](https://github.com/relative-ci/bundle-stats) or [statoscope](https://github.com/statoscope/statoscope):

```sh
$ rspack build --json stats.json
```



---
url: /guide/diagnostics/profile.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Build performance profiling

This chapter introduces some common performance bottlenecks and performance profile methods for Rspack.

## Analysis with Rsdoctor

[Rsdoctor](https://rsdoctor.rs/) is a build analyzer that can visually display the build process, such as compilation time, code changes before and after compilation, module reference relationships, duplicate modules, etc.

Please refer to [Use Rsdoctor](/guide/diagnostics/use-rsdoctor.md) for more information.

## Rspack profile

The Rspack CLI supports the use of the `RSPACK_PROFILE` environment variable for build performance profile.

```sh
RSPACK_PROFILE=ALL rspack build
```

This command will generate a `.rspack-profile-${timestamp}-${pid}` folder. By default, it contains the `rspack.log` file, which is generated by Rspack based on [tracing](https://github.com/tokio-rs/tracing) and records build timing information as JSON Lines.

`@rspack-debug/core` is a diagnostic variant of `@rspack/core` that includes extra debugging and tracing capabilities. If you use `@rspack-debug/core` and set `RSPACK_TRACE_LAYER=perfetto`, the profile directory will contain `rspack.pftrace`, which can be viewed using [ui.perfetto.dev](https://ui.perfetto.dev/).

> See [Tracing](/contribute/development/tracing.md) for more information.

## Performance bottlenecks

Although Rspack itself provides good build performance, the use of some JavaScript loaders and plugins in Rspack can slow down the build performance, especially on large projects.

Some of these issues can be resolved with Rspack's built-in high performance alternatives, while others can be identified and optimized using performance analysis tools.

Here are some common cases:

### babel-loader

[babel-loader](https://github.com/babel/babel-loader) compiles JavaScript and TypeScript code using Babel. You can replace Babel with the faster SWC. Rspack comes with a built-in [builtin:swc-loader](/guide/features/builtin-swc-loader.md), which is the Rust version of `swc-loader` and is intended to provide better performance.

If you need to use some Babel plugins for custom transformations, configure babel-loader with [rules\[\].include](/config/module-rules.md#rulesinclude) to match as few files as possible to reduce the Babel compilation overhead.

### postcss-loader

[postcss-loader](https://github.com/postcss/postcss-loader) compiles CSS code based on PostCSS, which is often used with PostCSS plugins to downgrade CSS syntax, add vendor prefixes, etc. You can replace PostCSS with the faster Lightning CSS by using Rspack's built-in [builtin:lightningcss-loader](/guide/features/builtin-lightningcss-loader.md).

### terser-webpack-plugin

[terser-webpack-plugin](https://github.com/webpack/terser-webpack-plugin) minifies JavaScript code based on Terser. You can replace Terser with the faster SWC minimizer by using Rspack's built-in [SwcJsMinimizerRspackPlugin](/plugins/swc-js-minimizer-rspack-plugin.md).

### css-minimizer-webpack-plugin

[css-minimizer-webpack-plugin](https://github.com/webpack/css-minimizer-webpack-plugin) minifies CSS code based on tools like cssnano. You can replace cssnano with the faster Lightning CSS minimizer by using Rspack's built-in [LightningCssMinimizerRspackPlugin](/plugins/lightning-css-minimizer-rspack-plugin.md).

### less-loader

[less-loader](https://github.com/webpack/less-loader) compiles `.less` files based on Less. Since Less currently lacks an officially implemented high performance alternative, it is recommended to use [sass-loader](https://github.com/webpack/sass-loader) and [sass-embedded](https://www.npmjs.com/package/sass-embedded) instead. `sass-embedded` is a JavaScript wrapper for Sass's native Dart executable that provides excellent performance.

### html-webpack-plugin

[html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) performs poorly when generating large numbers of HTML files. The [HtmlRspackPlugin](/plugins/html-rspack-plugin.md) implemented in Rust by Rspack can provide better performance.

### ts-checker-rspack-plugin

When using [ts-checker-rspack-plugin](https://github.com/rspack-contrib/ts-checker-rspack-plugin), TypeScript 7 or later is recommended to enable the native type checker and improve type-checking performance on large projects. See the [plugin README](https://github.com/rspack-contrib/ts-checker-rspack-plugin#typescript-7-support) for details.

## Blocking thread pool size

Rspack internally uses a dedicated thread pool to handle blocking operations such as file system reads and writes, preventing the main thread from being blocked.

By default, the pool size is set to `4`, matching Node.js's [libuv](https://docs.libuv.org/en/v1.x/threadpool.html) behavior, which provides stable performance across most development and CI environments.

If your build environment uses high-speed storage, you can adjust the thread count via the `RSPACK_BLOCKING_THREADS` environment variable to improve parallelism and potentially reduce build time, for example:

```bash
# Need to install cross-env package to set environment variables
cross-env RSPACK_BLOCKING_THREADS=8 rspack build
```

After setting the variable, observe the build time to find the most suitable configuration.

On slower or high-latency file systems, it's recommended to keep the default value or even lower it to avoid thread contention.

## Working thread pool size

Rspack internally uses a Tokio thread pool and Rayon thread pool to handle CPU bound tasks (Tokio for async tasks and Rayon for sync tasks). By default, Tokio and Rayon automatically determines the number of worker threads based on the number of CPU cores available.

If it consumes too much CPU resources during the build process, you can limit the number of worker threads by setting the `TOKIO_WORKER_THREADS` and `RAYON_NUM_THREADS` environment variable, for example:

```bash
# Need to install cross-env package to set environment variables
cross-env TOKIO_WORKER_THREADS=4 RAYON_NUM_THREADS=4 rspack build
```

Be aware that setting this value too low may lead to longer build times. After setting the variable, observe the build time to find the most suitable configuration.



---
url: /guide/diagnostics/use-rsdoctor.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Use Rsdoctor

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

Rsdoctor is committed to being a one-stop, intelligent build analyzer that makes the build process transparent, predictable, and optimizable through visualization and smart analysis, helping development teams precisely identify bottlenecks, optimize performance, and improve engineering quality.

If you need to debug the build outputs or build process, you can use Rsdoctor for troubleshooting.

## How to use

In an Rspack project, you can enable Rsdoctor by following these steps:

1. Install the `@rsdoctor/rspack-plugin` plugin:


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

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

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

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

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

2. Register the `RsdoctorRspackPlugin` plugin in the [plugins](/config/plugins.md) option of Rspack:

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

export default {
  plugins: [
    // Register the plugin only when RSDOCTOR is true, as the plugin increases build time
    process.env.RSDOCTOR &&
      new RsdoctorRspackPlugin({
        // plugin options
      }),
  ],
};
```

3. Add the `RSDOCTOR=true` variable before the build command:

```bash
# dev
RSDOCTOR=true rspack serve

# build
RSDOCTOR=true rspack 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:

```bash
# dev
cross-env RSDOCTOR=true rspack serve

# build
cross-env RSDOCTOR=true rspack build
```

Rsdoctor will open the build analysis page after the build is complete. For complete features, please refer to [Rsdoctor documentation](https://rsdoctor.rs/).

## Configure Rsdoctor

See the [Options](https://rsdoctor.rs/config/options/options) documentation of Rsdoctor to configure the options of the RsdoctorRspackPlugin.

## More features

See the [Rsdoctor features](https://rsdoctor.rs/guide/start/features) to learn about all the features of Rsdoctor.



---
url: /guide/migration/rspack_1.x.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Upgrading from v1 to v2

This document lists the breaking changes from Rspack 1.x to 2.0.

- For more details, see [Breaking changes in Rspack 2.0](https://github.com/web-infra-dev/rspack/discussions/9270)
- For Rsbuild users, see [Rsbuild - Upgrading from v1 to v2](https://v2.rsbuild.rs/guide/upgrade/v1-to-v2)

## Using Agent Skills

If your Coding Agent supports Skills, install the [rspack-v2-upgrade](https://github.com/rstackjs/agent-skills#rspack-v2-upgrade) skill to help with the migration.

```bash
npx skills add rstackjs/agent-skills --skill rspack-v2-upgrade
```

After installation, let the agent guide you through the upgrade.

## Upgrade Rspack to v2

- Upgrade `@rspack/core` to the 2.0 release.
- If you use `@rspack/cli`, `@rspack/dev-server`, or `@rspack/plugin-react-refresh`, upgrade them to the latest compatible versions so they stay in sync with `@rspack/core`. For example:

```json
{
  "devDependencies": {
    "@rspack/core": "^2.0.0",
    "@rspack/cli": "^2.0.0",
    "@rspack/dev-server": "^2.0.0",
    "@rspack/plugin-react-refresh": "^2.0.0"
  }
}
```

## Upgrade Node.js

Rspack 2.0 requires a minimum Node.js version of **20.19+** or **22.12+**, and Node.js 18 is no longer supported.

## Pure ESM packages

`@rspack/core`, `@rspack/cli`, `@rspack/dev-server` and `@rspack/plugin-react-refresh` are now published as **pure ESM** packages, with CommonJS builds removed.

In Node.js 20 and later, the runtime natively supports loading ESM modules via [require(esm)](https://nodejs.org/api/modules.html#loading-ecmascript-modules-using-require), so for most projects that use Rspack through its JavaScript API, this change should have no practical impact and does not require code changes.

> This does not affect Rspack's ability to build CommonJS output. All related build behavior and configuration remain unchanged.

## Dev server

[@rspack/dev-server](https://npmjs.com/package/@rspack/dev-server) 2.0 includes the following changes:

- `@rspack/cli` no longer depends on `@rspack/dev-server` by default, since some workflows do not require a dev server. When using the `rspack dev` or `rspack serve` commands, install `@rspack/dev-server` manually:


```sh [npm]
npm add @rspack/dev-server -D
```

```sh [yarn]
yarn add @rspack/dev-server -D
```

```sh [pnpm]
pnpm add @rspack/dev-server -D
```

```sh [bun]
bun add @rspack/dev-server -D
```

```sh [deno]
deno add npm:@rspack/dev-server -D
```

- Some [devServer](/config/dev-server.md) options have changed, including `devServer.proxy` and `devServer.watchFiles`. See the [upgrade guide](https://github.com/rstackjs/rspack-dev-server/blob/main/docs/migrate-v1-to-v2.md) for details.

`@rspack/dev-server` dependencies are now more streamlined and modernized:

- It introduces the new [@rspack/dev-middleware](https://github.com/rstackjs/rspack-dev-middleware) package to replace `webpack-dev-middleware`.
- It uses [connect-next](https://github.com/rstackjs/connect-next) instead of Express v4 as the default middleware framework.

## Bundle analysis

The built-in `webpack-bundler-analyzer` has been removed from `@rspack/cli`, and the `--analyze` flag is no longer available.

If you need to analyze bundle outputs, it is recommended to use [Rsdoctor](/guide/diagnostics/use-rsdoctor.md), which provides more powerful analysis capabilities.

## Module compilation changes

### Changed default value of module.parser.javascript.exportsPresence

The default value of [module.parser.javascript.exportsPresence](/config/module-parser.md#javascriptexportspresence) has been changed from `warn` to `error`. When detecting non-existent exports, an error will now be thrown directly instead of just a warning.

If you want to restore the old behavior, you can explicitly set it to `auto`:

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        exportsPresence: 'auto',
      },
    },
  },
};
```

### Removed module.parser.javascript.strictExportPresence

`module.parser.javascript.strictExportPresence` has been removed. You can use [module.parser.javascript.exportsPresence](/config/module-parser.md#javascriptexportspresence) to control the behavior when exports don't exist.

### Changed default value of module.parser.javascript.requireAlias

The default value of [module.parser.javascript.requireAlias](/config/module-parser.md#javascriptrequirealias) changed from `true` to `false`. If your code relies on renamed `require` calls being parsed and bundled, explicitly enable it:

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        requireAlias: true,
      },
    },
  },
};
```

### Disabled builtin:swc-loader reading .swcrc

In Rspack 2.0, `builtin:swc-loader` no longer supports reading `.swcrc` files. Move your SWC configuration into the loader options in `rspack.config.js`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        loader: 'builtin:swc-loader',
        options: {
          detectSyntax: 'auto',
          jsc: {
            transform: {
              react: {
                runtime: 'automatic',
              },
            },
          },
        },
      },
    ],
  },
};
```

### Removed builtin:swc-loader's rspackExperiments.collectTypeScriptInfo

The `rspackExperiments.collectTypeScriptInfo` option of `builtin:swc-loader` has been removed. Use [collectTypeScriptInfo](/guide/features/builtin-swc-loader.md#collecttypescriptinfo) to control TypeScript information collection:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.ts$/,
        loader: 'builtin:swc-loader',
        options: {
          collectTypeScriptInfo: {
            typeExports: true,
          },
        },
      },
    ],
  },
};
```

### Moved builtin:swc-loader's rspackExperiments.import

The `rspackExperiments.import` option of `builtin:swc-loader` has been moved to the top-level [transformImport](/guide/features/builtin-swc-loader.md#transformimport) option. `rspackExperiments.import` is still supported as a deprecated alias in Rspack 2.0, but you should migrate to `transformImport` to avoid future breakage:

```diff title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        loader: 'builtin:swc-loader',
        options: {
-         rspackExperiments: {
-           import: [
-             {
-               libraryName: 'antd',
-               style: true,
-             },
-           ],
-         },
+         transformImport: [
+           {
+             libraryName: 'antd',
+             style: true,
+           },
+         ],
        },
      },
    ],
  },
};
```

### Derive loader and plugin targets from target

In Rspack 2.0, the `targets` configuration for `builtin:swc-loader`, `builtin:lightningcss-loader`, and `rspack.LightningCssMinimizerRspackPlugin` now defaults to the [target](/config/target.md) configuration. If you need different targets, configure them in the loader or plugin options:

```js title="rspack.config.mjs"
export default {
  target: 'node',
  module: {
    rules: [
      {
        test: /\.js$/,
        loader: 'builtin:swc-loader',
        options: {
          env: {
            targets: 'chrome >= 87',
          },
        },
      },
    ],
  },
};
```

### New `experiments.pureFunctions` for function-level tree shaking

Rspack 2.0 adds an experimental [`experiments.pureFunctions`](/config/experiments.md#experimentspurefunctions) switch for finer-grained, pure-function-based tree shaking across modules.

After enabling it, you can choose one of these entry points depending on your code ownership:

- Use [module.parser.javascript.pureFunctions](/config/module-parser.md#javascriptpurefunctions) to manually mark top-level exported functions in matched third-party modules such as packages in `node_modules`.
- Use `/*#__NO_SIDE_EFFECTS__*/` on function definitions when you can modify the source code directly.

```js title="rspack.config.mjs"
export default {
  experiments: {
    pureFunctions: true,
  },
  module: {
    rules: [
      {
        test: /node_modules\/some-library\/index.js/,
        parser: {
          pureFunctions: ['isString'],
        },
      },
    ],
  },
};
```

For more details, see the [pureFunctions section](/guide/optimization/tree-shaking.md#purefunctions) and the [NO\_SIDE\_EFFECTS annotation](/guide/optimization/tree-shaking.md#no_side_effects-annotation) in the [tree shaking guide](/guide/optimization/tree-shaking.md).

## Output configuration changes

### Moved output library options

- `output.libraryTarget`: moved to [output.library.type](/config/output.md#outputlibrarytype)
- `output.libraryExport`: moved to [output.library.export](/config/output.md#outputlibraryexport)
- `output.umdNamedDefine`: moved to [output.library.umdNamedDefine](/config/output.md#outputlibraryumdnameddefine)
- `output.auxiliaryComment`: moved to [output.library.auxiliaryComment](/config/output.md#outputlibraryauxiliarycomment)

### Changed default value of output.chunkLoadingGlobal

The default value of [output.chunkLoadingGlobal](/config/output.md#outputchunkloadingglobal) changed from `webpackChunk${output.uniqueName}` to `rspackChunk${output.uniqueName}`. If your application depends on the old name, configure it explicitly:

```js title="rspack.config.mjs"
export default {
  output: {
    chunkLoadingGlobal: 'webpackChunkMyApp',
  },
};
```

### Changed default value of output.hotUpdateGlobal

The default value of [output.hotUpdateGlobal](/config/output.md#outputhotupdateglobal) changed from `webpackHotUpdate${output.uniqueName}` to `rspackHotUpdate${output.uniqueName}`. If your application depends on the old name, configure it explicitly:

```js title="rspack.config.mjs"
export default {
  output: {
    hotUpdateGlobal: 'webpackHotUpdateMyApp',
  },
};
```

### Changed default value of output.bundlerInfo.force

The default value of [output.bundlerInfo.force](/config/output.md#outputbundlerinfo) changed from `true` to `false`. In Rspack 2.0, `__rspack_version__` and `__rspack_unique_id__` are injected on demand by default instead of always being added as runtime modules. If your application depends on the previous always-injected behavior, configure it explicitly:

```js title="rspack.config.mjs"
export default {
  output: {
    bundlerInfo: {
      force: true,
    },
  },
};
```

### Changed default fallback value of output.trustedTypes.policyName

The fallback value of [output.trustedTypes.policyName](/config/output.md#outputtrustedtypes) changed from `'webpack'` to `'rspack'`. `policyName` still defaults to `output.uniqueName`, and the fallback is only used when `uniqueName` is not set. If your project relies on the old fallback, update your CSP configuration or set it explicitly:

```js title="rspack.config.mjs"
export default {
  output: {
    trustedTypes: {
      policyName: 'webpack',
    },
  },
};
```

### Removed output.charset

The `output.charset` configuration has been removed. It only added a `charset` attribute to generated `<script>` tags, and modern browsers already default to UTF-8.

### Removed optimization.removeAvailableModules

The `optimization.removeAvailableModules` configuration has been removed. It had no actual effect in Rspack and can be safely removed from your configuration.

## Stats changes

### Changed default parameters of stats.toJson()

When `stats.toJson()` is called without parameters, these fields now default to `false`:

- `modules`: Module information
- `assets`: Asset information
- `chunks`: Chunk information
- `chunkGroups`: Chunk group information
- `entryPoints`: Entry point information

By default, `stats.toJson()` no longer includes these details, so the returned object is more compact. If you need them, pass the parameters explicitly:

```js
const statsData = stats.toJson({
  modules: true,
  assets: true,
  chunks: true,
  chunkGroups: true,
  entryPoints: true,
});
```

> For detailed parameter configuration, refer to [Stats](/config/stats.md).

### Removed profile and stats.profile configuration

The top-level `profile` configuration and `stats.profile` configuration have been removed. Use [Rsdoctor](/guide/diagnostics/use-rsdoctor.md) for performance analysis:

```diff title="rspack.config.mjs"
export default {
-  profile: true,
  stats: {
-    profile: true,
  },
};
```

## Plugin changes

### Removed EsmLibraryPlugin

The `rspack.EsmLibraryPlugin` plugin has been removed. Configure [output.library](/config/output.md#outputlibrary) to generate ESM output:

```diff title="rspack.config.mjs"
-import { EsmLibraryPlugin } from '@rspack/core';

export default {
-  plugins: [new EsmLibraryPlugin()],
+  output: {
+    library: {
+      type: 'modern-module',
+    },
+  },
};
```

### Removed WarnCaseSensitiveModulesPlugin

`WarnCaseSensitiveModulesPlugin` has been renamed to [CaseSensitivePlugin](/plugins/case-sensitive-plugin.md), which covers all of its functionality.

### Removed getHooks method from some plugins

The `getHooks` method on `HtmlRspackPlugin`, `RsdoctorPlugin`, and `RuntimePlugin` has been removed. It was only a deprecated alias of `getCompilationHooks`, so migrate to `getCompilationHooks` directly.

### Adjusted HtmlRspackPlugin configuration

The `sri` configuration of [HtmlRspackPlugin](/plugins/html-rspack-plugin.md) has been removed. If you need SRI functionality, use the [SubresourceIntegrityPlugin](/plugins/subresource-integrity-plugin.md) plugin.

```diff title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.HtmlRspackPlugin({
-      sri: "sha256",
    }),
+    new rspack.SubresourceIntegrityPlugin({
+      hashFuncNames: ["sha256"],
+    }),
  ],
};
```

### Adjusted LightningCssMinimizerRspackPlugin configuration

The following [LightningCssMinimizerRspackPlugin](/plugins/lightning-css-minimizer-rspack-plugin.md) options have changed:

- `draft`: removed; use `drafts` instead
- `cssHeadDataCompression`: removed; delete this option directly

## Resolve behavior changes

### Default extensions change

Rspack 2.0 no longer includes `.wasm` in the default [resolve.extensions](/config/resolve.md#resolveextensions) used for JavaScript requests. That means extension-less requests such as `import './module'` or `require('./module')` no longer try `./module.wasm` by default, while explicit imports like `import './module.wasm'` are not affected. If you need the previous behavior, add `.wasm` back to the corresponding `resolve.byDependency` entries:

```js title="rspack.config.mjs"
export default {
  resolve: {
    byDependency: {
      esm: {
        extensions: ['.js', '.json', '.wasm'],
      },
      commonjs: {
        extensions: ['.js', '.json', '.wasm'],
      },
    },
  },
};
```

### CSS resolve conditions

Rspack 2.0 no longer includes `webpack` in the default CSS `@import` resolve conditions. If you need the previous behavior, add `webpack` back explicitly:

```js title="rspack.config.mjs"
export default {
  resolve: {
    byDependency: {
      'css-import': {
        conditionNames: ['webpack', '...'],
      },
    },
  },
};
```

## Other changes

### Changed `devtool` default value

The default value of the [devtool](/config/devtool.md) option has changed:

- When `mode` is `development`, the default value of `devtool` has been changed from `eval` to `cheap-module-source-map`
- When `mode` is `production` and you are using `@rspack/cli`, the default value of `devtool` has been changed from `source-map` to `false`

If you need source maps in production, set `devtool` to `source-map` or `hidden-source-map`:

```js title="rspack.config.mjs"
const isProd = process.env.NODE_ENV === 'production';

export default {
  devtool: isProd ? 'source-map' : 'cheap-module-source-map',
};
```

### Removed runtime module deprecated properties

The following deprecated properties of Runtime module have been removed:

- `constructorName` - Constructor name property
- `moduleIdentifier` - Module identifier property

If you used these properties in custom plugins, update your code as follows:

```diff title="my-plugin.js"
class MyPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap('MyPlugin', (compilation) => {
      compilation.hooks.runtimeModule.tap('MyPlugin', (module) => {
-       const name = module.constructorName;
-       const id = module.moduleIdentifier;
+       // Use alternative ways to get module information
+       const name = module.constructor.name;
+       const id = module.identifier();
      });
    });
  }
}
```

### ProgressPlugin handler signature change

The `ProgressPlugin` custom handler's third argument changed from `items: string[]` to a structured `info` object.

```diff
- (percent, msg, items) => void
+ (percent, msg, info) => void
```

`info` includes:

- `builtModules: number`: Number of modules built so far
- `moduleIdentifier?: string`: Identifier of the module being built (only provided during `build modules` updates)

### Changed default value of `resolve.roots`

The [resolve.roots](/config/resolve.md#resolveroots) configuration default value changed from `[context]` to `[]`.

In Rspack 1.x, `resolve.roots` implicitly included the project `context`, so the following CSS import could be resolved as `<context>/node_modules/lib/style.css`:

```css title="styles.css"
@import '/node_modules/lib/style.css';
```

In Rspack 2.0, this implicit behavior has been removed to align with standard module resolution. Requests starting with `/` are treated as file-system absolute paths.

Use a package request or a relative path instead:

```css title="styles.css"
@import 'lib/style.css';
@import '../node_modules/lib/style.css';
```

If you do rely on the previous behavior, add the following configuration:

```js title="rspack.config.mjs"
export default {
  resolve: {
    roots: [import.meta.dirname],
  },
};
```

### Removed `readResourceForScheme` hook

`NormalModule.getCompilationHooks(compilation).readResourceForScheme` has been removed. This hook was only a legacy alias for `readResource.for(scheme)`, so migrate to that API directly.

### `@module-federation/runtime-tools` is declared as optional peerDependency

The `@module-federation/runtime-tools` package has changed from `dependencies` to optional `peerDependencies` (declared via `peerDependencies` + `peerDependenciesMeta.optional`). If you are using [ModuleFederationPlugin](/plugins/module-federation-plugin.md), ensure that this package is explicitly installed in your project.

### Removed `module.unsafeCache`

`module.unsafeCache` was previously a performance optimization option. Because it conflicts with Rspack's Incremental Build and Persistent Cache mechanisms, it has been officially removed.

## Experimental configuration changes

### Remove experiments.css

`experiments.css` has been removed. CSS processing capability is now available by default, but you still need to configure the corresponding `type` in `module.rules` to enable it:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        type: 'css/auto', // Auto-detect CSS Modules
      },
    ],
  },
};
```

Available `type` options:

- **`css`**: Process CSS as plain CSS, without CSS Modules
- **`css/module`**: Force enable CSS Modules
- **`css/auto`**: Auto-detect, enable CSS Modules for `.module.css` files, and process plain `.css` files as regular CSS

> For more details, refer to [CSS](/guide/languages/css.md)

### experiments.asyncWebAssembly enabled by default

The default value of [experiments.asyncWebAssembly](/config/experiments.md#experimentsasyncwebassembly) changed from `false` to `true`. Files with the `.wasm` extension will now be handled using the built-in `webassembly/async` rule. If you don't need this feature, you can explicitly disable it:

```js title="rspack.config.mjs"
export default {
  experiments: {
    asyncWebAssembly: false,
  },
};
```

### Other experimental configuration changes

- `experiments.cache`: moved to the top-level [cache](/config/cache.md).
- `experiments.rspackFuture`: removed; `bundlerInfo` has moved to [output.bundlerInfo](/config/output.md#outputbundlerinfo).
- `experiments.incremental`: moved to the top-level [incremental](/config/incremental.md).
- `experiments.layers`: removed; layers are now stable and enabled by default, but you still need to configure `layer` in `module.rules`.
- `experiments.topLevelAwait`: removed; top-level await is now stable and enabled by default in ESM modules.
- `experiments.lazyCompilation`: moved to the top-level [lazyCompilation](/config/lazy-compilation.md).
- `experiments.lazyCompilationMiddleware`: moved to the top-level [lazyCompilationMiddleware](/guide/advanced/lazy-compilation.md#integrating-with-custom-server).
- `experiments.lazyBarrel`: removed; [barrel file optimization](/guide/advanced/lazy-barrel.md) is now enabled by default.
- `experiments.typeReexportsPresence`: removed; use [module.parser.javascript.typeReexportsPresence](/config/module-parser.md#javascripttypereexportspresence) directly to control the behavior when re-exporting types.
- `experiments.inlineConst`: removed; use [optimization.inlineExports](/config/optimization.md#optimizationinlineexports) to control constant inlining optimization.
- `experiments.inlineEnum`: removed; use [optimization.inlineExports](/config/optimization.md#optimizationinlineexports) and `builtin:swc-loader`'s [collectTypeScriptInfo.exportedEnum](/guide/features/builtin-swc-loader.md#collecttypescriptinfoexportedenum) to control enum inlining optimization.
- `experiments.outputModule`: removed; use [output.module](/config/output.md#outputmodule) directly to output ESM artifacts.
- `experiments.parallelLoader`: removed; loader parallelization is now stable and enabled by default, but you still need to configure [module.rules.use.parallel](/config/module-rules.md#rulesuseparallel) to opt in.
- `experiments.SubResourceIntegrityPlugin`: moved to the top-level [SubresourceIntegrityPlugin](/plugins/subresource-integrity-plugin.md).



---
url: /guide/migration/rspack_0.x.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Upgrading from 0.x to v1

The document lists all breaking changes from Rspack 0.7 to 1.0. Use it as a migration reference.

> See [Breaking changes in Rspack 1.0](https://github.com/web-infra-dev/rspack/discussions/6626) for details.

## Configuration default value adjustments

In Rspack 1.x, we have aligned the default configuration values with those of Webpack.

### \[Important] experiments.css

`experiments.css` has been deprecated and no longer enables default CSS processing.

In Rspack 0.x, `experiments.css` was enabled by default, which meant files ending with `*.css` were automatically treated as `type: 'css/auto'` and processed with built-in CSS logic.

Now, you must manually configure `module.rules` to handle CSS files. For example:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        type: 'css/auto', // 👈
        use: ['less-loader'],
      },
    ],
  },
};
```

### \[Important] optimization.concatenateModules

The default value of [optimization.concatenateModules](/config/optimization.md#optimizationconcatenatemodules) has been changed from `false` to:

- `true` when `mode` is `'production'`.
- `false` for other values of `mode`.

In Rspack 1.x, module concatenation optimization has become more stable. Thus, it's now enabled by default in production mode, allowing multiple modules to be concatenated into a single module to reduce output size and improve compression efficiency.

### devtool

The default value of [devtool](/config/devtool.md) has been changed from `false` to:

- `eval` when `mode` is `'development'`.
- `false` for other values of `mode`.

> `@rspack/cli` overrides the default `devtool` value from `@rspack/core`. Therefore, if you are using `@rspack/cli`, this change will not affect you.

### experiments.asyncWebAssembly

The default value of [experiments.asyncWebAssembly](/config/experiments.md#experimentsasyncwebassembly) has been changed from `false` to depend on the `experiments.futureDefaults` configuration. It is enabled by default only when `experiments.futureDefaults` is set to `true`.

If you are using WebAssembly modules as asynchronous modules, you now need to manually set `experiments.asyncWebAssembly` to `true`.

### splitChunks.cacheGroups.\{cacheGroup}.reuseExistingChunk

The default value of [splitChunks.cacheGroups.\{cacheGroup}.reuseExistingChunk](/plugins/split-chunks-plugin.md#splitchunkscachegroupscachegroupreuseexistingchunk) has been changed from `true` to `false`.

### optimization.moduleIds

The default value of [optimization.moduleIds](/config/optimization.md#optimizationmoduleids) has been changed to `'natural'` when `mode` is `none`.

### optimization.chunkIds

The default value of [optimization.chunkIds](/config/optimization.md#optimizationchunkids) has been changed to `'natural'` when `mode` is `none`.

## Removed configurations

### \[Important] Removed resolve.tsConfigPath

Please use [resolve.tsConfig](/config/resolve.md#resolvetsconfig) instead.

```diff
export default {
  resolve: {
-   tsConfigPath: path.resolve(__dirname, './tsconfig.json'),
+   tsConfig: path.resolve(__dirname, './tsconfig.json'),
  },
};
```

### output.amdContainer

Please use [output.library.amdContainer](/config/output.md#outputlibraryamdcontainer) instead.

## Adjustments to builtin:swc-loader

To streamline the core, Rspack 1.x has removed the built-in SWC plugins. You now need to manually include them.

### \[Important] Removed rspackExperiments.styledComponents

Use [@swc/plugin-styled-components](https://www.npmjs.com/package/@swc/plugin-styled-components) instead.

```diff
export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        loader: "builtin:swc-loader",
        options: {
-         rspackExperiments: {
-           styledComponents: true,
-         },
          jsc: {
+           experimental: {
+             plugins: [["@swc/plugin-styled-components", {}]],
+           },
          },
        },
      },
    ],
  },
};
```

### \[Important] Removed rspackExperiments.emotion

Use [@swc/plugin-emotion](https://www.npmjs.com/package/@swc/plugin-emotion) instead.

```diff
export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        loader: "builtin:swc-loader",
        options: {
-         rspackExperiments: {
-           emotion: true,
-         },
          jsc: {
+           experimental: {
+             plugins: [["@swc/plugin-emotion", {}]],
+           },
          },
        },
      },
    ],
  },
};
```

### \[Important] Removed rspackExperiments.relay

Use [@swc/plugin-relay](https://www.npmjs.com/package/@swc/plugin-relay) instead.

```diff
export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        loader: "builtin:swc-loader",
        options: {
-         rspackExperiments: {
-           relay: true,
-         },
          jsc: {
+           experimental: {
+             plugins: [["@swc/plugin-relay", {}]],
+           },
          },
        },
      },
    ],
  },
};
```

### \[Important] Removed rspackExperiments.preact

Use [@swc/plugin-prefresh](https://www.npmjs.com/package/@swc/plugin-prefresh) instead.

```diff
export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        loader: "builtin:swc-loader",
        options: {
-         rspackExperiments: {
-           preact: true,
-         },
          jsc: {
+           experimental: {
+             plugins: [["@swc/plugin-prefresh", {}]],
+           },
          },
        },
      },
    ],
  },
};
```

## Adjustments to built-in plugins

### \[Important] CSS minimizer plugin adjustment

In Rspack 0.x, we used the built-in `rspack.SwcCssMinimizerRspackPlugin` to compress CSS size.
Now, we have removed it and replaced it with [rspack.LightningCssMinimizerRspackPlugin](/plugins/lightning-css-minimizer-rspack-plugin.md) to handle the same functionality.

If you previously manually registered and configured `rspack.SwcCssMinimizerRspackPlugin`, you should to switch to `rspack.LightningCssMinimizerRspackPlugin`:

```diff
import { rspack } from '@rspack/core';

export default {
  optimization: {
    minimizer: [
-     new rspack.SwcCssMinimizerRspackPlugin({
+     new rspack.LightningCssMinimizerRspackPlugin({
        // options
      }),
    ],
  },
};
```

### rspack.SwcJsMinimizerRspackPlugin

Rspack's built-in and default-enabled JavaScript minimizer plugin has had its configuration aligned with [SWC's minification configuration](https://swc.rs/docs/configuration/minification). The breaking changes are as follows:

- `minimizerOptions.passes`: moved to `minimizerOptions.compress.passes`
- `minimizerOptions.dropConsole`: moved to `minimizerOptions.compress.drop_console`
- `minimizerOptions.pureFuncs`: moved to `minimizerOptions.compress.pure_funcs`
- `minimizerOptions.keepClassNames`: moved to `minimizerOptions.mangle.keep_classnames`
- `minimizerOptions.keepFnNames`: moved to `minimizerOptions.mangle.keep_fnames`
- `minimizerOptions.comments`: moved to `minimizerOptions.format.comments`
- `minimizerOptions.asciiOnly`: moved to `minimizerOptions.format.ascii_only`

Default value changes:

- `comments` (`options.format.comments`): changed from `false` to `"some"`

### rspack.HtmlRspackPlugin

We have aligned its configuration with [html-webpack-plugin](https://www.npmjs.com/package/html-webpack-plugin), with the following breaking changes:

- `excludedChunks` has been renamed to `excludeChunks`
- When `mode` is `'production'`, `minify` is now `true` by default

## Other changes

### \[Important] @rspack/cli

`@rspack/cli` has upgraded its dependency on `webpack-dev-server` from v4 to v5. If you are using `@rspack/cli`, please be aware of the following breaking changes:

- The minimum supported Node.js version for webpack-dev-server v5 is 18.12.0.
- Several configuration options have changed. Please refer to the [webpack-dev-server v5 migration guide](https://github.com/webpack/webpack-dev-server/blob/master/migration-v5.md).

### \[Important] `ResolverFactory` and `Resolver` refactoring with Rust

`ResolverFactory` and `Resolver` have been refactored with Rust to unify the implementations on the JS and Rust sides. Due to this change, `ResolverFactory` and `Resolver` currently do not support any hooks.

Additionally, `Resolver` now only supports the following methods:

- `resolveSync`
- `resolve`
- `withOptions`

This change might cause some plugins to become unusable.

:::tip
Rspack supports the [NormalModuleFactory](/api/plugin-api/normal-module-factory-hooks.md)'s [resolve](/api/plugin-api/normal-module-factory-hooks.md#resolve) hook. In most cases, you can use this hook as a replacement for the `Resolver`'s `resolve` hook to achieve the same functionality.

```js
compiler.hooks.normalModuleFactory.tap('PLUGIN', (normalModuleFactory) => {
  normalModuleFactory.hooks.resolve.tap('PLUGIN', (data) => {
    // Redirect the module
    if (data.request === './foo.js') {
      data.request = './bar.js';
    }
  });
});
```

:::



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

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Migrate from webpack

Rspack's configuration is designed based on webpack, enabling you to migrate your project from webpack to Rspack with ease.

This document is primarily aimed at projects using webpack 5. Since Rspack's API and configuration align with webpack 5.
For projects not using webpack 5, there are other migration guides that can be referenced:

- For projects using webpack v4 or earlier versions, you can refer to [webpack - To v5 from v4](https://webpack.js.org/migrate/5/) to understand the differences.
- For projects using create-react-app or CRACO, you can refer to [Migrating Create React App](/guide/migration/cra.md).
- For projects using Vue CLI, you can refer to [Rsbuild - Migrating from Vue CLI](https://rsbuild.rs/guide/migration/vue-cli).

## Checking the Node.js version

Before migrating, make sure that all build environments use a Node.js version supported by Rspack. `@rspack/core@2` requires Node.js `^20.19.0 || >=22.12.0`.

Keep the Node.js version consistent across local development, CI, and deployment builds. Update version settings such as `.nvmrc`, Volta configuration, and build images as needed.

## Installing Rspack

Install Rspack in your project directory:


```sh [npm]
npm add @rspack/core @rspack/cli @rspack/dev-server -D
```

```sh [yarn]
yarn add @rspack/core @rspack/cli @rspack/dev-server -D
```

```sh [pnpm]
pnpm add @rspack/core @rspack/cli @rspack/dev-server -D
```

```sh [bun]
bun add @rspack/core @rspack/cli @rspack/dev-server -D
```

```sh [deno]
deno add npm:@rspack/core npm:@rspack/cli npm:@rspack/dev-server -D
```

Both `@rspack/cli` and `@rspack/dev-server` are optional dependencies:

- If you are not using `webpack-cli`, no need to install `@rspack/cli`.
- If you are not using `webpack-dev-server`, no need to install `@rspack/dev-server`.
- Use the same version of `@rspack/core` and `@rspack/cli`. The version of `@rspack/dev-server` may differ and does not need to match.

## Updating package.json

Update your build scripts to use Rspack instead of webpack, see [CLI](/api/cli.md) for more details.

```diff title="package.json"
{
  "scripts": {
-   "dev": "webpack serve",
-   "build": "webpack build",
+   "dev": "rspack dev",
+   "build": "rspack build",
+   "preview": "rspack preview",
  }
}
```

## Remove unsupported CLI options

Rspack CLI does not support some webpack CLI options, including `--progress`, `--color`, `--bail`, and `--output-pathinfo`. Keeping these options causes an `Unknown option` error before the configuration is loaded.

During migration, remove these unsupported options from the build command. If you still need the corresponding behavior, use the Rspack configuration instead:

```diff title="package.json"
{
  "scripts": {
-   "build": "webpack --mode production --progress --color",
+   "build": "rspack --mode production",
  }
}
```

```js title="rspack.config.mjs"
export default {
  stats: {
    // Equivalent to webpack CLI's --color
    colors: true,
  },
};
```

## Updating configuration

Rename the `webpack.config.js` file to `rspack.config.js`.

:::tip
Rspack commands can specify the configuration file with `-c` or `--config`, similar to webpack commands.
However, unlike webpack, if a configuration file is not explicitly specified, Rspack defaults to using `rspack.config.js`.
:::

Rspack supports most webpack configuration options. See [Configure Rspack](/config/index.md) for the complete list of supported options.

## Cache configuration

Webpack and Rspack use different cache option shapes. Do not copy webpack cache options directly; map them to the corresponding [Rspack cache options](/config/cache.md).

For Cache storage itself, disabled cache and memory cache can be kept as-is: `cache: false`,
`cache: true`, and `cache: { type: 'memory' }` map directly to Rspack.

For webpack filesystem cache, use Rspack [persistent cache](/config/cache.md#persistent-cache), then migrate the supported fields below.

webpack's `cache.cacheUnaffected` optimization maps conceptually to Rspack's top-level
[`incremental`](/config/incremental.md) option. Rspack keeps this option independent from Cache, so
`cache: false` does not disable Incremental. To prevent cross-compilation reuse through both
mechanisms, also set `incremental: false`. Because Rspack Incremental covers more compilation stages
and has its own defaults, migrate this optimization separately instead of treating it as a Cache
field rename.

1. Change webpack `cache.type: 'filesystem'` to Rspack `cache.type: 'persistent'`.

```diff title="rspack.config.mjs"
export default {
- cache: {
-   type: 'filesystem',
- },
+ cache: {
+   type: 'persistent',
+ },
};
```

2. Flatten webpack `cache.buildDependencies` into Rspack [`cache.buildDependencies`](/config/cache.md#builddependencies), which accepts a file path array.

```diff title="rspack.config.mjs"
export default {
- cache: {
-   buildDependencies: {
-     config: [__filename, path.join(__dirname, 'package.json')],
-     ts: [path.join(__dirname, 'tsconfig.json')]
-   }
- },
+ cache: {
+   type: 'persistent',
+   buildDependencies: [
+     __filename,
+     path.join(import.meta.dirname, 'package.json'),
+     path.join(import.meta.dirname, 'tsconfig.json')
+   ]
+ },
};
```

3. Keep webpack [`cache.name`](/config/cache.md#name) and [`cache.version`](/config/cache.md#version) as-is. Rspack uses the same `cache.name` semantics to create coexisting caches.

4. Move webpack top-level `snapshot` options into Rspack [`cache.snapshot`](/config/cache.md#snapshot).

```diff title="rspack.config.mjs"
export default {
- snapshot: {
-   immutablePaths: [path.join(__dirname, 'constant')],
-   managedPaths: [path.join(__dirname, 'node_modules')],
-   unmanagedPaths: []
- },
+ cache: {
+   type: 'persistent',
+   snapshot: {
+     immutablePaths: [path.join(import.meta.dirname, 'constant')],
+     managedPaths: [path.join(import.meta.dirname, 'node_modules')],
+     unmanagedPaths: []
+   }
+ },
};
```

5. Move webpack `cache.cacheDirectory` to Rspack [`cache.storage.directory`](/config/cache.md#storagedirectory), and webpack `cache.cacheLocation` to Rspack [`cache.storage.location`](/config/cache.md#storagelocation). The option names differ, but their semantics are aligned. Rspack also defaults `storage.location` to `storage.directory/cache.name`.

```diff title="rspack.config.mjs"
export default {
- cache: {
-   type: 'filesystem',
-   cacheDirectory: path.join(__dirname, 'node_modules/.cache/test'),
-   cacheLocation: path.join(__dirname, 'node_modules/.cache/test/client')
- },
+ cache: {
+   type: 'persistent',
+   storage: {
+     type: 'filesystem',
+     directory: path.join(import.meta.dirname, 'node_modules/.cache/test'),
+     location: path.join(import.meta.dirname, 'node_modules/.cache/test/client')
+   }
+ },
};
```

The following example automates the Cache storage mapping. It intentionally leaves Incremental as a
separate migration decision.

```js
function transform(webpackConfig, rspackConfig) {
  if (webpackConfig.cache === undefined) {
    webpackConfig.cache = webpackConfig.mode === 'development';
  }

  if (!webpackConfig.cache) {
    rspackConfig.cache = false;
    return;
  }

  if (webpackConfig.cache === true || webpackConfig.cache.type === 'memory') {
    rspackConfig.cache = true;
    return;
  }

  rspackConfig.cache = { type: 'persistent' };

  rspackConfig.cache.buildDependencies = Object.values(
    webpackConfig.cache.buildDependencies || {},
  ).flat();

  rspackConfig.cache.name = webpackConfig.cache.name;
  rspackConfig.cache.version = webpackConfig.cache.version;

  rspackConfig.cache.snapshot = {
    immutablePaths: webpackConfig.snapshot?.immutablePaths,
    managedPaths: webpackConfig.snapshot?.managedPaths,
    unmanagedPaths: webpackConfig.snapshot?.unmanagedPaths,
  };

  rspackConfig.cache.storage = {
    type: 'filesystem',
    directory: webpackConfig.cache.cacheDirectory,
    location: webpackConfig.cache.cacheLocation,
  };
}
```

## Webpack built-in plugins

Rspack has implemented most of webpack's built-in plugins, with the same names and configuration parameters, allowing for easy replacement.

For example, replacing the [DefinePlugin](/plugins/define-plugin.md):

```js title="rspack.config.js"
const webpack = require('webpack'); // [!code --]
const { rspack } = require('@rspack/core'); // [!code ++]

module.exports = {
  //...
  plugins: [
    new webpack.DefinePlugin({ // [!code --]
    new rspack.DefinePlugin({ // [!code ++]
      // ...
    }),
  ],
}
```

See [webpack plugin compatibility](/plugins/webpack-built-in-plugin-support.md) for Rspack's compatibility status with webpack built-in plugins and selected internal plugins.

## Community plugins

Rspack supports most of the webpack community plugins and also offers alternative solutions for some currently unsupported plugins.

Check [Community plugin compatibility](/plugins/community-plugin-compatibility.md) for more information on Rspack's compatibility with popular webpack community plugins.

Some webpack ecosystem packages, such as [`webpack-node-externals`](https://www.npmjs.com/package/webpack-node-externals) and [`node-polyfill-webpack-plugin`](https://www.npmjs.com/package/node-polyfill-webpack-plugin), require newer versions for Rspack compatibility. Before reusing a community package, upgrade it to the latest version, as older versions may rely on incompatible webpack APIs.

### html-webpack-plugin

For most projects migrating from [`html-webpack-plugin`](https://github.com/jantimon/html-webpack-plugin), use [`html-rspack-plugin`](https://github.com/rstackjs/html-rspack-plugin). It is a JavaScript fork designed for Rspack and provides closer compatibility with existing options, templates, and integrations.


```sh [npm]
npm add html-rspack-plugin -D
```

```sh [yarn]
yarn add html-rspack-plugin -D
```

```sh [pnpm]
pnpm add html-rspack-plugin -D
```

```sh [bun]
bun add html-rspack-plugin -D
```

```sh [deno]
deno add npm:html-rspack-plugin -D
```

Update the import and constructor name in the Rspack configuration:

```diff title="rspack.config.mjs"
-import HtmlWebpackPlugin from 'html-webpack-plugin';
+import HtmlRspackPlugin from 'html-rspack-plugin';

 export default {
   plugins: [
-    new HtmlWebpackPlugin({
+    new HtmlRspackPlugin({
       // ...
     }),
   ],
 };
```

After completing the migration, remove `html-webpack-plugin` from the project dependencies.

If build performance is the priority, you can also use the built-in Rust plugin [`rspack.HtmlRspackPlugin`](/plugins/html-rspack-plugin.md). See the [HTML guide](/guide/languages/html.md#choose-a-plugin) for details.

### unplugin

Some [unplugin](/guide/features/plugin.md#unplugin) packages provide separate entry points for each bundler. When a `/rspack` entry is available, use it instead of `/webpack` so the plugin selects the Rspack adapter:

```diff title="rspack.config.mjs"
- import AutoImport from 'unplugin-auto-import/webpack';
- import Components from 'unplugin-vue-components/webpack';
+ import AutoImport from 'unplugin-auto-import/rspack';
+ import Components from 'unplugin-vue-components/rspack';
```

### copy-webpack-plugin

Use [rspack.CopyRspackPlugin](/plugins/copy-rspack-plugin.md) instead of [copy-webpack-plugin](https://github.com/webpack/copy-webpack-plugin):

```js title="rspack.config.js"
const CopyWebpackPlugin = require('copy-webpack-plugin'); // [!code --]
const { rspack } = require('@rspack/core'); // [!code ++]

module.exports = {
  plugins: [
    new CopyWebpackPlugin({ // [!code --]
    new rspack.CopyRspackPlugin({ // [!code ++]
      // ...
    }),
  ]
}
```

### mini-css-extract-plugin

Use [rspack.CssExtractRspackPlugin](/plugins/css-extract-rspack-plugin.md) instead of [mini-css-extract-plugin](https://github.com/webpack/mini-css-extract-plugin):

```diff title="rspack.config.js"
- const CssExtractWebpackPlugin = require('mini-css-extract-plugin');
+ const { rspack } = require('@rspack/core');

module.exports = {
  plugins: [
-   new CssExtractWebpackPlugin({
+   new rspack.CssExtractRspackPlugin({
      // ...
    }),
  ]
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
-         CssExtractWebpackPlugin.loader,
+         rspack.CssExtractRspackPlugin.loader,
          "css-loader"
        ],
      }
    ]
  }
}
```

### tsconfig-paths-webpack-plugin

Rspack does not support webpack's `resolve.plugins` option. Use [resolve.tsConfig](/config/resolve.md#resolvetsconfig) option instead of [tsconfig-paths-webpack-plugin](https://github.com/dividab/tsconfig-paths-webpack-plugin):

```diff title="rspack.config.mjs"
-import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin';
+import path from 'node:path';

 export default {
  resolve: {
-    plugins: [new TsconfigPathsPlugin()],
+    tsConfig: path.resolve(import.meta.dirname, 'tsconfig.json'),
  },
};
```

### fork-ts-checker-webpack-plugin

Use [ts-checker-rspack-plugin](https://github.com/rstackjs/ts-checker-rspack-plugin) instead of [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin):

```js title="rspack.config.js"
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin'); // [!code --]
const { TsCheckerRspackPlugin } = require('ts-checker-rspack-plugin'); // [!code ++]

module.exports = {
  plugins: [
    new ForkTsCheckerWebpackPlugin(), // [!code --]
    new TsCheckerRspackPlugin(), // [!code ++]
  ],
};
```

### terser-webpack-plugin

For projects that use [terser-webpack-plugin](https://github.com/webpack/terser-webpack-plugin) to minify JavaScript, we recommend switching to [rspack.SwcJsMinimizerRspackPlugin](/plugins/swc-js-minimizer-rspack-plugin.md) for better build performance:

```js title="rspack.config.js"
const TerserPlugin = require('terser-webpack-plugin'); // [!code --]
const { rspack } = require('@rspack/core'); // [!code ++]

module.exports = {
  optimization: {
    minimizer: [
      new TerserPlugin(), // [!code --]
      new rspack.SwcJsMinimizerRspackPlugin(), // [!code ++]
      new rspack.LightningCssMinimizerRspackPlugin(),
    ],
  },
};
```

:::tip
When you explicitly configure [optimization.minimizer](/config/optimization.md#optimizationminimizer), Rspack's default minimizers are disabled, so we recommend keeping both JavaScript and CSS minimizers in the list.
:::

### css-minimizer-webpack-plugin

For projects that use [css-minimizer-webpack-plugin](https://github.com/webpack/css-minimizer-webpack-plugin) to minify CSS, we recommend switching to [rspack.LightningCssMinimizerRspackPlugin](/plugins/lightning-css-minimizer-rspack-plugin.md) for better build performance:

```js title="rspack.config.js"
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin'); // [!code --]
const { rspack } = require('@rspack/core'); // [!code ++]

module.exports = {
  optimization: {
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin(),
      new CssMinimizerPlugin(), // [!code --]
      new rspack.LightningCssMinimizerRspackPlugin(), // [!code ++]
    ],
  },
};
```

## Loaders

Rspack is compatible with most webpack loaders, so existing loaders can typically be reused without changes.

For optimal performance and consistency, we recommend the following migrations where applicable:

### babel-loader

Migrate [babel-loader](https://github.com/babel/babel-loader) to [builtin:swc-loader](/guide/features/builtin-swc-loader.md) to use Rspack's built-in SWC transform for better performance.

If you need custom transformation logic using Babel plugins, you can retain `babel-loader`, but it is recommended to limit its use to fewer files to prevent significant performance degradation.

- Replace [@babel/preset-typescript](http://npmjs.com/package/@babel/preset-typescript) with `builtin:swc-loader` using `detectSyntax: 'auto'`:

```diff title="rspack.config.js"
module.exports = {
  module: {
    rules: [
      {
-        test: /\.(j|t)sx?$/,
+        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        exclude: [/[\\/]node_modules[\\/]/],
        use: [
          {
-           loader: 'babel-loader',
+           loader: 'builtin:swc-loader',
+           options: {
+             detectSyntax: 'auto',
+           },
          },
        ],
      },
    ],
  },
};
```

- Replace [@babel/preset-react](http://npmjs.com/package/@babel/preset-react) with SWC's `jsc.transform.react` option:

```diff title="rspack.config.js"
+const isDev = process.env.NODE_ENV === 'development';

module.exports = {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        exclude: [/[\\/]node_modules[\\/]/],
        use: [
          {
-            loader: 'babel-loader',
+            loader: 'builtin:swc-loader',
            options: {
-              presets: ['@babel/preset-typescript', '@babel/preset-react'],
+              jsc: {
+                transform: {
+                  react: {
+                    runtime: 'automatic',
+                    development: isDev,
+                    refresh: isDev,
+                  },
+                },
+              },
+              detectSyntax: 'auto',
            },
          },
        ],
      },
    ],
  },
};
```

### swc-loader

When migrating external [swc-loader](https://swc.rs/docs/usage/swc-loader) to [builtin:swc-loader](/guide/features/builtin-swc-loader.md), only the loader name changes to `builtin:swc-loader`; all the options remain exactly the same as your original `swc-loader` config.

```js title="rspack.config.js"
module.exports = {
  module: {
    rules: [
      {
        test: /\.(j|t)sx?$/,
        use: [
          {
            loader: 'swc-loader', // [!code --]
            loader: 'builtin:swc-loader', // [!code ++]
          },
        ],
      },
    ],
  },
};
```

### file-loader

Migrate [file-loader](https://github.com/webpack-contrib/file-loader) to [Asset Modules](/guide/features/asset-module.md) with `asset/resource`.

```diff title="rspack.config.js"
 module.exports = {
   module: {
     rules: [
-      {
-        test: /\.(png|jpe?g|gif)$/i,
-        use: ["file-loader"],
-      },
+      {
+        test: /\.(png|jpe?g|gif)$/i,
+        type: "asset/resource",
+      },
     ],
   },
 };
```

### url-loader

Migrate [url-loader](https://github.com/webpack-contrib/url-loader) to [Asset Modules](/guide/features/asset-module.md) with `asset/inline`.

```diff title="rspack.config.js"
 module.exports = {
   module: {
     rules: [
-      {
-        test: /\.(png|jpe?g|gif)$/i,
-        use: ["url-loader"],
-      },
+      {
+        test: /\.(png|jpe?g|gif)$/i,
+        type: "asset/inline",
+      },
     ],
   },
 };
```

### raw-loader

Migrate [raw-loader](https://github.com/webpack-contrib/raw-loader) to [Asset Modules](/guide/features/asset-module.md) with `asset/source`.

```diff title="rspack.config.js"
 module.exports = {
   module: {
     rules: [
-      {
-        test: /^BUILD_ID$/,
-        use: ["raw-loader",],
-      },
+      {
+        test: /^BUILD_ID$/,
+        type: "asset/source",
+      },
     ],
   },
 };
```

### vue-loader

For Vue 3 projects, replace `vue-loader` with [`rspack-vue-loader`](/guide/integrations/vue.md#vue-3), and update both the plugin import and loader name:

```diff title="rspack.config.mjs"
-import { VueLoaderPlugin } from 'vue-loader';
+import { VueLoaderPlugin } from 'rspack-vue-loader';

export default {
  plugins: [new VueLoaderPlugin()],
  module: {
    rules: [
      {
        test: /\.vue$/,
-       loader: 'vue-loader',
+       loader: 'rspack-vue-loader',
+       options: {
+         experimentalInlineMatchResource: true,
+       },
      },
    ],
  },
};
```

## Common webpack package replacements

When migrating webpack ecosystem packages, the following non-plugin packages usually need to be replaced.

| webpack package          | Rspack replacement                                                            | Notes                                  |
| ------------------------ | ----------------------------------------------------------------------------- | -------------------------------------- |
| `webpack`                | [`@rspack/core`](https://www.npmjs.com/package/@rspack/core)                  | Core package.                          |
| `webpack-cli`            | [`@rspack/cli`](https://www.npmjs.com/package/@rspack/cli)                    | CLI commands for Rspack.               |
| `webpack-dev-server`     | [`@rspack/dev-server`](https://github.com/rstackjs/rspack-dev-server)         | Development server for Rspack.         |
| `webpack-dev-middleware` | [`@rspack/dev-middleware`](https://github.com/rstackjs/rspack-dev-middleware) | Middleware for custom Node.js servers. |
| `webpack-chain`          | [`rspack-chain`](https://github.com/rstackjs/rspack-chain)                    | Chainable Rspack configuration API.    |
| `webpack-merge`          | [`rspack-merge`](https://github.com/rstackjs/rspack-merge)                    | Rspack configuration merging.          |

> For plugin packages, see [Community plugin compatibility](/plugins/community-plugin-compatibility.md).

## Removing webpack dependencies

After successfully building your project with Rspack, check whether any loaders, plugins, or custom build scripts still import `webpack` or `webpack/lib/*`.

If imports remain, keep `webpack` temporarily as a compatibility dependency. Remove webpack-related dependencies after they have been replaced or verified as unnecessary:


```sh [npm]
npm remove webpack webpack-cli webpack-dev-server
```

```sh [yarn]
yarn remove webpack webpack-cli webpack-dev-server
```

```sh [pnpm]
pnpm remove webpack webpack-cli webpack-dev-server
```

```sh [bun]
bun remove webpack webpack-cli webpack-dev-server
```

```sh [deno]
deno remove npm:webpack npm:webpack-cli npm:webpack-dev-server
```



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

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Migrate from Create React App

Since Create React App (CRA) comes with rich built-in capabilities, it would be challenging to manually set up an equivalent configuration using Rspack CLI. Therefore, we recommend migrating your CRA application to [Rsbuild](https://rsbuild.rs/) to leverage Rspack's capabilities out of the box.

## What is Rsbuild

Rsbuild is a high-performance build tool powered by Rspack. It provides a set of thoughtfully designed default build configs, offering an out-of-the-box development experience and can fully unleash the performance advantages of Rspack.

Rsbuild provides rich build features, including the compilation of TypeScript, JSX, Sass, Less, CSS Modules, Wasm, and others. It also supports Module Federation, image compression, type checking, PostCSS, Lightning CSS, and more.

![build tools](https://assets.rspack.rs/rsbuild/assets/rsbuild-1-0-build-tools.png)

## How to migrate

Rsbuild provides a comprehensive migration guide to help you migrate from Create React App.

Please refer to the [Migration guide](https://rsbuild.rs/guide/migration/cra) for details.



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

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Migrate from Storybook webpack

If you are using React / Vue with [Storybook](https://storybook.js.org/) and building with webpack 5, you can replace the `@storybook/react-webpack5` build with [storybook-rsbuild](https://github.com/rstackjs/storybook-rsbuild), which is implemented based on Rsbuild and uses Rspack as the underlying bundler. It supports out-of-the-box use, and the documentation can be found at [storybook-rsbuild](https://github.com/rstackjs/storybook-rsbuild).

Next, we will take React as an example to introduce how to migrate a Storybook webpack 5 project. The migration steps for Vue projects are similar to React.

:::info

Storybook Rsbuild requires at least version 8.0 of Storybook. It's highly recommended to upgrade Storybook to the latest version, check Storybook 8's [release note](https://storybook.js.org/blog/storybook-8/) for detail changes and migration guide.

:::

## Update dependencies

First, replace `@storybook/react-webpack5` with [`storybook-react-rsbuild`](https://www.npmjs.com/package/storybook-react-rsbuild) (for Vue projects, use [`storybook-vue3-rsbuild`](https://www.npmjs.com/package/storybook-vue3-rsbuild)), add `@rsbuild/core` and `@rsbuild/plugin-react` (for Vue projects, use `@rsbuild/plugin-vue`).


```sh [npm]
npm install storybook-react-rsbuild @rsbuild/core @rsbuild/plugin-react -D
```

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

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

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

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

## Configure Rsbuild

Storybook Rsbuild will automatically load the Rsbuild configuration file from the working directory. Install [`@rsbuild/plugin-react`](https://rsbuild.rs/guide/framework/react) (for Vue projects, install and use [`@rsbuild/plugin-vue`](https://rsbuild.rs/guide/framework/vue#vue-3)).

```js
import { defineConfig } from '@rsbuild/core';
import { pluginReact } from '@rsbuild/plugin-react';

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

## Update Storybook configuration

Refer to the following configuration to modify the `main.js` configuration of Storybook, and specify `'storybook-react-rsbuild'` as the Storybook framework (for Vue projects, use `'storybook-vue3-rsbuild'`).

```diff title=.storybook/main.js
export default {
-  framework: '@storybook/react-webpack5'
+  framework: 'storybook-react-rsbuild',
  },
```

## Examples

The [rstackjs/storybook-rsbuild](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes) repository provides examples of Storybook for React / Vue projects.

## More details

This page is a quick start. For the complete migration walkthrough — including handling webpack-dependent addons, mapping common webpack patterns to Rsbuild, and migrating from Vite — see the [storybook-rsbuild migration guide](https://storybook.rsbuild.rs/guide/migration#from-storybook-webpack5-framework).



---
url: /misc/branding/guideline.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Branding guideline

Here you can find the branding guideline, assets and license for the project.

## The name

When used standalone, Rspack should always be written as Rspack, not rspack or RSPACK or RSPack. However, lowercase letters can be used in command lines or package names, such as `@rspack/cli`.

## Rspack logo

Rspack logo is a small crab as fast as lightning, representing fast compilation of Rspack.

![Rspack Logo](https://assets.rspack.rs/rspack/rspack-logo.svg)
## Design resources

You can find all of Rspack's design resources under the [rstack-design-resources](https://github.com/rstackjs/rstack-design-resources) repository.

The design resources of Rspack are licensed under the [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.en) license.



---
url: /config/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Configure Rspack

Rspack provides configurations similar to webpack. This chapter will show you how to use the Rspack configuration.

## Configuration file

When you run the Rspack CLI, Rspack automatically reads the `rspack.config.*` file in the current working directory.

A basic Rspack configuration file looks like this:


**ESM**

```js title="rspack.config.mjs"
import { defineConfig } from '@rspack/cli';

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```


**CJS**

```js title="rspack.config.cjs"
const { defineConfig } = require('@rspack/cli');

module.exports = defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```


**TypeScript**

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

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```


## Configuration file formats

Rspack supports these configuration file formats:

- `rspack.config.ts`: `TypeScript` format, see [TypeScript configuration file](#typescript-configuration-file) for more details.
- `rspack.config.js`: defaults to `CommonJS` format, or `ES modules` format if the type of the package.json is "module".
- `rspack.config.mts`: Forced to `ES modules` + `TypeScript` format.
- `rspack.config.mjs`: Forced to `ES modules` format.
- `rspack.config.cts`: Forced to `CommonJS` + `TypeScript` format.
- `rspack.config.cjs`: Forced to `CommonJS` format.

Rspack resolves configuration files in the following order by default:

`rspack.config.ts` > `rspack.config.js` > `rspack.config.mts` > `rspack.config.mjs` > `rspack.config.cts` > `rspack.config.cjs`

> See [ES modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules) and [CommonJS](https://nodejs.org/api/modules.html) for the difference between `CommonJS` and `ES modules`.

## Extending configurations

See [Extending Configurations](/config/extends.md) for details on how to extend configurations from other files or packages.

## TypeScript configuration file

When using `rspack.config.ts`, you can choose from one of the following approaches:

### Default behavior

Starting from v1.5.0, Rspack CLI has built-in support for TypeScript configuration.

By default, Rspack CLI uses `--configLoader=auto`:

- JavaScript config files are loaded with the native runtime loader.
- When the runtime supports native TypeScript, Rspack CLI tries the native loader first and falls back to [Jiti](https://github.com/unjs/jiti) if loading fails.
- On runtimes without native TypeScript support, Rspack CLI loads TypeScript config files with Jiti directly.

If you're using a Rspack CLI earlier than v1.5.0, it's recommended to upgrade to the latest version.

### Native support

If your JavaScript runtime already natively supports TypeScript, you can force the native loader to load the configuration file, ensuring that module resolution behavior is consistent with native behavior.

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

- For Node.js v22.18+ and v24.3+ which support native TypeScript by default, you can run the following command to load the TS config:

```json title="package.json"
{
  "scripts": {
    "build": "rspack build --configLoader=native"
  }
}
```

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

### Jiti loader

You can also force Rspack CLI to load TypeScript config files through Jiti:

```json title="package.json"
{
  "scripts": {
    "build": "rspack build --configLoader=jiti"
  }
}
```

## Type checking

Use the `defineConfig` helper to enable auto-completion. For JavaScript configuration files, you can use the `// @ts-check` comment to enable type checking.


**TypeScript**

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

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```


**JavaScript**

```js title="rspack.config.mjs"
// @ts-check
import { defineConfig } from '@rspack/cli';

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```


Alternatively, you can use [JSDoc](https://jsdoc.app/) for type checking.

```js title="rspack.config.mjs"
// @ts-check
/** @type {import('@rspack/cli').Configuration} */
const config = {
  entry: {
    main: './src/index.js',
  },
};
export default config;
```

## Specify the configuration file

Specify the name of the configuration file using the `--config` option.

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

```json title="package.json"
{
  "scripts": {
    "dev": "rspack serve",
    "build": "rspack build --config rspack.prod.config.js"
  }
}
```

Abbreviate the `--config` option to `-c`:

```bash
$ rspack build -c rspack.prod.config.js
```

## Exporting a configuration function

Rspack supports exporting a function in Rspack configuration file, you can dynamically compute the configuration in the function and return it to Rspack.

```js title="rspack.config.mjs"
export default function (env, argv) {
  return {
    devtool: env.production ? 'source-map' : 'eval',
  };
}
```

As you can see from the example above, the function takes two input parameters:

- The first argument is `env`, which corresponds to the value of the `--env` option when running the CLI command.
- The second argument is `argv`, which contains all the options passed to the CLI.

### Determine the current environment

In addition to passing the `env` parameter, it is more common to use `process.env.NODE_ENV` to determine the current environment:

```js title="rspack.config.mjs"
export default function (env, argv) {
  const isProduction = process.env.NODE_ENV === 'production';
  return {
    devtool: isProduction ? 'source-map' : 'eval',
  };
}
```

## Merge configurations

Use Rspack's [extends](/config/extends.md) option or [rspack-merge](https://github.com/rstackjs/rspack-merge) package to merge multiple Rspack configurations.

### extends option

When using [@rspack/cli](/api/cli.md), Rspack provides the `extends` option, allowing you to extend configurations from other files or packages.

```js title="rspack.config.mjs"
export default {
  extends: './base.rspack.config.mjs',
  output: {
    filename: '[name].bundle.js',
  },
};
```

> This option is only supported in `@rspack/cli`, see [extends](/config/extends.md) for more usage.

### rspack-merge

`rspack-merge` is a library for merging multiple Rspack configurations.

First install `rspack-merge`:


```sh [npm]
npm add rspack-merge -D
```

```sh [yarn]
yarn add rspack-merge -D
```

```sh [pnpm]
pnpm add rspack-merge -D
```

```sh [bun]
bun add rspack-merge -D
```

```sh [deno]
deno add npm:rspack-merge -D
```

Then you can use its `merge` function to merge configurations:

```js title="rspack.config.mjs"
import { merge } from 'rspack-merge';

const isDev = process.env.NODE_ENV === 'development';
const base = {};
const dev = {
  plugins: [new SomeDevPlugin()],
};

export default isDev ? merge(base, dev) : base;
```

> See [rspack-merge documentation](https://github.com/rstackjs/rspack-merge) for more details.



---
url: /config/filename-placeholders.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Filename placeholders

Rspack's filename-related options support placeholders. This lets you generate output filenames dynamically based on the current build context. It helps distinguish different assets and improves caching efficiency.

Different options support different types of placeholders. This page lists all placeholder types available in Rspack, and which filename options use which placeholder type.

## Example

For example, the `[contenthash]` placeholder generates a hash based on the file content. If the content does not change, the filename remains stable. This is ideal for long-term caching.

Here is an example showing how `[name]` and `[contenthash]` can be used in [output.filename](/config/output.md#outputfilename):

```js title="rspack.config.mjs"
const isProd = process.env.NODE_ENV === 'production';

export default {
  entry: {
    main: './src/main.js',
    list: './src/list.js',
  },
  output: {
    filename: isProd ? '[name].[contenthash].js' : '[name].js',
  },
};
```

This outputs:

```
src/
├── main.js
└── list.js
dist/
├── main.abcdefghabcdefgh.js
└── list.qwertyuiqwertyui.js
```

## Filename options

The following table summarizes common filename options and the placeholder types they support:

| Option                                                                                | Placeholder Types              | Description                   |
| ------------------------------------------------------------------------------------- | ------------------------------ | ----------------------------- |
| [output.filename](/config/output.md#outputfilename)                                   | Compilation, Chunk             | Entry chunk filenames         |
| [output.chunkFilename](/config/output.md#outputchunkfilename)                         | Chunk                          | Non-entry chunk filenames     |
| [output.cssFilename](/config/output.md#outputcssfilename)                             | Compilation, Chunk             | Entry CSS chunk filenames     |
| [output.cssChunkFilename](/config/output.md#outputcsschunkfilename)                   | Chunk                          | Non-entry CSS chunk filenames |
| [output.assetModuleFilename](/config/output.md#outputassetmodulefilename)             | File, Module                   | Static asset module filenames |
| [output.webassemblyModuleFilename](/config/output.md#outputwebassemblymodulefilename) | File, Module                   | WebAssembly module filenames  |
| [output.hotUpdateMainFilename](/config/output.md#outputhotupdatemainfilename)         | Only `[fullhash]`, `[runtime]` | HMR manifest filename         |
| [output.hotUpdateChunkFilename](/config/output.md#outputhotupdatechunkfilename)       | Only `[fullhash]`, `[id]`      | HMR chunk filenames           |
| [output.sourceMapFilename](/config/output.md#outputsourcemapfilename)                 | Compilation, Chunk, File       | source map filenames          |

## Placeholder types

### Compilation placeholders

Compilation placeholders expose information about the entire build process.

| Template     | Description           |
| ------------ | --------------------- |
| `[fullhash]` | Full compilation hash |

### Chunk placeholders

Chunk placeholders expose information about a specific chunk.

| Template        | Description                                                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------- |
| `[id]`          | Chunk ID                                                                                                 |
| `[name]`        | Chunk name if available. Otherwise falls back to chunk ID                                                |
| `[chunkhash]`   | Hash of all content in the chunk                                                                         |
| `[contenthash]` | Hash of content for a specific file type. For example JavaScript files only hash JS modules in the chunk |

### Module placeholders

Module placeholders expose information about a specific module.

| Template        | Description            |
| --------------- | ---------------------- |
| `[id]`          | Module ID              |
| `[hash]`        | Module hash            |
| `[contenthash]` | Hash of module content |

### File placeholders

File placeholders expose information derived from the file path.

| Template     | Description                                                              |
| ------------ | ------------------------------------------------------------------------ |
| `[file]`     | Full file path without query or fragment                                 |
| `[query]`    | The query string, including `?`                                          |
| `[fragment]` | Fragment starting with `#`                                               |
| `[base]`     | Base filename including extension but without path                       |
| `[path]`     | Directory path without the filename                                      |
| `[name]`     | Filename without extension and without path                              |
| `[ext]`      | Extension including `.` (only supported in `output.assetModuleFilename`) |

Relationships:

- `[file]` equals `[path][base]`
- `[base]` equals `[name][ext]`

A complete path can be built using any of these forms:

- `[path][name][ext][query][fragment]`
- `[path][base][query][fragment]`
- `[file][query][fragment]`

### URL placeholders

URL placeholders expose information about the current request URL.

| Template | Description |
| -------- | ----------- |
| `[url]`  | URL value   |

## Hash length

Hash placeholders (`[hash]`, `[contenthash]`, `[chunkhash]`) support length modifiers using `[hash:n]`, where the default length is 16.

Example truncating `[contenthash]` to 8 characters:

```js title="rspack.config.mjs"
const isProd = process.env.NODE_ENV === 'production';

export default {
  output: {
    filename: isProd ? '[name].[contenthash:8].js' : '[name].js',
  },
};
```

You can also specify a digest (only `base64` is supported) and length:

```js title="rspack.config.mjs"
const isProd = process.env.NODE_ENV === 'production';

export default {
  output: {
    filename: isProd ? '[name].[contenthash:base64:8].js' : '[name].js',
  },
};
```

Alternatively, you can configure a global default using [output.hashDigestLength](/config/output.md#outputhashdigestlength).

:::tip

During local development, avoid using hash-based filenames.

Entry chunks and chunks produced by [optimization.splitChunks](/plugins/split-chunks-plugin.md) are loaded via `<script>` tags in HTML. If filenames contain hashes, the HTML file cannot update dynamically, which breaks HMR.

:::

## Escaping placeholders

If you want to preserve the literal placeholder text instead of having Rspack interpolate it, escape the brackets with backslashes.

For example, to include `[name]` in the filename, rather than interpolating it as the chunk name, you can escape it with backslashes:

```js title="rspack.config.mjs"
export default {
  output: {
    filename: '\\[name\\].js',
  },
};
```

## Using functions

Some options allow specifying a function instead of a string.

For example, `output.filename` option accepts a function, which will be called during compilation and receives a `PathData` object containing contextual information.

```js title="rspack.config.mjs"
export default {
  output: {
    filename: (pathData) => {
      return pathData.chunk.name === 'main' ? '[name].js' : '[name]/[name].js';
    },
  },
};
```

The function is invoked during the build process and receives an object that contains the current context data. You can use this information to construct any string you need, and the returned string will still go through the same placeholder substitution rules.

```ts
type PathData = {
  filename?: string;
  hash?: string;
  contentHash?: string;
  runtime?: string;
  url?: string;
  id?: string | number;
  chunk?: Chunk;
  contentHashType?: string;
};
```



---
url: /config/cache.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Cache


[Added in v2.0.0](https://github.com/web-infra-dev/rspack/releases/tag/v2.0.0)

The `cache` option controls Rspack's caching strategy and lets Rspack reuse cached data across builds to improve build performance.

When Cache is enabled, Rspack supports two storage modes: process-local Memory Cache and
filesystem-backed Persistent Cache. Both store fine-grained computation results and are independent
from [`incremental`](/config/incremental.md).

- **Type:**

```ts
type CacheOptions =
  | boolean
  | { type: 'memory' }
  | {
      type: 'persistent';
      name?: string;
      buildDependencies?: string[];
      version?: string;
      maxAge?: number;
      maxMemoryGenerations?: number;
      maxVersions?: number;
      portable?: boolean;
      readonly?: boolean;
      snapshot?: {
        immutablePaths?: Array<string | RegExp>;
        unmanagedPaths?: Array<string | RegExp>;
        managedPaths?: Array<string | RegExp>;
      };
      storage?: {
        type: 'filesystem';
        directory?: string;
        location?: string;
      };
    };
```

- **Default:** `{ type: 'memory' }` in development mode (equivalent to `true`), `false` in production mode and none mode

## Relationship with incremental

Cache and [`incremental`](/config/incremental.md) are orthogonal. Cache controls fine-grained entry
lookup and storage; Incremental controls whether development rebuilds recover prior pass artifacts
and update affected work from known mutations.

- `cache: false` does not disable Incremental.
- `incremental: false` does not disable Cache.
- A filesystem Cache can accelerate a later one-shot build, but that is a Cache hit rather than an
  incremental build.

To disable both reuse mechanisms, set both options explicitly:

```js title="rspack.config.mjs"
export default {
  cache: false,
  incremental: false,
};
```

## Memory cache

Set `cache` to `true` or `{ type: 'memory' }` to enable in-memory cache. Memory cache is kept only in the current compiler process and is useful for rebuilds, watch mode, and HMR.

Memory cache does not write cache data to disk, so it is cleared when the process exits and cannot speed up a fresh build started later. It is best suited for long-running development workflows where the same compiler instance handles multiple rebuilds.

```js title="rspack.config.mjs"
export default {
  cache: true,
};
```

or:

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'memory',
  },
};
```

## Persistent cache

Set `cache` to `{ type: 'persistent' }` to enable filesystem-backed persistent cache. Persistent cache stores cache data on disk so later build processes can reuse it.

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
  },
};
```

### name

- **Type:** `string`
- **Default:** `<config.name>-<mode>` when `config.name` is set, otherwise `<mode>`

`cache.name` names a persistent cache. Different names create coexisting caches. In multi-compiler mode, the first compiler keeps the default name, while later compilers append their zero-based index, such as `-1` and `-2`.

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    name: 'client-development',
  },
};
```

### buildDependencies

- **Type:** `string[]`
- **Default:** `[]`

`cache.buildDependencies` is an array of file or directory paths treated as build dependencies. Rspack tracks these paths and invalidates the persistent cache when any tracked build dependency changes.

```js title="rspack.config.mjs"
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

export default {
  cache: {
    type: 'persistent',
    buildDependencies: [__filename, join(__dirname, './tsconfig.json')],
  },
};
```

:::tip
Unlike webpack, Rspack does not include any preset build dependencies by default. Add project configuration files that are not loaded by Rspack CLI to `cache.buildDependencies` so the cache is invalidated when those files change.

Note: When using Rspack CLI, the config file is automatically added to `cache.buildDependencies`.

When resolving build dependencies, Rspack recursively traverses directories and parses JS/TS files via AST to track transitive dependencies. For dependencies resolved under `node_modules`, recursive resolution stops and the corresponding package's `package.json` is tracked when available.
:::

### version

- **Type:** `string`
- **Default:** `""`

`cache.version` identifies the format of the persistent cache data. When it
differs from the stored version, Rspack does not reuse the existing cache and
overwrites its content after the build. Update it when configuration changes
make the existing cache incompatible.

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    version: 'v1',
  },
};
```

:::warning
Don't share the same cache (same `cache.version` and same `cache.storage.location`) between builds with different configurations. Doing so may cause incorrect cache hits.
:::

:::tip Persistent cache invalidation

Rspack stores one cache directory for each `compilerPath`, using its hash as
the subdirectory name. Changing [version](#version) invalidates and overwrites
that compiler's existing cache; multiple versions do not coexist.

:::

### maxVersions


Stability: Deprecated

- **Type:** `number`
- **Default:** Not set

`cache.maxVersions` is retained for backward compatibility but has no effect.
Rspack keeps only one persistent cache per `compilerPath`. Explicitly
configuring this option emits a deprecation warning.

### maxMemoryGenerations

- **Type:** `number` (non-negative integer) or `Infinity`
- **Default:** `5` in development mode, `Infinity` in production and none modes

The number of generations that unused persistent-cache entries stay in the
additional memory cache. Set it to `0` to disable the memory cache and read
entries from disk whenever they are needed. Set it to `Infinity` to keep
entries in memory for the lifetime of the compiler.

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    maxMemoryGenerations: 0,
  },
};
```

### maxAge

- **Type:** `number` (positive integer, in seconds) or `Infinity`
- **Default:** `7 * 24 * 60 * 60` (7 days)

The maximum time, in seconds, that a compiler cache can remain unused. During cleanup, Rspack removes compiler cache directories that have not been accessed for longer than `maxAge`. Set `maxAge` to `Infinity` to disable age-based cleanup.

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    maxAge: 7 * 24 * 60 * 60,
  },
};
```

### portable

- **Type:** `boolean`
- **Default:** `false`

Enable portable cache mode. When enabled, the generated cache content can be shared across different platforms and paths within the same project.

Portable cache is built on top of persistent cache and makes the cache platform-independent by converting platform-specific data (e.g., absolute paths to relative paths) during serialization and deserialization.

**Example:**

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    portable: true,
  },
};
```

:::tip Use cases

A typical use case is in CI environments where Windows, Linux, and macOS can share the same cache for acceleration without generating three separate cache copies.

:::

:::warning Limitations

Files outside the project directory (outside `config.context`) will be converted to relative paths. If these files don't exist in the new environment, it will trigger a rebuild of the related modules.

:::

### readonly

- **Type:** `boolean`
- **Default:** `false`

Enable read-only cache mode. When enabled, the cache will only be read from disk and never written to, which is useful for CI environments where you want to use a pre-warmed cache without modifying it.

**Example:**

Enable only in CI:

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    // Make sure your CI environment sets `process.env.CI` (or a similar env variable)
    readonly: Boolean(process.env.CI),
  },
};
```

### snapshot

- **Type:** `object`
- **Default:** `{ immutablePaths: [], managedPaths: [/[\\/]node_modules[\\/][^.]/], unmanagedPaths: [] }`

Configure the snapshot strategy used by persistent cache to determine which dependencies have changed since the previous build.

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    snapshot: {
      managedPaths: [/[\\/]node_modules[\\/]/],
    },
  },
};
```

#### snapshot.immutablePaths

- **Type:** `(RegExp | string)[]`
- **Default:** `[]`

An array of immutable paths. When restoring from persistent cache, Rspack treats matching paths as unchanged and does not re-check their contents. This is suitable for content-addressed paths that never change after being written.

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    snapshot: {
      immutablePaths: [/[\\/]\.yarn[\\/]cache[\\/]/],
    },
  },
};
```

#### snapshot.managedPaths

- **Type:** `(RegExp | string)[]`
- **Default:** `[/[\\/]node_modules[\\/][^.]/]`

An array of paths managed by the package manager. When restoring from persistent cache, Rspack uses the `version` field in the corresponding `package.json` to determine whether a package has changed, instead of hashing file contents. This speeds up cache validation for packages that are only updated through the package manager.

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    snapshot: {
      managedPaths: [/[\\/]node_modules[\\/]/],
    },
  },
};
```

#### snapshot.unmanagedPaths

- **Type:** `(RegExp | string)[]`
- **Default:** `[]`

Specifies paths within [`cache.snapshot.managedPaths`](#snapshotmanagedpaths) that should not be treated as managed by the package manager. Files in these paths fall back to content-hash-based cache validation.

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    snapshot: {
      unmanagedPaths: [/[\\/]node_modules[\\/]my-linked-package[\\/]/],
    },
  },
};
```

### storage

- **Type:** `{ type: 'filesystem'; directory?: string; location?: string }`

Configure cache storage. Currently only filesystem storage is supported.

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
    },
  },
};
```

#### storage.type

- **Type:** `'filesystem'`
- **Default:** `'filesystem'`

Use `type` to configure the cache storage type. Currently only filesystem storage is supported.

#### storage.directory

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

`cache.storage.directory` is the base directory for persistent caches, matching the semantics of webpack's `cache.cacheDirectory`. Relative paths are resolved from [`config.context`](/config/context.md).

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
      directory: '.rspack-cache',
    },
  },
};
```

#### storage.location


[Added in v2.1.8](https://github.com/web-infra-dev/rspack/releases/tag/v2.1.8)

- **Type:** `string`
- **Default:** `<storage.directory>/<cache.name>`

`cache.storage.location` is the complete path where Rspack reads and writes cache data, matching the semantics of webpack's `cache.cacheLocation`. When omitted, Rspack derives it from `cache.storage.directory` and `cache.name`. Relative paths are resolved from [`config.context`](/config/context.md).

```js title="rspack.config.mjs"
export default {
  context: '/project',
  cache: {
    type: 'persistent',
    name: 'client',
    storage: {
      type: 'filesystem',
      directory: '.rspack-cache',
    },
  },
};

// cache.storage.location defaults to '/project/.rspack-cache/client'.
```

Set `storage.location` explicitly to override the derived path:

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    storage: {
      type: 'filesystem',
      location: '.custom-cache/client',
    },
  },
};
```

### Inspect persistent cache logs

Persistent cache logs are emitted through the `rspack.persistentCache` logger. To display them in the build stats, enable this logger with `stats.loggingDebug`:

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
  },
  stats: {
    logging: false,
    loggingDebug: /^rspack\.persistentCache$/,
  },
};
```

The logs include key persistent cache events, such as whether persistent cache is enabled, whether build dependencies are valid, whether cache recovery succeeded, and why the persistent cache was invalidated. They also include read and write timings for each cache phase (for example, build dependency validation, snapshot restore, occasion recovery, staging, and flushing to disk).

If you want to include logs from other loggers too, enable `stats.logging`:

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
  },
  stats: {
    logging: 'info',
    loggingDebug: /^rspack\.persistentCache$/,
  },
};
```

## Disable cache

Set `cache` to `false` to disable both memory cache and persistent cache. This does not disable
[`incremental`](/config/incremental.md). If a workflow requires full rebuilds without artifact recovery,
set `incremental: false` separately.

Disabling cache is generally not recommended because computations that are not skipped by
Incremental can no longer reuse fine-grained cache entries.

```js title="rspack.config.mjs"
export default {
  cache: false,
};
```

## Migrating from webpack

See [Migrate from webpack - Cache configuration](/guide/migration/webpack.md#cache-configuration) for how to migrate webpack cache configuration to Rspack.



---
url: /config/context.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Context


- Type: `string`
- Default:`process.cwd()`


The `context` configuration is used to set the base directory for Rspack builds.

`context` is an absolute path that is used as the base path for relative paths in Rspack configurations such as [entry](/config/entry.md) and [output](/config/output.md).

By default, Rspack uses the current working directory of the Node.js process as the base directory. In most cases, it is recommended to set a base directory manually, rather than relying on the current working directory of Node.js.

## Example

For example, you can use [`__dirname`](https://nodejs.org/docs/latest/api/modules.html#__dirname) as the base directory:


**ESM**

```js title="rspack.config.mjs"
import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = dirname(fileURLToPath(import.meta.url));

export default {
  context: __dirname,
  entry: {
    main: './src/index.js',
  },
};
```


**CJS**

```js title="rspack.config.cjs"
module.exports = {
  context: __dirname,
  entry: {
    main: './src/index.js',
  },
};
```


In the above example, the `main` entry will be resolved based on the `path.join(__dirname, './src/index.js')` path.


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/entry-context/#context) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/dev-server.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# DevServer

This page describes the options used by [`@rspack/dev-server`](https://github.com/rstackjs/rspack-dev-server) to run a local development server for Rspack projects.

- **Type:** `object`

## When to use

The `devServer` config only takes effect when using `@rspack/dev-server`. If the current application does not start `@rspack/dev-server`, this config will have no effect.

For example, with Rspack CLI, install `@rspack/dev-server` and use `rspack dev` or `rspack serve` to apply the `devServer` config. Rsbuild implements its own dev server and provides a separate `server` config, so Rsbuild projects should configure that instead.

When using `rspack preview`, the Rspack CLI also loads `@rspack/dev-server` and respects a subset of `devServer` options: [`port`](#devserverport), [`host`](#devserverhost), [`open`](#devserveropen), [`server`](#devserverserver), [`proxy`](#devserverproxy), and [`historyApiFallback`](#devserverhistoryapifallback).

## devServer.allowedHosts

- **Type:** `string | string[] | 'all' | 'auto'`
- **Default:** `'auto'`

This option allows you to allowlist services that are allowed to access the dev server.

```js title="rspack.config.mjs"
export default {
  devServer: {
    allowedHosts: [
      'host.com',
      'subdomain.host.com',
      'subdomain2.host.com',
      'host2.com',
    ],
  },
};
```

Mimicking Django's `ALLOWED_HOSTS`, a value beginning with `.` can be used as a subdomain wildcard. `.host.com` will match `host.com`, `www.host.com`, and any other subdomain of `host.com`.

```js title="rspack.config.mjs"
export default {
  devServer: {
    // this achieves the same effect as the first example
    // with the bonus of not having to update your config
    // if new subdomains need to access the dev server
    allowedHosts: ['.host.com', 'host2.com'],
  },
};
```

When set to `'all'` this option bypasses host checking. **THIS IS NOT RECOMMENDED** as apps that do not check the host are vulnerable to DNS rebinding attacks.

```js title="rspack.config.mjs"
export default {
  devServer: {
    allowedHosts: 'all',
  },
};
```

When set to `'auto'` this option always allows `localhost`, [`host`](#devserverhost), and [`client.webSocketURL.hostname`](#websocketurl):

```js title="rspack.config.mjs"
export default {
  devServer: {
    allowedHosts: 'auto',
  },
};
```

## devServer.app

- **Type:**

```ts
type DevServerApp = () => Promise<ConnectApplication>;
```

- **Default:** a [`connect-next`](https://github.com/rstackjs/connect-next) app

Provide a custom application instance for the dev server middleware stack.

By default, `@rspack/dev-server` creates a `connect-next` app. If you need Express-only APIs such as `app.get()`, `app.post()`, or `res.send()`, provide your own Express app explicitly:

```js title="rspack.config.mjs"
import express from 'express';

export default {
  devServer: {
    app: async () => express(),
  },
};
```

## devServer.client

- **Type:** `object`

### logging

- **Type:** `'log' | 'info' | 'warn' | 'error' | 'none' | 'verbose'`
- **Default:** `'info'`

Allows to set log level in the browser, e.g. before reloading, before an error or when HMR is enabled.

```js title="rspack.config.mjs"
export default {
  devServer: {
    client: {
      logging: 'info',
    },
  },
};
```

### overlay

- **Type:** `boolean | object`
- **Default:** `true`

Shows a full-screen overlay in the browser when there are compiler errors or warnings.

```js title="rspack.config.mjs"
export default {
  devServer: {
    client: {
      overlay: true,
    },
  },
};
```

You can provide an object with the following properties for more granular control:

| Property        | Explanation              |
| --------------- | ------------------------ |
| `errors`        | compilation errors       |
| `runtimeErrors` | unhandled runtime errors |
| `warnings`      | compilation warnings     |

All properties are optional and default to `true` when not provided.

For example, to disable compilation warnings, you can provide the following configuration:

```js title="rspack.config.mjs"
export default {
  devServer: {
    client: {
      overlay: {
        errors: true,
        warnings: false,
        runtimeErrors: true,
      },
    },
  },
};
```

To filter based on the thrown error, you can pass a function that accepts an `error` parameter and returns a boolean.

For example, to ignore errors thrown by [`AbortController.abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort):

```js title="rspack.config.mjs"
export default {
  devServer: {
    client: {
      overlay: {
        runtimeErrors: (error) => {
          if (error instanceof DOMException && error.name === 'AbortError') {
            return false;
          }
          return true;
        },
      },
    },
  },
};
```

:::warning
The function will not have access to the variables declared in the outer scope within the configuration file.
:::

### progress

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

Prints compilation progress in percentage in the browser.

```js title="rspack.config.mjs"
export default {
  devServer: {
    client: {
      progress: true,
    },
  },
};
```

### reconnect

- **Type:** `boolean | number`
- **Default:** `true`

Tells dev server the number of times it should try to reconnect the client. When `true` it will try to reconnect unlimited times.

```js title="rspack.config.mjs"
export default {
  devServer: {
    client: {
      reconnect: true,
    },
  },
};
```

When set to `false` it will not try to reconnect.

```js title="rspack.config.mjs"
export default {
  devServer: {
    client: {
      reconnect: false,
    },
  },
};
```

You can also specify the exact number of times the client should try to reconnect.

```js title="rspack.config.mjs"
export default {
  devServer: {
    client: {
      reconnect: 5,
    },
  },
};
```

### webSocketTransport

- **Type:** `'ws' | string`
- **Default:** `ws`

This option allows us to provide a custom client implementation. This allows specifying how the browser or other client communicates with the `devServer`.

To create a custom client implementation, create a class that extends BaseClient.

Using path to `CustomClient.js`, a custom WebSocket client implementation, along with the compatible `'ws'` server:

```js title="rspack.config.mjs"
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);

export default {
  devServer: {
    client: {
      webSocketTransport: require.resolve('./CustomClient'),
    },
    webSocketServer: 'ws',
  },
};
```

Using custom, compatible WebSocket client and server implementations:

```js title="rspack.config.mjs"
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);

export default {
  devServer: {
    client: {
      webSocketTransport: require.resolve('./CustomClient'),
    },
    webSocketServer: require.resolve('./CustomServer'),
  },
};
```

:::tip
When providing a custom client and server implementation make sure that they are compatible with one another to communicate successfully.
:::

### webSocketURL

- **Type:** `string | object`
- **Default:** `{}`

This option allows specifying URL to web socket server (useful when you're proxying dev server and client script does not always know where to connect to).

```js title="rspack.config.mjs"
export default {
  devServer: {
    client: {
      webSocketURL: 'ws://0.0.0.0:8080/ws',
    },
  },
};
```

You can also specify an object with the following properties:

- `hostname`: Tells clients connected to devServer to use the provided hostname.
- `pathname`: Tells clients connected to devServer to use the provided path to connect.
- `password`: Tells clients connected to devServer to use the provided password to authenticate.
- `port`: Tells clients connected to devServer to use the provided port.
- `protocol`: Tells clients connected to devServer to use the provided protocol.
- `username`: Tells clients connected to devServer to use the provided username to authenticate.

```js title="rspack.config.mjs"
export default {
  devServer: {
    client: {
      webSocketURL: {
        hostname: '0.0.0.0',
        pathname: '/ws',
        password: 'dev-server',
        port: 8080,
        protocol: 'ws',
        username: 'rspack',
      },
    },
  },
};
```

:::tip
To get `protocol`/`hostname`/`port` from browser use `webSocketURL: 'auto://0.0.0.0:0/ws'`.
:::

## devServer.compress

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

Enable [gzip compression](https://betterexplained.com/articles/how-to-optimize-your-site-with-gzip-compression/) for everything served:

```js title="rspack.config.mjs"
export default {
  devServer: {
    compress: true,
  },
};
```

## devServer.devMiddleware

- **Type:** `object`
- **Default:** `{}`

Provide options to [`@rspack/dev-middleware`](https://github.com/rstackjs/rspack-dev-middleware), which serves Rspack build assets from the dev server.

```js title="rspack.config.mjs"
export default {
  devServer: {
    devMiddleware: {
      index: true,
      mimeTypes: { phtml: 'text/html' },
      publicPath: '/publicPathForDevServe',
      serverSideRender: true,
      writeToDisk: true,
    },
  },
};
```

## devServer.headers

- **Type:** `array | function | object`
- **Default:** `undefined`

Adds headers to all responses:

```js title="rspack.config.mjs"
export default {
  devServer: {
    headers: {
      'X-Custom-Foo': 'bar',
    },
  },
};
```

You can also pass an array:

```js title="rspack.config.mjs"
export default {
  devServer: {
    headers: [
      {
        key: 'X-Custom',
        value: 'foo',
      },
      {
        key: 'Y-Custom',
        value: 'bar',
      },
    ],
  },
};
```

You can also pass a function:

```js title="rspack.config.mjs"
export default {
  devServer: {
    headers: () => {
      return { 'X-Bar': ['key1=value1', 'key2=value2'] };
    },
  },
};
```

## devServer.historyApiFallback

- **Type:** `boolean | object`
- **Default:** `false`

When using the [HTML5 History API](https://developer.mozilla.org/en-US/docs/Web/API/History), the `index.html` page will likely have to be served in place of any `404` responses. Enable `devServer.historyApiFallback` by setting it to `true`:

```js title="rspack.config.mjs"
export default {
  devServer: {
    historyApiFallback: true,
  },
};
```

By providing an object this behavior can be controlled further using options like `rewrites`:

```js title="rspack.config.mjs"
export default {
  devServer: {
    historyApiFallback: {
      rewrites: [
        { from: /^\/$/, to: '/views/landing.html' },
        { from: /^\/subpage/, to: '/views/subpage.html' },
        { from: /./, to: '/views/404.html' },
      ],
    },
  },
};
```

When using dots in your path (common with Angular), you may need to use the `disableDotRule`:

```js title="rspack.config.mjs"
export default {
  devServer: {
    historyApiFallback: {
      disableDotRule: true,
    },
  },
};
```

For more options and information, see the [connect-history-api-fallback](https://github.com/bripkens/connect-history-api-fallback) documentation.

## devServer.host

- **Type:** `'local-ip' | 'local-ipv4' | 'local-ipv6' | string`
- **Default:** `'local-ip'`

Specify a host to use. If you want your server to be accessible externally, specify it like this:

```js title="rspack.config.mjs"
export default {
  devServer: {
    host: '0.0.0.0',
  },
};
```

### local-ip

Specifying `local-ip` as host will try to resolve the host option as your local `IPv4` address if available, if `IPv4` is not available it will try to resolve your local `IPv6` address.

### local-ipv4

Specifying `local-ipv4` as host will try to resolve the host option as your local `IPv4` address.

### local-ipv6

Specifying local-ipv6 as host will try to resolve the host option as your local IPv6 address.

## devServer.ipc

- **Type:** `boolean | string`
- **Default:** `undefined`

Listen on an IPC socket instead of a host and port.

When set to `true`, `@rspack/dev-server` uses a default socket path named `rspack-dev-server.sock` in the operating system temporary directory, or a Windows named pipe path on Windows. When set to a string, that string is used as the custom socket path.

```js title="rspack.config.mjs"
export default {
  devServer: {
    ipc: true,
  },
};
```

Use a custom socket path:

```js title="rspack.config.mjs"
export default {
  devServer: {
    ipc: '/tmp/rspack-dev-server.sock',
  },
};
```

## devServer.hot

- **Type:** `boolean | 'only'`
- **Default:** `true`

Enable Rspack's hot module replacement feature:

```js title="rspack.config.mjs"
export default {
  devServer: {
    hot: true,
  },
};
```

To enable HMR without page refresh as a fallback in case of build failures, use `hot: 'only'`:

```js title="rspack.config.mjs"
export default {
  devServer: {
    hot: 'only',
  },
};
```

## devServer.liveReload

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

By default, the dev server will reload/refresh the page when file changes are detected. [`devServer.hot`](#devserverhot) option must be disabled or [`devServer.watchFiles`](#devserverwatchfiles) option must be enabled in order for `liveReload` to take effect. Disable `devServer.liveReload` by setting it to `false`:

```js title="rspack.config.mjs"
export default {
  devServer: {
    liveReload: false,
  },
};
```

:::tip
Live reloading works only with web related [targets](/config/target.md) like `web`, `webworker`, `electron-renderer` and `node-webkit`.
:::

## devServer.onListening

- **Type:** `function (devServer)`

Provides the ability to execute a custom function when @rspack/dev-server starts listening for connections on a port.

```js title="rspack.config.mjs"
export default {
  devServer: {
    onListening: function (devServer) {
      if (!devServer) {
        throw new Error('@rspack/dev-server is not defined');
      }

      const port = devServer.server.address().port;
      console.log('Listening on port:', port);
    },
  },
};
```

## devServer.open

- **Type:** `boolean | string | object | (string | object)[]`
- **Default:** `true`

Tells dev server to open the browser after server had been started. Set it to `true` to open your default browser.

```js title="rspack.config.mjs"
export default {
  devServer: {
    open: true,
  },
};
```

:::info
When using `rspack dev` or `rspack serve`, you can override this option from the CLI with `--open`, `--open <value>`, or `--no-open`. When using `rspack preview`, this option is also respected, and `--open` takes precedence over `devServer.open` in the configuration.
:::

To open a specified page in a browser:

```js title="rspack.config.mjs"
export default {
  devServer: {
    open: ['/my-page'],
  },
};
```

To open multiple specified pages in browser:

```js title="rspack.config.mjs"
export default {
  devServer: {
    open: ['/my-page', '/another-page'],
  },
};
```

Provide browser name to use instead of the default one:

```js title="rspack.config.mjs"
export default {
  devServer: {
    open: {
      app: {
        name: 'google-chrome',
      },
    },
  },
};
```

The object accepts all [open](https://www.npmjs.com/package/open) options:

```js title="rspack.config.mjs"
export default {
  devServer: {
    open: {
      target: ['first.html', 'http://localhost:8080/second.html'],
      app: {
        name: 'google-chrome',
        arguments: ['--incognito', '--new-window'],
      },
    },
  },
};
```

:::tip
The browser application name is platform-dependent. Don't hard code it in reusable modules. For example, `'Chrome'` is `'Google Chrome'` on macOS, `'google-chrome'` on Linux, and `'chrome'` on Windows.
:::

## devServer.port

- **Type:** `'auto' | string | number`
- **Default:** `[]`

Specify a port number to listen for requests on:

```js title="rspack.config.mjs"
export default {
  devServer: {
    port: 8080,
  },
};
```

`port` option can't be `null` or an empty string, to automatically use a free port please use `port: 'auto'`:

```js title="rspack.config.mjs"
export default {
  devServer: {
    port: 'auto',
  },
};
```

## devServer.proxy

- **Type:** `ProxyConfigArray`

Configure proxy rules for the dev server, and forward requests to the specified service.

This feature is powered by [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware). You can use [all options](https://github.com/chimurai/http-proxy-middleware#options) provided by `http-proxy-middleware`.

### Basic usage

Forward `/api/*` requests to `https://example.com`:

```js title="rspack.config.mjs"
export default {
  devServer: {
    proxy: [
      {
        // http://localhost:8080/api -> https://example.com/api
        // http://localhost:8080/api/users -> https://example.com/api/users
        pathFilter: '/api',
        target: 'https://example.com',
      },
    ],
  },
};
```

You can also proxy to a local service:

```js title="rspack.config.mjs"
export default {
  devServer: {
    proxy: [
      {
        // http://localhost:8080/api -> http://localhost:3000/api
        // http://localhost:8080/api/foo -> http://localhost:3000/api/foo
        pathFilter: '/api',
        target: 'http://localhost:3000',
      },
    ],
  },
};
```

### Path rewrite

Use `pathRewrite` to rewrite request paths, for example rewriting `/foo` to `/bar` on the target service:

```js title="rspack.config.mjs"
export default {
  devServer: {
    proxy: [
      {
        // http://localhost:8080/foo -> https://example.com/bar
        // http://localhost:8080/foo/baz -> https://example.com/bar/baz
        pathFilter: '/foo',
        target: 'https://example.com',
        pathRewrite: { '^/foo': '/bar' },
      },
    ],
  },
};
```

### Path filter

`pathFilter` matches request paths for proxying, and supports strings, arrays, and functions. `context` is an alias of `pathFilter`.

```js title="rspack.config.mjs"
export default {
  devServer: {
    proxy: [
      {
        // Only proxy /api traffic that is not an HTML request.
        // http://localhost:8080/api/users -> https://example.com/api/users
        pathFilter: (pathname, req) => {
          const accept = req.headers.accept || '';
          return pathname.startsWith('/api') && !accept.includes('html');
        },
        target: 'https://example.com',
      },
    ],
  },
};
```

## devServer.server

- **Type:** `'http' | 'https' | 'http2' | string | object`
- **Default:** `'http'`

Allows to set server and options (by default `'http'`).

```js title="rspack.config.mjs"
export default {
  devServer: {
    server: 'http',
  },
};
```

To serve over `HTTPS` with a self-signed certificate:

```js title="rspack.config.mjs"
export default {
  devServer: {
    server: 'https',
  },
};
```

To serve over `HTTP/2` with a self-signed certificate:

```js title="rspack.config.mjs"
export default {
  devServer: {
    server: 'http2',
  },
};
```

:::tip
If you use `server: 'https'` or `server: 'http2'` without providing `server.options.key` and `server.options.cert`, install [`selfsigned`](https://www.npmjs.com/package/selfsigned) in your project so dev server can automatically generate a local certificate.
:::

Use the object syntax to provide your own certificate:

```js title="rspack.config.mjs"
export default {
  devServer: {
    server: {
      type: 'https',
      options: {
        ca: './path/to/server.pem',
        pfx: './path/to/server.pfx',
        key: './path/to/server.key',
        cert: './path/to/server.crt',
        passphrase: '@rspack/dev-server',
        requestCert: true,
      },
    },
  },
};
```

It also allows you to set additional [TLS options](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options) like `minVersion` and you can directly pass the contents of respective files:


**ESM**

```js title="rspack.config.mjs"
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

export default {
  devServer: {
    server: {
      type: 'https',
      options: {
        minVersion: 'TLSv1.1',
        key: fs.readFileSync(path.join(__dirname, './server.key')),
        pfx: fs.readFileSync(path.join(__dirname, './server.pfx')),
        cert: fs.readFileSync(path.join(__dirname, './server.crt')),
        ca: fs.readFileSync(path.join(__dirname, './ca.pem')),
        passphrase: '@rspack/dev-server',
        requestCert: true,
      },
    },
  },
};
```


**CJS**

```js title="rspack.config.cjs"
const fs = require('node:fs');
const path = require('node:path');

module.exports = {
  devServer: {
    server: {
      type: 'https',
      options: {
        minVersion: 'TLSv1.1',
        key: fs.readFileSync(path.join(__dirname, './server.key')),
        pfx: fs.readFileSync(path.join(__dirname, './server.pfx')),
        cert: fs.readFileSync(path.join(__dirname, './server.crt')),
        ca: fs.readFileSync(path.join(__dirname, './ca.pem')),
        passphrase: '@rspack/dev-server',
        requestCert: true,
      },
    },
  },
};
```


## devServer.setupExitSignals

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

Whether `@rspack/dev-server` registers `SIGINT` and `SIGTERM` handlers to gracefully stop the dev server and close the compiler before exiting the process.

Set it to `false` when another process manager or test runner owns signal handling.

```js title="rspack.config.mjs"
export default {
  devServer: {
    setupExitSignals: false,
  },
};
```

## devServer.setupMiddlewares

- **Type:** `function (middlewares, devServer)`

Provides the ability to execute a custom function and apply custom middleware(s).

```js title="rspack.config.mjs"
export default {
  devServer: {
    setupMiddlewares: (middlewares, devServer) => {
      if (!devServer) {
        throw new Error('@rspack/dev-server is not defined');
      }

      // Use the `unshift` method if you want to run a middleware before all other middlewares
      // or when you are migrating from the `onBeforeSetupMiddleware` option
      middlewares.unshift({
        name: 'first-in-array',
        // `path` is optional
        path: '/foo/path',
        middleware: (req, res) => {
          res.setHeader('Content-Type', 'text/plain; charset=utf-8');
          res.end('Foo!');
        },
      });

      // Use the `push` method if you want to run a middleware after all other middlewares
      // or when you are migrating from the `onAfterSetupMiddleware` option
      middlewares.push({
        name: 'hello-world-test-one',
        // `path` is optional
        path: '/foo/bar',
        middleware: (req, res) => {
          res.setHeader('Content-Type', 'text/plain; charset=utf-8');
          res.end('Foo Bar!');
        },
      });

      middlewares.push((req, res) => {
        res.setHeader('Content-Type', 'text/plain; charset=utf-8');
        res.end('Hello World!');
      });

      return middlewares;
    },
  },
};
```

## devServer.static

- **Type:**

```ts
type DevServerStatic =
  string | boolean | DevServerStaticItem | (string | DevServerStaticItem)[];
```

This option controls how the dev server serves static files from disk. These files are read directly from the file system and are not processed by Rspack.

By default, the `public` directory is served.

You can use the following forms:

- `boolean`: `false` disables static file serving; `true` serves the default `public` directory with the default options.
- `string`: shorthand for `static.directory`.
- `object`: configure one static directory.
- `array`: configure multiple static directories.

Set it to `false` to disable static file serving:

```js title="rspack.config.mjs"
export default {
  devServer: {
    static: false,
  },
};
```

When set to a string, it is equivalent to configuring `static.directory`:

```js title="rspack.config.mjs"
export default {
  devServer: {
    static: 'assets',
  },
};
```

To serve multiple static directories, pass an array:

```js title="rspack.config.mjs"
export default {
  devServer: {
    static: ['assets', 'css'],
  },
};
```

### directory

- **Type:** `string`
- **Default:** `path.join(process.cwd(), 'public')`

Tells the server which directory to read static files from, the value is an absolute path.

`directory` only controls which folder is read from disk. It does not decide where Rspack compilation assets are served from. The URL prefix for these static files is controlled by [`static.publicPath`](#publicpath).

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  devServer: {
    static: {
      directory: path.join(import.meta.dirname, 'public'),
    },
  },
};
```

Provide an array of objects if you have multiple static folders:

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  devServer: {
    static: [
      {
        directory: path.join(import.meta.dirname, 'assets'),
      },
      {
        directory: path.join(import.meta.dirname, 'css'),
      },
    ],
  },
};
```

It is recommended to use an absolute path.

### staticOptions

- **Type:** `object`

Allows configuring lower-level options for serving files. See the [express.static](https://expressjs.com/en/api.html#express.static) documentation for the available options.

```js title="rspack.config.mjs"
export default {
  devServer: {
    static: {
      staticOptions: {
        redirect: true,
      },
    },
  },
};
```

### publicPath

- **Type:** `string | string[]`
- **Default:** `'/'`

Tells the server at which URL to serve the content from [`static.directory`](#directory).

For example, to serve the file `assets/manifest.json` at `/serve-public-path-url/manifest.json`, configure it like this:

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  devServer: {
    static: {
      directory: path.join(import.meta.dirname, 'assets'),
      publicPath: '/serve-public-path-url',
    },
  },
};
```

Provide an array of objects if you have multiple static folders with different URL prefixes:

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  devServer: {
    static: [
      {
        directory: path.join(import.meta.dirname, 'assets'),
        publicPath: '/serve-public-path-url',
      },
      {
        directory: path.join(import.meta.dirname, 'css'),
        publicPath: '/other-serve-public-path-url',
      },
    ],
  },
};
```

You can also mount the same static directory on multiple URL prefixes:

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  devServer: {
    static: {
      directory: path.join(import.meta.dirname, 'public'),
      publicPath: ['/assets', '/shared-assets'],
    },
  },
};
```

### watch

- **Type:** `boolean | object`

Controls whether files in [`static.directory`](#directory) are watched for changes. By default, changes to static files trigger a full page reload. Set it to `false` to disable watching.

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  devServer: {
    static: {
      directory: path.join(import.meta.dirname, 'public'),
      watch: false,
    },
  },
};
```

You can also pass an object to configure advanced watch options. See the [`chokidar`](https://github.com/paulmillr/chokidar) documentation for the available options.

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  devServer: {
    static: {
      directory: path.join(import.meta.dirname, 'public'),
      watch: {
        ignored: (filePath) => filePath.endsWith('.txt'),
        usePolling: false,
      },
    },
  },
};
```

## devServer.watchFiles

- **Type:** `string | string[] | object | (string | object)[]`

This option allows you to configure a list of directories/files to watch for file changes, implemented based on [`chokidar`](https://github.com/paulmillr/chokidar).

When files matched by `watchFiles` change, dev server triggers a full page refresh in the browser. This is mainly useful for watching files outside the Rspack's module graph, such as HTML templates or other non-bundled assets.

For example, watch a couple of directories and ignore everything except `.php` files:

```js title="rspack.config.mjs"
export default {
  devServer: {
    watchFiles: {
      paths: ['src', 'public'],
      options: {
        ignored: (filePath, stats) => {
          if (!stats?.isFile()) {
            return false;
          }

          return !filePath.endsWith('.php');
        },
      },
    },
  },
};
```

You can also provide an array when you need multiple entries:

```js title="rspack.config.mjs"
export default {
  devServer: {
    watchFiles: [
      'templates',
      {
        paths: 'public',
        options: {
          usePolling: false,
        },
      },
    ],
  },
};
```

:::tip

- For more advanced options, see the [`chokidar`](https://github.com/paulmillr/chokidar) documentation.
- If [`devServer.liveReload`](#devserverlivereload) is set to `false`, changes to these watched files will not refresh the browser.

:::

## devServer.webSocketServer

- **Type:** `boolean | 'ws' | string | object`

This option allows you to provide custom WebSocket server implementation.

The current default mode is `'ws'`. This mode uses [ws](https://www.npmjs.com/package/ws) as a server, and native WebSockets on the client.

For example, using custom WebSocket client and server implementations:

```js title="rspack.config.mjs"
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);

export default {
  devServer: {
    client: {
      webSocketTransport: require.resolve('./CustomClient'),
    },
    webSocketServer: require.resolve('./CustomServer'),
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/dev-server/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/devtool.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Devtool

The `devtool` option controls the debugging information Rspack generates for output code, including whether source maps are generated, how they are emitted, and their mapping precision. The selected value affects how well browser development tools and error monitoring services can map bundled code back to the original source. It also affects build speed and the risk of exposing source code.

- **Type:**

```ts
type Devtool = string | false;
```

- **Default:** `cheap-module-source-map` in development mode and `false` in production mode

## Recommended configurations

The following examples use `process.env.NODE_ENV` to distinguish development from production.

### Development only

If you only need debugging information during development and do not need source maps in production, use the following configuration:

```js title="rspack.config.mjs"
const isDev = process.env.NODE_ENV === 'development';

export default {
  devtool: isDev ? 'cheap-module-source-map' : false,
};
```

- **Development:** Uses `cheap-module-source-map` to generate line-level source maps, balancing debugging accuracy and build speed.
- **Production:** Sets `devtool` to `false`, so no source maps are emitted and no source map generation overhead is added.

### Disabled everywhere

If neither environment needs source maps, use the following configuration:

```js title="rspack.config.mjs"
export default {
  devtool: false,
};
```

This configuration has the lowest build overhead and does not emit `.map` files. The tradeoff is that browser errors and production stack traces can only point to bundled code and cannot be mapped back to the original source.

### Enabled everywhere

If you want fast source maps during development and complete line and column mappings in production, use the following configuration:

```js title="rspack.config.mjs"
const isDev = process.env.NODE_ENV === 'development';

export default {
  devtool: isDev ? 'cheap-module-source-map' : 'source-map',
};
```

- **Development:** Uses the faster `cheap-module-source-map`.
- **Production:** Uses `source-map`, which emits a separate `.map` file with line and column mappings and adds a `sourceMappingURL` comment to the bundle. As long as the `.map` file is accessible, browser development tools can load it automatically. This is useful for debugging production code directly, but it increases build time and may expose your source code to users.

### Hidden production reference

If you need production source maps to reconstruct error stack traces but do not want browsers to discover them automatically from the bundle, use the following configuration:

```js title="rspack.config.mjs"
const isDev = process.env.NODE_ENV === 'development';

export default {
  devtool: isDev ? 'cheap-module-source-map' : 'hidden-source-map',
};
```

- **Development:** Uses the faster `cheap-module-source-map`.
- **Production:** Uses `hidden-source-map`, which emits a separate `.map` file with complete line and column mappings but does not add a `//# sourceMappingURL` comment to the bundle. This is useful when uploading source maps privately to an error monitoring service to reconstruct production stack traces.

:::warning
`hidden-source-map` only removes the reference from the bundle; it does not encrypt or protect the `.map` file. Unless you explicitly intend to publish your source code, do not deploy production `.map` files to a publicly accessible web server or CDN. Upload them to an access-controlled error monitoring service instead.
:::

## Common values

The following table compares the mapping precision, output format, and typical use of common values.

| Value                     | Mapping                                     | Output                                          | Typical use                                           |
| ------------------------- | ------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------- |
| `cheap-module-source-map` | Original source with line maps only         | Usually a separate `.map` file                  | Balancing debugging accuracy and build speed          |
| `cheap-source-map`        | Transformed code with line maps only        | Usually a separate `.map` file                  | Development without mapping to original source        |
| `eval`                    | Module names only; no source mapping        | Wraps each module in `eval()`                   | Locating modules during development                   |
| `eval-source-map`         | Original source with line and column maps   | Per-module map embedded in its `eval()`         | Precise debugging during development                  |
| `false`                   | No source map                               | None                                            | Debugging information is not needed                   |
| `hidden-source-map`       | Original source with line and column maps   | Separate `.map` file without a bundle reference | Private uploads to error monitoring services          |
| `inline-source-map`       | Original source with line and column maps   | Map embedded in the bundle as a Data URL        | Distributing a single file for development or testing |
| `nosources-source-map`    | Line and column maps without source content | Separate `.map` file with a bundle reference    | Mapping without embedding source in the map           |
| `source-map`              | Original source with line and column maps   | Separate `.map` file with a bundle reference    | Debugging production code directly                    |

## Modifiers

Without modifiers, `source-map` emits a separate `.map` file with line and column mappings and adds a `sourceMappingURL` comment to the bundle. Add the following modifiers to change how the map is emitted, its mapping precision, or its contents.

### `eval`

Wraps each module in `eval()`. When combined with `source-map` as `eval-source-map`, each module's source map is written to its `eval()` as a Data URL. This avoids combining source maps at the chunk level and improves rebuild performance. This modifier is normally used only in development.

Using `devtool: 'eval'` by itself does not generate a source map. Instead, a `//# sourceURL` comment gives each module a readable name. This identifies the module but cannot map generated code back to the original source.

### `inline`

Embeds the source map in the bundle as a Data URL instead of emitting a separate `.map` file, as in `inline-source-map`. This is convenient when distributing a single file, but it significantly increases bundle size. By default, the source map also includes source content in the bundle; combining it with `nosources` omits that content. This modifier is therefore normally limited to development or testing.

### `hidden`

Emits a separate `.map` file without adding a `//# sourceMappingURL` comment to the bundle, as in `hidden-source-map`. Browsers do not discover the file automatically, making it suitable for private uploads to error monitoring services. It does not prevent users from accessing a publicly deployed `.map` file directly.

### `nosources`

Removes `sourcesContent` from the source map, as in `nosources-source-map`. The map still contains original filenames, directory structure, and mapping information, so it can reconstruct stack traces, but it cannot provide the original source content to development tools on its own.

### `cheap`

Generates line mappings only, omitting column mappings to reduce source map computation, as in `cheap-source-map`. On its own, it ignores source maps provided by loaders, so mappings point to loader-transformed code rather than the original source.

:::tip
In production builds with minification enabled, no source map file may be emitted when using the `cheap` modifier, such as `cheap-source-map` or `cheap-module-source-map`. This is expected: minified code typically occupies a single line, while `cheap` provides line-level mappings only. A `.map` file may still be emitted when minification is disabled.
:::

### `module`

Used only together with `cheap`, as in `cheap-module-source-map`. It processes source maps provided by loaders so line mappings point back to the original source. Compared with `cheap-source-map`, it produces more accurate mappings at a slightly higher computation cost. Without `cheap`, `source-map` already processes loader source maps, so `module` is unnecessary.

### `debugids`

The `debugids` modifier adds a `debugId` to the source map following the [TC39 Debug ID proposal](https://github.com/tc39/ecma426/blob/main/proposals/debug-id.md). For example, with `source-map-debugids`, Rspack also adds a matching `//# debugId` comment to the corresponding output asset so error monitoring tools can associate the build artifact with its source map.

Rspack validates modifier order. Values must match `[inline-|hidden-|eval-][nosources-][cheap-[module-]]source-map[-debugids]`. The `inline`, `hidden`, and `eval` modifiers are mutually exclusive, `module` can only follow `cheap`, and `debugids` must appear at the end.

## Related options

- [`output.sourceMapFilename`](/config/output.md#outputsourcemapfilename) customizes the name of separate source map files.
- [`output.devtoolModuleFilenameTemplate`](/config/output.md#outputdevtoolmodulefilenametemplate), [`output.devtoolFallbackModuleFilenameTemplate`](/config/output.md#outputdevtoolfallbackmodulefilenametemplate), and [`output.devtoolNamespace`](/config/output.md#outputdevtoolnamespace) control module names in source maps and avoid naming conflicts across builds.
- [`rules[].extractSourceMap`](/config/module-rules.md#rulesextractsourcemap) extracts an existing source map from an input file's `sourceMappingURL` comment.

## Fine-grained control

For finer-grained control over source map generation, set `devtool` to `false` and use [SourceMapDevToolPlugin](/plugins/source-map-dev-tool-plugin.md) instead. For `eval`-based source maps, use [EvalSourceMapDevToolPlugin](/plugins/eval-source-map-dev-tool-plugin.md) instead.


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/devtool/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/entry.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Entry

- **Type:**

```ts
type EntryStatic =
  string | string[] | Record<string, string | string[] | EntryDescription>;

type Entry = EntryStatic | (() => EntryStatic | Promise<EntryStatic>);
```

- **Default:** `'./src/index.js'`

The `entry` configuration is used to set the entry module for Rspack builds.

## Single entry

If you are building a single page application or a library, you will usually only need to set up a single entry point.

To set up a single entry, simply pass the path to the entry module as a string to the `entry` configuration.

```js title="rspack.config.mjs"
export default {
  entry: './src/index.js',
};
```

The above writing method will automatically set the name of the entry module to `main`, which is equivalent to the following writing method:

```js title="rspack.config.mjs"
export default {
  entry: {
    main: './src/index.js',
  },
};
```

### Path type

The path of the entry module can be a relative path or an absolute path.

If `entry` is set as a relative path, Rspack will use the value set by [context configuration](/config/context.md) as the base path, which by default is the current working directory of the Node.js process, namely `process.cwd()`.

You can also use the [path module](https://nodejs.org/api/path.html) in Node.js to generate an absolute path and pass it to the `entry` configuration:

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  entry: path.join(__dirname, './src/index.js'),
};
```

### Entry array

When setting the value of an entry, in addition to setting it to `string`, you can also pass in a `string[]`, meaning that the entry contains multiple entry modules.

For example, the following example will build `pre.js` and `post.js` into the output of `page`.

```js title="rspack.config.mjs"
export default {
  entry: {
    page: ['./src/pre.js', './src/post.js'],
  },
};
```

When an array is used for an entry, Rspack still creates a single chunk for that entry. Modules in the array are loaded in declaration order and merged into the same dependency graph, so `pre.js` runs before `post.js`.

This pattern is commonly used to inject extra code before the main application entry, such as polyfills or development-only tooling, without adding manual imports in application source files.

**Example: Injecting a polyfill**

```js title="rspack.config.mjs"
export default {
  entry: {
    main: ['./src/polyfill.js', './src/index.js'],
  },
};
```

## Multiple entries

If you need to build multiple entries at once, you should set `entry` to an object, and each key of the object corresponds to an entry name.

For example, the following example will build `page1` and `page2` as two entries:

```js title="rspack.config.mjs"
export default {
  entry: {
    page1: './src/page1/index.js',
    page2: './src/page2/index.js',
  },
};
```

### Entry description object

When you set `entry` to an object, you can set the value of the entry to a description object. A description object can contain the following properties:

#### EntryDescription.import


- Type: `string[] | string`
- Default:`'./src/index.js'`


The path or paths to the entry modules.

```js title="rspack.config.mjs"
export default {
  entry: {
    foo: {
      import: './src/foo.js',
    },
  },
};
```

Multiple paths can be set in the `import` property:

```js title="rspack.config.mjs"
export default {
  entry: {
    foo: {
      import: ['./src/foo.js', './src/bar.js'],
    },
  },
};
```

#### EntryDescription.runtime


- Type: `false | string`
- Default:`undefined`


The name of the runtime chunk. When `runtime` is set, a new runtime chunk will be created. You can also set it to `false` to avoid a new runtime chunk.

The `runtime` property is used to set the name of the runtime chunk, for example to set the name of the `main` entry chunk to `'foo'`:

```js title="rspack.config.mjs"
export default {
  entry: {
    main: {
      import: './src/index.js',
      runtime: 'foo',
    },
  },
};
```

#### EntryDescription.chunkLoading


- Type: `false | string | 'jsonp' | 'import-scripts' | 'require' | 'async-node' | 'import'`
- Default:`undefined`


How this entry load other chunks. Methods included by default are `'jsonp'` (web), `'import'` (ESM), `'import-scripts'` (WebWorker), `'require'` (sync node.js), `'async-node'` (async node.js), but others might be added by plugins.

#### EntryDescription.asyncChunks


- Type: `boolean`
- Default:`true`


Whether to create a load-on-demand asynchronous chunk for this entry.

#### EntryDescription.publicPath


- Type: `'auto' | string | (pathData: PathData, assetInfo?: AssetInfo) => string`
- Default:`undefined`


The publicPath of the resource referenced by this entry.

#### EntryDescription.baseUri


- Type: `string`
- Default:`undefined`


The baseURI of the resource referenced by this entry.

#### EntryDescription.filename


- Type: `string | ((pathData: PathData, assetInfo?: AssetInfo) => string)`
- Default:`undefined`


The filename of the entry chunk.

#### EntryDescription.library

- **Type:** `LibraryOptions`
- **Default:** `undefined`

The format of the chunk generated by this entry as a library, for detailed configuration, see [output.library](/config/output.md#outputlibrary).

#### EntryDescription.dependOn


- Type: `string[] | string`
- Default:`undefined`


The entry that the current entry depends on. With `dependOn` option you can share the modules from one entry chunk to another.

#### EntryDescription.wasmLoading


- Type: `false | 'fetch' | 'async-node' | 'universal'`
- Default:`undefined`


Option to set the method of loading WebAssembly Modules for this entry. When omitted, the value of [`output.wasmLoading`](/config/output.md#outputwasmloading) is used.

The default value of [`output.wasmLoading`](/config/output.md#outputwasmloading) can be affected by different [target](/config/target.md):

- Defaults to `'fetch'` if target is set to `'web'`, `'webworker'`, `'electron-renderer'` or `'node-webkit'`.
- Defaults to `'async-node'` if target is set to `'node'`, `'async-node'`, `'electron-main'` or `'electron-preload'`.

#### EntryDescription.layer


- Type: `string | null | undefined`
- Default:`undefined`


Specifies the layer in which modules of this entrypoint are placed. Make the corresponding configuration take effect through layer matching in split chunks, [rules](/config/module-rules.md#rulesissuerlayer), stats, and externals.

For more information about layers, see the [Module layers guide](/guide/advanced/layer.md).

```js title="rspack.config.mjs"
export default {
  entry: {
    index: {
      import: './src/index.js',
      layer: 'layer-name',
    },
  },
};
```

## Dynamic entry

If a function is passed then it will be invoked on every [make](/api/plugin-api/compiler-hooks.md#make) event.

> Note that the `make` event triggers when Rspack starts and for every invalidation when [watching for file changes](/config/watch.md).

```js title="rspack.config.mjs"
export default {
  entry: () => './demo',
};
```

Or:

```js title="rspack.config.mjs"
export default {
  entry: () => new Promise((resolve) => resolve(['./demo', './demo2'])),
};
```

For example: you can use dynamic entries to get the actual entries from an external source (remote server, file system content or database):

```js title="rspack.config.mjs"
export default {
  entry() {
    return fetchPathsFromSomeExternalSource(); // returns a promise that will be resolved with something like ['src/main-layout.js', 'src/admin-layout.js']
  },
};
```

When combining with the [output.library](/config/output.md#outputlibrary) option: If an array is passed only the last item is exported.


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/entry-context/#entry) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/experiments.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Experiments

Enables experimental features.

- **Type:** `object`

:::tip
In minor releases, Rspack may change the APIs of experimental features. If you're using experimental features, pay attention to the minor release notes for detailed explanations of changes.
:::

## experiments.asyncWebAssembly

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

Supports the new WebAssembly according to the [updated specification](https://github.com/WebAssembly/esm-integration), making WebAssembly modules async.

```js title="rspack.config.mjs"
export default {
  experiments: {
    asyncWebAssembly: true,
  },
};
```

## experiments.buildHttp


[Added in v1.3.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.3.0)

- **Type:** `HttpUriOptions`
- **Default:** `undefined`

```ts
type HttpUriOptions = {
  /**
   * A list of allowed URIs
   */
  allowedUris: (string | RegExp)[];
  /**
   * Define the location to store the lockfile
   */
  lockfileLocation?: string;
  /**
   * Define the location for caching remote resources
   */
  cacheLocation?: string | false;
  /**
   * Detect changes to remote resources and upgrade them automatically
   * @default false
   */
  upgrade?: boolean;
  /**
   * Custom http client
   */
  httpClient?: (
    url: string,
    headers: Record<string, string>,
  ) => Promise<{
    status: number;
    headers: Record<string, string>;
    body: Buffer;
  }>;
};
```

After enabling this feature, Rspack can build remote resources that start with the `http(s):` protocol. Rspack will download the resources to the local machine and then bundle them.

By default, Rspack will generate `rspack.lock` and `rspack.lock.data` in the [context](/config/context.md) folder as the locations of the Lockfile and the cache respectively. You can also configure them through `lockfileLocation` and `cacheLocation`.

:::note
You should commit the files at `lockfileLocation` and `cacheLocation` to the version control system so that no network requests will be made during the production build.
:::

For example:

```js title="rspack.config.mjs"
export default {
  experiments: {
    buildHttp: {
      allowedUris: ['https://'],
      lockfileLocation: path.join(__dirname, 'my_project.lock'),
      cacheLocation: path.join(__dirname, 'my_project.lock.data'),
    },
  },
};
```

With this feature enabled, you can import modules directly from URLs:

```js
// Import from a remote URL
import { something } from 'https://example.com/module.js';

// Or import assets
import imageUrl from 'https://example.com/image.png';
```

## experiments.deferImport


[Added in v1.6.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.6.0)

- **Type:** `boolean`
- **Default:** `false`

When enabled, Rspack will support bundling the [Deferred Imports Evaluation](https://github.com/tc39/proposal-defer-import-eval) proposal, which allows deferring the evaluation of a module until its first use. Rspack supports both `import defer * as ns from "./module"` and `import.defer()` syntax.

```js title="rspack.config.mjs"
export default {
  experiments: {
    deferImport: true,
  },
};
```

:::info Known Limitation
Currently, when using `output.module: true`, `defer import` syntax for external modules will be compiled to standard `import` syntax.

For example, if `jquery` is configured as external:

```js
import defer * as $ from 'jquery';
```

It will generate:

```js
import * as __rspack_external_jquery from 'jquery';
```

This is because `defer import` syntax is not yet supported by any runtime. In the future, Rspack will support preserving `defer import` syntax based on the target configuration, generating the following code:

```js
import defer * as __rspack_external_jquery from 'jquery';
```

:::

## experiments.sourceImport


[Added in v2.0.8](https://github.com/web-infra-dev/rspack/releases/tag/v2.0.8)

Stability: Experimental

- **Type:** `boolean`
- **Default:** `false`

Enables support for the TC39 [Source Phase Imports](https://github.com/tc39/proposal-source-phase-imports) proposal.

Source phase imports let you import a module before it is evaluated. In Rspack, this support is currently designed for WebAssembly modules: importing a `.wasm` module in the source phase returns a compiled [`WebAssembly.Module`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Module), so you can instantiate it yourself, instantiate it more than once with different imports, or transfer it to a worker.

Enable `experiments.sourceImport`:

```js title="rspack.config.mjs"
export default {
  experiments: {
    sourceImport: true,
  },
};
```

You can use the static source-phase syntax:

```js
import source wasmModule from './module.wasm';

const instance = await WebAssembly.instantiate(wasmModule, {
  // imports...
});
```

Or the dynamic syntax:

```js
const wasmModule = await import.source('./module.wasm');
const instance = await WebAssembly.instantiate(wasmModule);
```

:::note
For a normal WebAssembly import, Rspack instantiates the module and exposes its exports. For a source phase import, Rspack returns the compiled `WebAssembly.Module` instead, and your code is responsible for calling `WebAssembly.instantiate`.
:::

## experiments.futureDefaults

- **Type:** `boolean`
- **Default:** `false`

Uses defaults from the next major Rspack version and shows warnings for any problematic configuration.

```js title="rspack.config.mjs"
export default {
  experiments: {
    futureDefaults: true,
  },
};
```

## experiments.nativeWatcher


[Added in v1.4.7](https://github.com/web-infra-dev/rspack/releases/tag/v1.4.7)

- **Type:** `boolean`
- **Default:** `false`

By default, Rspack uses Watchpack to monitor file changes, which generally works well in most scenarios.
However, in certain specific environments, issues may arise. For example, Watchpack may experience performance problems when there are a large number of file changes.
More detail see: [Watchpack issue #223](https://github.com/webpack/watchpack/issues/223).

If you encounter performance issues with the default watcher, you can try enabling nativeWatcher.

After enabling `nativeWatcher`, Rspack will use the Rust Native file system to monitor file changes, enabling incremental file change detection, which provides better performance and stability.

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    // Other watch options...
  },
  experiments: {
    nativeWatcher: true,
  },
};
```

## experiments.pureFunctions


[Added in v2.0.0](https://github.com/web-infra-dev/rspack/releases/tag/v2.0.0)

- **Type:** `boolean`
- **Default:** `true` in production mode, `false` otherwise

Enables cross-module side-effect-free function call optimization, including the `/*#__NO_SIDE_EFFECTS__*/` annotation and [`module.parser.javascript.pureFunctions`](/config/module-parser.md#javascriptpurefunctions). Functions marked through annotations or user configuration are omitted from the output when they are not actually used.

For more background, see [pureFunctions](/guide/optimization/tree-shaking.md#purefunctions) and [NO\_SIDE\_EFFECTS annotation](/guide/optimization/tree-shaking.md#no_side_effects-annotation).

This capability is enabled by default in production mode. To disable pure-function analysis, set this option to `false`. To manually mark identifiers in matched modules — exported functions in a third-party module, or imports/locals in your own files — configure [`module.parser.javascript.pureFunctions`](/config/module-parser.md#javascriptpurefunctions) through `module.rules[i].parser` so the rule only applies to the intended modules.

```js title="rspack.config.mjs"
export default {
  experiments: {
    pureFunctions: true,
  },
  module: {
    rules: [
      {
        test: /node_modules\/some-library\/index\.js$/,
        parser: {
          pureFunctions: ['isString'],
        },
      },
    ],
  },
};
```

:::warning
This option depends on `optimization.sideEffects`. If you disable [`optimization.sideEffects`](/config/optimization.md#optimizationsideeffects), pure-function hints will not be analyzed.
:::

## experiments.runtimeMode


[Added in v2.2.0](https://github.com/web-infra-dev/rspack/releases/tag/v2.2.0)

- **Type:** `'webpack' | 'rspack'`
- **Default:** `'webpack'`

Setting `experiments.runtimeMode` to `'rspack'` enables Rspack's experimental runtime output. This output mode is still under development, so use it with caution. It currently generates cleaner output when [`output.module`](/config/output.md#outputmodule) is `true` and [`output.library.type`](/config/output.md#outputlibrarytype) is `'modern-module'`. In this case, instead of exporting one `__webpack_require__` function with runtime helpers attached as properties, the runtime exports the loader, module factories, and helpers as named ESM bindings. Each output chunk can import only the bindings it needs.

### Example

```js title="rspack.config.mjs"
export default {
  experiments: {
    runtimeMode: 'rspack',
  },
  output: {
    module: true,
    library: {
      type: 'modern-module',
    },
  },
  optimization: {
    runtimeChunk: 'single',
  },
};
```

The generated runtime and a chunk that consumes it are organized like this (simplified):


**runtimeMode: 'webpack'**

```js
// runtime.js
var __webpack_modules__ = {};
function __webpack_require__(moduleId) {
  /* ... */
}
__webpack_require__.m = __webpack_modules__;
__webpack_require__.n = (module) => {
  /* ... */
};

export { __webpack_require__ };

// main.js
import { __webpack_require__ } from './runtime.js';

const value = __webpack_require__(moduleId);
const getDefault = __webpack_require__.n(value);
```


**runtimeMode: 'rspack'**

```js
// runtime.js
var modules = {};
function rspackRequire(moduleId) {
  /* ... */
}
var moduleFactories = modules;
var compatGetDefaultExport = (module) => {
  /* ... */
};

export { rspackRequire, moduleFactories, compatGetDefaultExport };

// main.js
import { rspackRequire, compatGetDefaultExport } from './runtime.js';

const value = rspackRequire(moduleId);
const getDefault = compatGetDefaultExport(value);
```


## experiments.useInputFileSystem


[Added in v1.3.14](https://github.com/web-infra-dev/rspack/releases/tag/v1.3.14)

- **Type:** `false | RegExp[]`
- **Default:** `false`

By default, Rspack reads files from disk using a native file system.
However, it is possible to change the file system using a different kind of file system.
To accomplish this, one can change the inputFileSystem. For example, you can replace the default inputFileSystem with memfs to virtual Modules.

But due to the overheads calling file system implemented in Node.js side, it will slow down Rspack a lot.
So we make a trade off by providing the `useInputFileSystem` config, to tell rspack to read file from the native file system or from modified inputFileSystem.

In below example, you can simply replace the default input file system to any file system satisfied the [`InputFileSystem`](/api/javascript-api/compiler.md#inputfilesystem-1) interface.

:::info Note
The replacing of `compiler.inputFileSystem` will only take effect before `compiler.run` called; Replacing after `compiler.run` will not take effect.
:::

More detailed case can be found [here](https://github.com/web-infra-dev/rspack/tree/main/tests/rspack-test/configCases/input-file-system/rspack.config.js)

```js title="rspack.config.mjs"
export default {
  entry: {
    index: './virtual_index.js',
  },
  plugins: [
    {
      apply: (compiler) => {
        compiler.hooks.beforeCompile.tap('SimpleInputFileSystem', () => {
          compiler.inputFileSystem = {
            readFile(path, cb) {
              cb(null, `// the file content`);
            },
            stat(p, cb) {
              cb(null, fsState);
            },
          };
        });
      },
    },
  ],
  experiments: {
    useInputFileSystem: [/virtual_.*\.js/],
  },
};
```

### Work with webpack-virtual-modules

```js title="rspack.config.mjs"
import VirtualModulesPlugin from 'webpack-virtual-modules';

const virtualModules = new VirtualModulesPlugin({
  'virtual-entry.js': `
    import "./src/another-virtual.js";
    import "./src/disk-file.js";
    `,
  'src/another-virtual.js': 'export default 42;',
});

export default {
  entry: './virtual-entry.js',
  plugins: [virtualModules],
  experiments: {
    useInputFileSystem: [/.*virtual.*\.js$/],
  },
};
```

When access to `virtual-entry.js` and `src/another-virtual.js` which match the regular expressions of `experiments.useInputFileSystem`,
Rspack will use the input file system wrapped by `VirtualModulesPlugin`; other than that, `src/disk-file.js` will be accessed by the native file system.


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/experiments/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/extends.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Extends

Used to extend configurations from other files or packages. This allows you to create a base configuration and extend it for different environments or use cases.

- **Type:** `string | string[]`
- **Default:** `undefined`

:::info
This option is only supported in [`@rspack/cli`](/api/cli.md).

If you are using the JavaScript API or other Rspack-based tools, `extends` will not take effect, use [rspack-merge](/config.md#rspack-merge) instead.
:::

## Basic usage

You can extend a configuration from another file by specifying the path to the file in the `extends` property. The path can be absolute or relative to the configuration file:


**ESM**

```js title="rspack.config.mjs"
export default {
  extends: './base.rspack.config.mjs',
  // Override or add to the base configuration
  output: {
    filename: '[name].bundle.js',
  },
};
```


**CJS**

```js title="rspack.config.cjs"
module.exports = {
  extends: './base.rspack.config.cjs',
  // Override or add to the base configuration
  output: {
    filename: '[name].bundle.js',
  },
};
```


:::tip
When using relative paths, they are resolved relative to the configuration file that contains the `extends` property.
:::

## Multiple configurations

- **Type:** `string[]`
- **Default:** `undefined`

You can extend multiple configurations by providing an array of paths. Configurations are merged from right to left, meaning that the rightmost configuration will be merged into the leftmost one, and so on:

```js title="rspack.config.mjs"
export default {
  extends: ['./base.rspack.config.mjs', './dev.rspack.config.mjs'],
  // Additional configuration options
  plugins: [
    // Add more plugins
  ],
};
```

:::info Merge Behavior
`@rspack/cli` uses [rspack-merge](https://github.com/rstackjs/rspack-merge) internally to merge configurations. The default merge rules are:

- Simple values are overwritten
- Arrays are concatenated
- Objects are deeply merged

:::

## Node modules

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

You can also extend configurations from packages installed in your node\_modules. The package should export a valid Rspack configuration:

```js title="rspack.config.mjs"
export default {
  extends: 'some-rspack-config-package',
  // Override or add to the package's configuration
};
```

## Nested extends

Configurations can have their own `extends` property, allowing for nested configuration inheritance. The resolution is performed recursively:

```js title="base.rspack.config.mjs"
export default {
  extends: './core.rspack.config.mjs',
  // Base configuration options
};
```

```js title="rspack.config.mjs"
export default {
  extends: './base.rspack.config.mjs',
  // Environment-specific configuration options
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/configuration-types/#exporting-multiple-configurations) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/externals.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Externals

Externals specify which modules Rspack should not bundle, and instead read directly from implementations provided by the external environment.

For example, if a page already includes `React` from a CDN, or if a library expects the consumer to install `react` themselves, you can declare it as an external. This reduces bundle size and avoids shipping the same dependency twice.

This capability is commonly used when building libraries, but it is also useful in applications that integrate CDN assets or rely on dependencies injected by the host environment.

- **Type:**

```ts
type ExternalItem =
  string | RegExp | Function | { [x: string]: ExternalItemValue };

type Externals = ExternalItem | ExternalItem[];
```

## Basic usage

For example, if the page already includes [Day.js](https://day.js.org/) from a CDN, you can declare it as an external to avoid bundling it again:

```html title="index.html"
<script src="https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js"></script>
```

```js title="rspack.config.mjs"
export default {
  externals: {
    dayjs: 'dayjs',
  },
};
```

In this case, the `dayjs` module is removed from the bundle and resolved from the external environment at runtime, so code like this still works:

```js
import dayjs from 'dayjs';

console.log(dayjs().format('YYYY-MM-DD'));
```

In the configuration above, the key `dayjs` under `externals` matches the module specifier in `import dayjs from 'dayjs'`, meaning that module should not be bundled.

The value `dayjs` is then used to access the global variable at runtime. In this basic configuration, the default [externalsType](#externalstype) is `var`, which means Rspack reads it from the global scope. In a browser, this usually means accessing `window.dayjs`.

### String

In the example above, the value of `externals` uses the string form. The meaning of that string depends on [externalsType](#externalstype).

In general, the string can represent:

- a **global variable name** for types such as [`'var'`](#externalstypevar), [`'window'`](#externalstypewindow), [`'global'`](#externalstypeglobal), and [`'this'`](#externalstypethis)
- or a **module name** for types such as [`'module'`](#externalstypemodule) and [`'commonjs'`](#externalstypecommonjs)

#### Shorthand syntax

If you only need to declare one external, you can use the shorter form:

```js title="rspack.config.mjs"
export default {
  externals: 'lodash', // equivalent to externals: { lodash: 'lodash' }
};
```

#### Matching rules

String externals use **exact matching**.

For example, the configuration below matches `react-dom`, but it does not match subpath imports such as `react-dom/client`:

```js title="rspack.config.mjs"
export default {
  externals: {
    'react-dom': 'react-dom',
  },
  externalsType: 'module-import',
};
```

If you want those subpath imports to be externalized as well, list them explicitly:

```js title="rspack.config.mjs"
export default {
  externals: {
    'react-dom': 'react-dom',
    'react-dom/client': 'react-dom/client',
  },
  externalsType: 'module-import',
};
```

If you need to match a family of similar import specifiers, use a [regular expression](#regexp) instead.

#### Specifying the external type

You can also specify the external type explicitly with the `${externalsType} ${libraryName}` syntax. This overrides the default value from [externalsType](#externalstype).

For example, if the external dependency is provided as an ES module:

```js title="rspack.config.mjs"
export default {
  externals: {
    react: 'module-import react',
  },
};
```

### string\[]\{#string-array}

```js title="rspack.config.mjs"
export default {
  externals: {
    subtract: ['./math', 'subtract'],
  },
};
```

`subtract: ['./math', 'subtract']` allows you select part of a module, where `./math` is the module and your bundle only requires the subset under the `subtract` variable.

When the `externalsType` is `commonjs`, this example would translate to `require('./math').subtract;` while when the `externalsType` is `window`, this example would translate to `window["./math"]["subtract"];`

Similar to the [string syntax](#string), you can specify the external library type with the `${externalsType} ${libraryName}` syntax, in the first item of the array, for example:

```js title="rspack.config.mjs"
export default {
  externals: {
    subtract: ['commonjs ./math', 'subtract'],
  },
};
```

### object

:::warning
An object with `{ root, commonjs, commonjs2, amd, ... }` is only allowed for [`library.type: 'umd'`](/config/output.md#outputlibrarytype) and [`externalsType: 'umd'`](#externalstype). It's not allowed for other library targets.
:::

```js title="rspack.config.mjs"
export default {
  externals: {
    // When `library.type: 'umd'` and `externalsType: 'umd'`, the following format must be strictly followed:
    lodash: {
      root: '_', // indicates global variable
      commonjs: 'lodash',
      commonjs2: 'lodash',
      amd: 'lodash',
    },
  },
};
```

This syntax is used to describe all the possible ways that an external library can be made available. `lodash` here is available as `lodash` under AMD and CommonJS module systems but available as `_` in a global variable form. `subtract` here is available via the property `subtract` under the global `math` object (e.g. `window['math']['subtract']`).

### function

- **Type:**
  - `function ({ context, request, contextInfo, getResolve }, callback)`
  - `function ({ context, request, contextInfo, getResolve }) => promise`

It might be useful to define your own function to control the behavior of what you want to externalize from Rspack. [webpack-node-externals](https://www.npmjs.com/package/webpack-node-externals), for example, excludes all modules from the `node_modules` directory and provides options to allowlist packages.

Here're arguments the function can receive:

- `ctx` (`object`): Object containing details of the file.
  - `ctx.context` (`string`): The directory of the file which contains the import.
  - `ctx.request` (`string`): The import path being requested.
  - `ctx.contextInfo` (`object`): Contains information about the issuer (e.g. the layer and compiler)
  - `ctx.getResolve`: Get a resolve function with the current resolver options.
- `callback` (`function (err, result, type)`): Callback function used to indicate how the module should be externalized.

The callback function takes three arguments:

- `err` (`Error`): Used to indicate if there has been an error while externalizing the import. If there is an error, this should be the only parameter used.
- `result` (`string | string[] | object | boolean`): Describes the external module.
  - `string | string[] | object`: Describes the external module with the other external formats ([`string`](#string), [`string[]`](#string-array), or [`object`](#object)).
  - `boolean`: Passing `true` externalizes the dependency using the original request path as the external module name. Passing `false` tells Rspack to skip the remaining external configuration and bundle the dependency instead.
- `type` (`string`): Optional parameter that indicates the module [external type](#externalstype) (if it has not already been indicated in the `result` parameter).

As an example, to externalize all imports where the import path matches a regular expression you could do the following:

```js title="rspack.config.mjs"
export default {
  externals: [
    function ({ context, request }, callback) {
      if (/^yourregex$/.test(request)) {
        // Externalize to a commonjs module using the request path
        return callback(null, 'commonjs ' + request);
      }

      // Continue without externalizing the import
      callback();
    },
  ],
};
```

Other examples using different module formats:

```js title="rspack.config.mjs"
export default {
  externals: [
    function (ctx, callback) {
      // The external is a `commonjs2` module located in `@scope/library`
      callback(null, '@scope/library', 'commonjs2');
    },
  ],
};
```

```js title="rspack.config.mjs"
export default {
  externals: [
    function (ctx, callback) {
      // The external is a global variable called `nameOfGlobal`.
      callback(null, 'nameOfGlobal');
    },
  ],
};
```

```js title="rspack.config.mjs"
export default {
  externals: [
    function (ctx, callback) {
      // The external is a named export in the `@scope/library` module.
      callback(null, ['@scope/library', 'namedexport'], 'commonjs');
    },
  ],
};
```

```js title="rspack.config.mjs"
export default {
  externals: [
    function (ctx, callback) {
      // The external is a UMD module
      callback(null, {
        root: 'componentsGlobal',
        commonjs: '@scope/components',
        commonjs2: '@scope/components',
        amd: 'components',
      });
    },
  ],
};
```

### RegExp

You can also use a regular expression to match modules that should be externalized. Any module specifier that matches the pattern will be excluded from the output bundle.

```js title="rspack.config.mjs"
export default {
  externals: /react-dom/i,
};
```

In this example, any module specifier matching `react-dom` will be externalized, including `react-dom` and `react-dom/client`.

### Combining syntaxes

Sometimes you may want to use a combination of the above syntaxes. This can be done in the following manner:

```js title="rspack.config.mjs"
export default {
  externals: [
    {
      // String
      react: 'react',
      // Object
      lodash: {
        commonjs: 'lodash',
        amd: 'lodash',
        root: '_', // indicates global variable
      },
      // [string]
      subtract: ['./math', 'subtract'],
    },
    // Function
    function ({ context, request }, callback) {
      if (/^yourregex$/.test(request)) {
        return callback(null, 'commonjs ' + request);
      }
      callback();
    },
    // Regex
    /^(jquery|\$)$/i,
  ],
};
```

:::warning
[Default type](#externalstype) will be used if you specify `externals` without a type e.g. `externals: { react: 'react' }` instead of `externals: { react: 'commonjs-module react' }`.
:::

## externalsType

- **Type:** `string`

`externalsType` determines how Rspack loads external dependencies by default. When using the `'amd'`, `'umd'`, `'system'`, or `'jsonp'` type, [`output.library.type`](/config/output.md#outputlibrarytype) must be set to the same value. For example, only an `'amd'` library can use an `'amd'` external.

Set `externalsType` explicitly when an external dependency needs a loading format different from the inferred value.

### Default value

The default value is inferred in this order:

- If [`output.library`](/config/output.md#outputlibrary) is configured with a type other than `'modern-module'`, `externalsType` defaults to [`output.library.type`](/config/output.md#outputlibrarytype).
- Otherwise, if [`output.module`](/config/output.md#outputmodule) is `true`, it defaults to `'module-import'`.
- Otherwise, it defaults to `'var'`.

For backward compatibility, [`output.library.type: 'modern-module'`](/config/output.md#outputlibrarytype) currently skips the first rule and falls through to the `output.module` rule. Set `externalsType: 'modern-module'` explicitly to opt in to modern module externals.

### Supported values

The following types are supported:

- `'amd'`
- `'amd-require'`
- `'assign'` - same as `'var'`
- [`'commonjs'`](#externalstypecommonjs)
- `'commonjs2'`
- `'commonjs-module'`
- `'commonjs-static'`
- [`'global'`](#externalstypeglobal)
- [`'module'`](#externalstypemodule)
- [`'import'`](#externalstypeimport) - uses `import()` to load a native ECMAScript module (async module)
- [`'module-import'`](#externalstypemodule-import)
- [`'modern-module'`](#externalstypemodern-module)
- [`'commonjs-import'`](#externalstypecommonjs-import)
- `'jsonp'`
- [`'node-commonjs'`](#externalstypenode-commonjs)
- [`'promise'`](#externalstypepromise) - same as `'var'` but awaits the result (async module)
- [`'self'`](#externalstypeself)
- `'system'`
- [`'script'`](#externalstypescript)
- [`'this'`](#externalstypethis)
- `'umd'`
- `'umd2'`
- [`'var'`](#externalstypevar)
- [`'window'`](#externalstypewindow)

```js title="rspack.config.mjs"
export default {
  externalsType: 'promise',
};
```

### externalsType.commonjs

Specify the default type of externals as `'commonjs'`. Rspack will generate code like `const X = require('...')` for externals used in a module.

**Example**

```js
import fs from 'fs-extra';
```

```js title="rspack.config.mjs"
export default {
  externalsType: 'commonjs',
  externals: {
    'fs-extra': 'fs-extra',
  },
};
```

Will generate into something like:

```js
const fs = require('fs-extra');
```

Note that there will be a `require()` in the output bundle.

### externalsType.global

Specify the default type of externals as `'global'`. Rspack will read the external as a global variable on the [`globalObject`](/config/output.md#outputglobalobject).

**Example**

```js
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

```js title="rspack.config.mjs"
export default {
  externalsType: 'global',
  externals: {
    jquery: '$',
  },
  output: {
    globalObject: 'global',
  },
};
```

Will generate into something like

```js
const jq = global['$'];
jq('.my-element').animate(/* ... */);
```

### externalsType.module

Specify the default type of externals as `'module'`. Rspack will generate code like `import * as X from '...'` for externals used in a module.

Make sure to enable [`output.module`](/config/output.md#outputmodule).

**Example**

```js
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

```js title="rspack.config.mjs"
export default {
  output: {
    module: true,
  },
  externalsType: 'module',
  externals: {
    jquery: 'jquery',
  },
};
```

Will generate into something like

```js
import * as __rspack_external_jquery from 'jquery';

const jq = __rspack_external_jquery['default'];
jq('.my-element').animate(/* ... */);
```

Note that there will be an `import` statement in the output bundle.

### externalsType.import

Specify the default type of externals as `'import'`. Rspack will generate code like `import('...')` for externals used in a module.

**Example**

```js
async function foo() {
  const jq = await import('jquery');
  jq('.my-element').animate(/* ... */);
}
```

```js title="rspack.config.mjs"
export default {
  externalsType: 'import',
  externals: {
    jquery: 'jquery',
  },
};
```

Will generate into something like

```js
var __webpack_modules__ = {
  jquery: (module) => {
    module.exports = import('jquery');
  },
};

// Rspack runtime...

async function foo() {
  const jq = await Promise.resolve(/* import() */).then(
    __webpack_require__.bind(__webpack_require__, 'jquery'),
  );
  jq('.my-element').animate(/* ... */);
}
```

Note that there will be an `import()` statement in the output bundle.

### externalsType\['module-import']

Specify the default type of externals as `'module-import'`. This combines [`'module'`](#externalstypemodule) and [`'import'`](#externalstypeimport). Rspack will automatically detect the type of import syntax, setting it to `'module'` for static imports and `'import'` for dynamic imports.

**Example**

```js
import { attempt } from 'lodash';

async function foo() {
  const jq = await import('jquery');
  attempt(() => jq('.my-element').animate(/* ... */));
}
```

```js title="rspack.config.mjs"
export default {
  externalsType: 'module-import',
  externals: {
    lodash: 'lodash',
    jquery: 'jquery',
  },
};
```

Will generate into something like

```js
import * as __rspack_external_lodash from 'lodash';
const lodash = __rspack_external_jquery;

var __webpack_modules__ = {
  jquery: (module) => {
    module.exports = import('jquery');
  },
};

// Rspack runtime...

async function foo() {
  const jq = await Promise.resolve(/* import() */).then(
    __webpack_require__.bind(__webpack_require__, 'jquery'),
  );
  (0, lodash.attempt)(() => jq('.my-element').animate(/* ... */));
}
```

Note that there will be an `import` or `import()` statement in the output bundle.

When a module is not imported via `import` or `import()`, Rspack will use `"module"` externals type as fallback. If you want to use a different type of externals as fallback, you can specify it with a function in the `externals` option. For example:

```js title="rspack.config.mjs"
export default {
  externalsType: 'module-import',
  externals: [
    function ({ request, dependencyType }, callback) {
      if (dependencyType === 'commonjs') {
        return callback(null, `node-commonjs ${request}`);
      }
      callback();
    },
  ],
};
```

### externalsType\['modern-module']

Specify the default type of externals as `'modern-module'`.

For compatibility, Rspack does not enable this automatically when [`output.library.type`](/config/output.md#outputlibrarytype) is `'modern-module'` yet. Configure `externalsType: 'modern-module'` explicitly to opt in. This will become the default for `modern-module` libraries in the next major version.

For static ESM imports, Rspack renders the external like [`'module'`](#externalstypemodule), using a static `import` statement. For dynamic `import()`, Rspack renders the external like [`'module-import'`](#externalstypemodule-import), using `import()`.

For CommonJS `require()`, Rspack chooses the CommonJS external variant from the target. Node-like targets render the external like [`'node-commonjs'`](#externalstypenode-commonjs) and create a `require` function with `createRequire` in the generated ESM output. Other targets render it like [`'commonjs'`](#externalstypecommonjs), preserving a bare `require()` call.

**Example**

```js title="src/index.js"
import { readFile } from 'node:fs/promises';

const path = require('node:path');

export async function loadConfig(file) {
  const os = await import('node:os');
  const content = await readFile(file, 'utf-8');
  return {
    content,
    dirname: path.dirname(file),
    platform: os.platform(),
  };
}
```

```js title="rspack.config.mjs"
export default {
  target: 'node',
  output: {
    library: {
      type: 'modern-module',
    },
  },
  externalsType: 'modern-module',
  externals: ['node:fs/promises', 'node:path', 'node:os'],
};
```

Because this example targets Node.js, the generated ESM output keeps the static import as an `import` statement, keeps the dynamic import as `import()`, and renders the `require()` external through `createRequire`:

```js
import { createRequire as __rspack_createRequire } from 'node:module';
import { readFile } from 'node:fs/promises';

const __rspack_createRequire_require = __rspack_createRequire(import.meta.url);
const path = __rspack_createRequire_require('node:path');

async function loadConfig(file) {
  const os = await import('node:os');
  // ...
}

export { loadConfig };
```

### externalsType\['commonjs-import']

Specify the default type of externals as `'commonjs-import'`. This combines [`'commonjs'`](#externalstypecommonjs) and [`'import'`](#externalstypeimport). Rspack will automatically detect the type of import syntax, setting dynamic import to `'import'` and leaving others to `'commonjs'`.

This is useful when building a Node.js application that target Node.js version higher than `13.2.0`, which supports both [`import()` expressions](https://nodejs.org/api/esm.html#import-expressions) and `require()`.

:::note
`commonjs-import` type is only available of Rspack, and not applicable for webpack.
:::

**Example**

```js
import { attempt } from 'lodash';

async function foo() {
  const jq = await import('jquery');
  attempt(() => jq('.my-element').animate(/* ... */));
}
```

```js title="rspack.config.mjs"
export default {
  externalsType: 'commonjs-import',
  externals: {
    lodash: 'lodash',
    jquery: 'jquery',
  },
};
```

Will generate into something like

```js
var __webpack_modules__ = {
  lodash: function (module) {
    module.exports = require('lodash');
  },
  jquery: function (module) {
    module.exports = import('jquery');
  },
};

// Rspack runtime...

async function foo() {
  const jq = await Promise.resolve(/* import() */).then(
    __webpack_require__.bind(__webpack_require__, 'jquery'),
  );
  (0, lodash__rspack_import_0__.attempt)(() =>
    jq('.my-element').animate(/* ... */),
  );
}
```

Note that there will be an `import()` statement in the output bundle.

### externalsType\['node-commonjs']

Specify the default type of externals as `'node-commonjs'`. Rspack will import [`createRequire`](https://nodejs.org/api/module.html#module_module_createrequire_filename) from `'module'` to construct a require function for loading externals used in a module.

**Example**

```js
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

```js title="rspack.config.mjs"
export default {
  externalsType: 'node-commonjs',
  externals: {
    jquery: 'jquery',
  },
};
```

Will generate into something like

```js
import { createRequire } from 'node:module';

const jq = createRequire(import.meta.url)('jquery');
jq('.my-element').animate(/* ... */);
```

Note that there will be an `import` statement in the output bundle.

### externalsType.promise

Specify the default type of externals as `'promise'`. Rspack will read the external as a global variable (similar to [`'var'`](#externalstypepromise)) and `await` for it.

**Example**

```js
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

```js title="rspack.config.mjs"
export default {
  externalsType: 'promise',
  externals: {
    jquery: '$',
  },
};
```

Will generate into something like

```js
const jq = await $;
jq('.my-element').animate(/* ... */);
```

### externalsType.self

Specify the default type of externals as `'self'`. Rspack will read the external as a global variable on the `self` object.

**Example**

```js
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

```js title="rspack.config.mjs"
export default {
  externalsType: 'self',
  externals: {
    jquery: '$',
  },
};
```

Will generate into something like

```js
const jq = self['$'];
jq('.my-element').animate(/* ... */);
```

### externalsType.script

Specify the default type of externals as `'script'`. Rspack will load the external as a script exposing predefined global variables with HTML `<script>` element. The `<script>` tag would be removed after the script has been loaded.

**Syntax**

```js title="rspack.config.mjs"
export default {
  externalsType: 'script',
  externals: {
    packageName: [
      'http://example.com/script.js',
      'global',
      'property',
      'property',
    ], // properties are optional
  },
};
```

You can also use the shortcut syntax if you're not going to specify any properties:

```js title="rspack.config.mjs"
export default {
  externalsType: 'script',
  externals: {
    packageName: 'global@http://example.com/script.js', // no properties here
  },
};
```

Note that [`output.publicPath`](/config/output.md#outputpublicpath) won't be added to the provided URL.

**Example**

Let's load a `lodash` from CDN:

```js title="rspack.config.mjs"
export default {
  externalsType: 'script',
  externals: {
    lodash: ['https://cdn.jsdelivr.net/npm/lodash@4.17.19/lodash.min.js', '_'],
  },
};
```

Then use it in code:

```js
import _ from 'lodash';
console.log(_.head([1, 2, 3]));
```

Here's how we specify properties for the above example:

```js title="rspack.config.mjs"
export default {
  externalsType: 'script',
  externals: {
    lodash: [
      'https://cdn.jsdelivr.net/npm/lodash@4.17.19/lodash.min.js',
      '_',
      'head',
    ],
  },
};
```

Both local variable `head` and global `window._` will be exposed when you `import` `lodash`:

```js
import head from 'lodash';
console.log(head([1, 2, 3])); // logs 1 here
console.log(window._.head(['a', 'b'])); // logs a here
```

:::tip
When loading code with HTML `<script>` tags, the Rspack runtime will try to find an existing `<script>` tag that matches the `src` attribute or has a specific `data-rspack` attribute. For chunk loading `data-rspack` attribute would have value of `'[output.uniqueName]:chunk-[chunkId]'` while external script has value of `'[output.uniqueName]:[global]'`.

Options like `output.chunkLoadTimeout`, `output.crossOriginLoading` and `output.scriptType` will also have effect on the external scripts loaded this way.
:::

### externalsType.this

Specify the default type of externals as `'this'`. Rspack will read the external as a global variable on the `this` object.

**Example**

```js
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

```js title="rspack.config.mjs"
export default {
  externalsType: 'this',
  externals: {
    jquery: '$',
  },
};
```

Will generate into something like

```js
const jq = this['$'];
jq('.my-element').animate(/* ... */);
```

### externalsType.var

Specify the default type of externals as `'var'`. Rspack will read the external as a global variable.

**Example**

```js
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

```js title="rspack.config.mjs"
export default {
  externalsType: 'var',
  externals: {
    jquery: '$',
  },
};
```

Will generate into something like

```js
const jq = $;
jq('.my-element').animate(/* ... */);
```

### externalsType.window

Specify the default type of externals as `'window'`. Rspack will read the external as a global variable on the `window` object.

**Example**

```js
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

```js title="rspack.config.mjs"
export default {
  externalsType: 'window',
  externals: {
    jquery: '$',
  },
};
```

Will generate into something like

```js
const jq = window['$'];
jq('.my-element').animate(/* ... */);
```

## externalsPresets

- **Type:** `object`

Enable presets of externals for specific targets.

### externalsPresets.electron

**Type:** `boolean`

Treat common electron built-in modules in main and preload context like `electron`, `ipc` or `shell` as external and load them via `require()` when used.

### externalsPresets.electronMain

**Type:** `boolean`

Treat electron built-in modules in the main context like `app`, `ipc-main` or `shell` as external and load them via `require()` when used.

### externalsPresets.electronPreload

**Type:** `boolean`

Treat electron built-in modules in the preload context like `web-frame`, `ipc-renderer` or `shell` as external and load them via require() when used.

### externalsPresets.electronRenderer

**Type:** `boolean`

Treat electron built-in modules in the renderer context like `web-frame`, `ipc-renderer` or `shell` as external and load them via `require()` when used.

### externalsPresets.node

**Type:** `boolean`

Treat node.js built-in modules like `fs`, `path` or `vm` as external and load them via `require()` when used.

### externalsPresets.nwjs

**Type:** `boolean`

Treat `NW.js` legacy `nw.gui` module as external and load it via `require()` when used.

### externalsPresets.web

**Type:** `boolean`

Treat references to `http(s)://...` and `std:...` as external and load them via `import` when used. **(Note that this changes execution order as externals are executed before any other code in the chunk)**.

### externalsPresets.webAsync

**Type:** `boolean`

Treat references to `http(s)://...` and `std:...` as external and load them via `async import()` when used **(Note that this external type is an `async` module, which has various effects on the execution)**.

Note that if you're going to output ES modules with those node.js-related presets, Rspack will set the default `externalsType` to [`node-commonjs`](#externalstypenode-commonjs) which would use `createRequire` to construct a require function instead of using `require()`.

**Example**

Using `node` preset will not bundle built-in modules and treats them as external and loads them via `require()` when used.

```js title="rspack.config.mjs"
export default {
  externalsPresets: {
    node: true,
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/externals/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/incremental.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Incremental

`incremental` controls whether Rspack reuses unaffected intermediate results between compilations in
the same long-lived compiler. It is designed for development rebuilds, watch mode, and Hot Module
Replacement (HMR), where Rspack knows which files changed and can avoid recalculating unaffected
stages and assets.

Incremental is enabled only when `mode` is set to `'development'`. A standalone `rspack build` is a
one-shot build with no previous compilation to update, so `incremental` does not make separate build
invocations incremental.

- **Type:** `boolean | 'none' | 'safe' | 'advance' | 'advance-silent' | Incremental`
- **Default:** `'advance-silent'`

:::tip
Incremental artifacts are independent of [`cache`](/config/cache.md). Disabling cache does not disable incremental rebuilds during development, watch, or HMR.
:::

## Relationship with cache

[`cache`](/config/cache.md) and `incremental` are independent options. Cache stores fine-grained
computation results in memory or filesystem-backed persistent storage. Incremental recovers prior
pass artifacts from the previous compilation, then updates affected work from known mutations.

All four combinations are valid:

| Cache | Incremental | Behavior                                                                                                                                        |
| ----- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Off   | Off         | No state from a prior compilation or build is reused through Cache or Incremental; compilation-local optimizations may still apply.             |
| On    | Off         | Artifact recovery is disabled, but individual computations can still use memory or persistent cache entries.                                    |
| Off   | On          | Development rebuilds recover prior pass artifacts so unaffected portions can be reused, but no fine-grained cache entries are read or written.  |
| On    | On          | Development rebuilds combine prior-artifact recovery with fine-grained cache hits. This is the normal high-performance development combination. |

Cache “On” includes `cache: true`, `cache: { type: 'memory' }`, and
`cache: { type: 'persistent' }`.

Rspack Incremental has a similar optimization goal to webpack's
[`cacheUnaffected`](https://webpack.js.org/configuration/cache/#cachecacheunaffected): avoid
recomputing work that is unaffected by a change. Rspack applies the idea to multiple compilation
stages and exposes it independently from Cache. This is semantic alignment, not configuration
equivalence: webpack requires `cacheUnaffected` to be used with memory cache, while Rspack exposes
`incremental` as an independent top-level option.

## Configuration

`incremental` can be configured with presets or a detailed object.

Most projects can use the default value; configure this option explicitly only when you need to disable incremental builds, fall back to a more conservative strategy, or diagnose incremental build issues.

| Value                       | Behavior                                                                                                                                                                                                               |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `false` / `'none'`          | Disable incremental builds for all stages.                                                                                                                                                                             |
| `'safe'`                    | Enable incremental builds only for the `buildModuleGraph`, `buildChunkGraph`, and `emitAssets` stages.                                                                                                                 |
| `true` / `'advance-silent'` | Enable all incremental stages and silently handle cases that are not friendly to incremental builds. This is the default behavior of Rspack.                                                                           |
| `'advance'`                 | Enable the same stages as `'advance-silent'`, but emit warnings when configuration or plugin behavior causes Rspack to disable incremental passes. This helps identify what is limiting incremental build performance. |

## Examples

By default, you do not need to configure `incremental` explicitly. To surface warnings when configuration or plugin behavior disables incremental passes during development, use `'advance'`:

```js title="rspack.config.mjs"
export default {
  mode: 'development',
  incremental: 'advance',
};
```

You can also configure `incremental` with an object to control each build stage individually. Object configuration is mainly intended for debugging or temporary workarounds; presets are recommended for normal usage.

In object configuration, omitted stage options default to `true`, and `silent` also defaults to
`true`. For example, `{ modulesCodegen: false }` disables only that stage; the other Incremental
stages remain enabled.

```js title="rspack.config.mjs"
export default {
  incremental: {
    silent: false,
    modulesCodegen: false,
  },
};
```

## Type definition

```ts
type Incremental = {
  // Whether to suppress warnings for cases that are not friendly to incremental builds.
  // Set this to false to emit warnings.
  silent?: boolean;
  // The following options control whether incremental builds are enabled for each stage.
  buildModuleGraph?: boolean;
  finishModules?: boolean;
  optimizeDependencies?: boolean;
  buildChunkGraph?: boolean;
  optimizeChunkModules?: boolean;
  moduleIds?: boolean;
  chunkIds?: boolean;
  modulesHashes?: boolean;
  modulesCodegen?: boolean;
  modulesRuntimeRequirements?: boolean;
  chunksRuntimeRequirements?: boolean;
  chunksHashes?: boolean;
  chunkAsset?: boolean;
  emitAssets?: boolean;
};
```

## Performance impact

Incremental improves rebuilds and HMR when a previous compilation and a known change set are
available. It does not make the initial compilation or a separate one-shot build incremental, but
the initial compilation can still prepare artifacts for a later rebuild.

Memory or persistent Cache may independently speed up computations during either an initial build or
a rebuild. In particular, a filesystem Cache hit after process startup is Cache acceleration, not an
incremental build.



---
url: /config/infrastructure-logging.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# InfrastructureLogging

Options for infrastructure level logging. Generally used for logs unrelated to the Compilation.

## infrastructureLogging.appendOnly

- **Type:** `boolean`

Append lines to the output instead of updating existing output, useful for status messages. This option is used only when no custom [console](#infrastructureloggingconsole) is provided.

```js title="rspack.config.mjs"
export default {
  infrastructureLogging: {
    appendOnly: true,
    level: 'verbose',
  },
  plugins: [
    (compiler) => {
      const logger = compiler.getInfrastructureLogger('MyPlugin');
      logger.status('first output'); // this line won't be overridden with `appendOnly` enabled
      logger.status('second output');
    },
  ],
};
```

## infrastructureLogging.colors

- **Type:** `boolean`

Enable colorful output for infrastructure level logging. This option is used only when no custom [console](#infrastructureloggingconsole) is provided.

```js title="rspack.config.mjs"
export default {
  infrastructureLogging: {
    colors: true,
    level: 'verbose',
  },
  plugins: [
    (compiler) => {
      const logger = compiler.getInfrastructureLogger('MyPlugin');
      logger.log('this output will be colorful');
    },
  ],
};
```

## infrastructureLogging.console

- **Type:** `Console`
- **Default:** `Console`

Customize the console used for infrastructure level logging.

```js title="rspack.config.mjs"
export default {
  infrastructureLogging: {
    console: yourCustomConsole(),
  },
};
```

## infrastructureLogging.debug

- **Type:** `boolean | RegExp | function(name) => boolean | [string, RegExp, function(name) => boolean]`
- **Default:** `'false'`

Enable debug information of specified loggers such as plugins or loaders. Similar to [stats.loggingDebug](/config/stats.md#statsloggingdebug) option but for infrastructure. Defaults to `false`.

```js title="rspack.config.mjs"
export default {
  infrastructureLogging: {
    level: 'info',
    debug: ['MyPlugin', /MyPlugin/, (name) => name.includes('MyPlugin')],
  },
};
```

## infrastructureLogging.level

- **Type:** `'none' | 'error' | 'warn' | 'info' | 'log' | 'verbose'`
- **Default:** `'info'`

Enable infrastructure logging output. Similar to [stats.logging](/config/stats.md#statslogging) option but for infrastructure. Defaults to `'info'`.

Possible values:

- `'none'` - disable logging
- `'error'` - errors only
- `'warn'` - errors and warnings only
- `'info'` - errors, warnings, and info messages
- `'log'` - errors, warnings, info messages, log messages, groups, clears. Collapsed groups are displayed in a collapsed state.
- `'verbose'` - log everything except debug and trace. Collapsed groups are displayed in expanded state.

```js title="rspack.config.mjs"
export default {
  infrastructureLogging: {
    level: 'info',
  },
};
```

## infrastructureLogging.stream

- **Type:** `NodeJS.WritableStream`
- **Default:** `process.stderr`

Stream used for logging output. Defaults to `process.stderr`. This option is used only when no custom [console](#infrastructureloggingconsole) is provided.

```js title="rspack.config.mjs"
export default {
  infrastructureLogging: {
    stream: process.stderr,
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/infrastructureLogging/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/lazy-compilation.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# LazyCompilation


[Added in v1.5.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.5.0)

Lazy Compilation is an optimization technique that delays the compilation of modules until they are actually requested. **Modules are only built when they are actually accessed.**

Enable lazy compilation, which can greatly improve the dev startup performance of multi-page applications (MPA) or large single-page applications (SPA).

:::tip
Check out the [guide](/guide/advanced/lazy-compilation.md) for a quick start.
:::

- **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 path that needs to be requested.
       */
      serverUrl?: string;
      /**
       * Customize the prefix used for lazy compilation endpoint.
       * @default "/_rspack/lazy/trigger"
       */
      prefix?: string;
    };
```

## Default behavior

- **JavaScript API:** Lazy compilation is disabled by default. After enabling `lazyCompilation`, register the lazy compilation middleware with your development server. See [Integrating with custom server](/guide/advanced/lazy-compilation.md#integrating-with-custom-server).
- **Rspack CLI:** `rspack dev` registers the middleware automatically. When [`target`](/config/target.md) is limited to a browser environment and `lazyCompilation` is not explicitly configured, it also uses `{ entries: false, imports: true }`. When the option is omitted in other cases, lazy compilation remains disabled.

## Compilation scope

Lazy compilation can be applied to two groups of modules: entry modules and modules loaded through dynamic `import()`. Once enabled, Rspack defers building these modules until they are actually accessed.

For example, if an application has twenty entries, Rspack builds only the entries that are accessed. The remaining entries are built when they are accessed. Modules loaded through dynamic `import()` follow the same behavior.

Setting `lazyCompilation` to `true` enables lazy compilation for both groups:

```js title="rspack.config.mjs"
export default {
  lazyCompilation: true,
};
```

This is equivalent to:

```js title="rspack.config.mjs"
export default {
  lazyCompilation: {
    entries: true,
    imports: true,
  },
};
```

To enable lazy compilation for only one group, use an object and configure [`entries`](#entries) and [`imports`](#imports) separately. `entries` controls entry modules, while `imports` controls modules loaded through dynamic `import()`.

To narrow the scope further, use [`test`](#test) to filter modules. It accepts a regular expression or a function that receives a `Module` and returns a `boolean`.

## Options

### entries

- **Type:** `boolean`
- **Default:** When `entries` is omitted from the configuration object, it defaults to `true`.

Controls whether entry modules are lazily compiled.

When set to `false`, entry modules are built during the initial compilation.

```js title="rspack.config.mjs"
export default {
  lazyCompilation: {
    entries: false,
  },
};
```

### imports

- **Type:** `boolean`
- **Default:** When `imports` is omitted from the configuration object, it defaults to `true`.

Controls whether modules loaded through dynamic `import()` are lazily compiled.

When set to `false`, dynamically imported modules are built during the initial compilation.

```js title="rspack.config.mjs"
export default {
  lazyCompilation: {
    imports: false,
  },
};
```

### test

- **Type:** `RegExp | ((module: Module) => boolean)`
- **Default:** `undefined`

Further filters the entry and dynamically imported modules selected by `entries` and `imports`. When neither option is specified, both default to `true`, so `test` filters both groups. A regular expression is tested against `module.nameForCondition()`, while a function receives the `Module` instance directly. A match or a return value of `true` enables lazy compilation for the module; otherwise, the module is built normally.

```js title="rspack.config.mjs"
export default {
  lazyCompilation: {
    test: /src/,
  },
};
```

See [Filtering modules](/guide/advanced/lazy-compilation.md#filtering-modules) for configuration examples.

### client

- **Type:** `string`
- **Default:** Built-in web or Node.js client, selected automatically

The path to custom runtime code that overrides the default lazy compilation client. By default, Rspack uses the built-in Node.js client when [`externalsPresets.node`](/config/externals.md#externalspresetsnode) is enabled, and the built-in web client otherwise.

- [Client for web](https://github.com/web-infra-dev/rspack/blob/699229b9e7c33b7db7968c2f803f750e0367fe8a/packages/rspack/hot/lazy-compilation-web.js)
- [Client for node](https://github.com/web-infra-dev/rspack/blob/699229b9e7c33b7db7968c2f803f750e0367fe8a/packages/rspack/hot/lazy-compilation-node.js)

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  lazyCompilation: {
    client: path.resolve('custom-client.js'),
  },
};
```

### serverUrl

- **Type:** `string`
- **Default:** `''`

Sets the base URL requested by the lazy compilation client. Rspack appends [`lazyCompilation.prefix`](#prefix) to this value. When omitted, the web client sends requests to the current origin; in a Node.js environment, specify the development server URL explicitly.

```js title="rspack.config.mjs"
export default {
  lazyCompilation: {
    serverUrl: 'http://localhost:3000',
  },
};
```

### prefix

- **Type:** `string`
- **Default:** `'/_rspack/lazy/trigger'`

Customize the prefix used for lazy compilation endpoint. By default, the lazy compilation middleware uses the `/_rspack/lazy/trigger` prefix for handling requests.

```js title="rspack.config.mjs"
export default {
  lazyCompilation: {
    prefix: '/custom-lazy-endpoint-',
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/experiments/#experimentslazycompilation) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/mode.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Mode


- Type: `'production' | 'development' | 'none'`


The `mode` configuration is used to set the build mode of Rspack to enable the default optimization strategy.

## Default value

If `mode` is not specified:

- When using `@rspack/cli`, `rspack dev` and `rspack serve` default to `'development'`, and `rspack build` defaults to `'production'`.
- When using JavaScript API, the `mode` option defaults to `'production'`.

## Usage

You can set the mode directly in Rspack config:

```js title="rspack.config.mjs"
export default {
  mode: 'production',
};
```

In actual scenarios, you can dynamically set the mode according to `process.env.NODE_ENV`:

```js title="rspack.config.mjs"
const isProduction = process.env.NODE_ENV === 'production';

export default {
  mode: isProduction ? 'production' : 'development',
};
```

Alternatively, you can set the mode using the `--mode` option on the Rspack CLI:

```bash
rspack --mode=production
```

:::info
`--mode` option on the CLI has a higher priority than `mode` in Rspack config.
:::

## Optional values

`mode` has the following optional values:

### production

In production mode, Rspack automatically enables the following optimization strategies:

- Set the default value of [optimization.nodeEnv](/config/optimization.md#optimizationnodeenv) to `'production'`, which replaces `process.env.NODE_ENV` in code with `'production'`.
- Set the default value of [optimization.minimize](/config/optimization.md#optimizationminimize) to `true`, and enable the default JavaScript and CSS minimizers.
- Set the default value of [optimization.concatenateModules](/config/optimization.md#optimizationconcatenatemodules) to `true` to enable module concatenation (scope hoisting).
- Set the default values of [optimization.sideEffects](/config/optimization.md#optimizationsideeffects), [optimization.usedExports](/config/optimization.md#optimizationusedexports), [optimization.mangleExports](/config/optimization.md#optimizationmangleexports), and [optimization.innerGraph](/config/optimization.md#optimizationinnergraph) for more aggressive tree shaking and export optimization.
- Set the default values of [optimization.moduleIds](/config/optimization.md#optimizationmoduleids) and [optimization.chunkIds](/config/optimization.md#optimizationchunkids) to `'deterministic'` for more stable long-term caching.
- Set the default value of [optimization.realContentHash](/config/optimization.md#optimizationrealcontenthash) to `true`.

### development

In development mode, Rspack automatically enables the following optimization strategies:

- Set the default value of [optimization.nodeEnv](/config/optimization.md#optimizationnodeenv) to `'development'`, which replaces `process.env.NODE_ENV` in code with `'development'`.
- Set the default value of [devtool](/config/devtool.md) to `'cheap-module-source-map'` for easier debugging.
- Set the default value of [cache](/config/cache.md) to `true` to enable memory caching for faster development builds.
- Set the default values of [optimization.moduleIds](/config/optimization.md#optimizationmoduleids) and [optimization.chunkIds](/config/optimization.md#optimizationchunkids) to `'named'` for more readable module and chunk names.
- Set the default value of [optimization.emitOnErrors](/config/optimization.md#optimizationemitonerrors) to `true`, which keeps emitting output when build fails to support local debugging.

### none

When `mode` is set to `'none'`, Rspack will not enable any default optimization strategies.


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/mode/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/module.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Module

Used to decide how to handle different types of modules in a project.

- **Type:** `Object`
- **Default:** `{}`

## module.defaultRules

- **Type:** `('...' | Rule | Falsy)[]`

`defaultRules` configures the built-in module resolution and processing rules that Rspack enables by default. These rules are applied automatically to ensure that common resource types such as JavaScript, JSON, CSS, and Wasm can be correctly resolved and bundled.

You can extend, override, or disable these default rules to gain finer control over the build behavior.

For example, extending the default rules:

```js title="rspack.config.mjs"
export default {
  module: {
    defaultRules: [
      // Use "..." to reference Rspack’s default rules
      '...',
      // Add a custom rule
      {
        test: /\.foo$/,
        use: ['foo-loader'],
      },
    ],
  },
};
```

If you want to remove all of Rspack's default rules, simply omit `"..."`:

```js title="rspack.config.mjs"
export default {
  module: {
    defaultRules: [],
  },
};
```

:::tip
See the [source code](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack/src/config/defaults.ts#L453) for the full list of default rules.
:::

## module.generator

- **Type:** `Object`
- **Default:** `{}`

Use `module.generator` to define output generation options for each module type, such as asset filenames, public paths, and CSS Modules exports. See [Module Generator](/config/module-generator.md) for details.

## module.noParse

- **Type:**

```ts
type NoParseOption =
  | string
  | RegExp
  | ((request: string) => boolean)
  | (string | RegExp | ((request: string) => boolean))[];
```

- **Default:** `undefined`

Keep module mechanism of the matched modules as-is, such as `module.exports`, `require`, `import`.

It's useful and can boost build performance when used to ignore libraries without external dependencies.

Note: these modules will still be processed by configured loaders.

```js title="rspack.config.mjs"
export default {
  module: {
    noParse: /typescript|watermark-dom/,
  },
};
```

```js title="rspack.config.mjs"
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);

export default {
  module: {
    noParse: [require.resolve('typescript'), /watermark-dom/],
  },
};
```

```js title="rspack.config.mjs"
export default {
  module: {
    noParse: (request) => /typescript|watermark-dom/.test(request),
  },
};
```

## module.parser

- **Type:** `Object`
- **Default:** `{}`

Use `module.parser` to define parser options for each module type, such as dependency collection and how module syntax is interpreted. See [Module Parser](/config/module-parser.md) for details.

## module.rules

See [Module Rules](/config/module-rules.md) for details.


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/module/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/module-generator.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Module generator

`module.generator` controls how Rspack turns parsed modules into output code or emitted assets. It affects output-related behavior such as asset filenames, public paths, CSS Modules exports, and other generation settings for each module type.

## generator

- **Type:** `Object`
- **Default:** `{}`

Use `module.generator` to define output generation options for each module type.

Available generator option groups:

- `asset`, `asset/inline`, `asset/resource`: [Asset generator options](#asset)
- `css`, `css/auto`, `css/global`, `css/module`: [CSS generator options](#cssauto)
- `json`: [JSON generator options](#jsonjsonparse)

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      // Generator options for asset modules
      asset: {
        dataUrl: {
          encoding: false,
          mimetype: 'image/png',
        },
        filename: '[name]-[contenthash][ext]',
        publicPath: 'https://cdn.example.com/',
      },
      // Generator options for asset/inline modules
      'asset/inline': {
        dataUrl: {
          encoding: false,
          mimetype: 'image/png',
        },
      },
      // Generator options for asset/resource modules
      'asset/resource': {
        emit: true,
        filename: '[name]-[contenthash][ext]',
        publicPath: 'https://cdn.example.com/',
      },
      // Generator options for css/auto modules
      'css/auto': {
        exportsConvention: 'as-is',
        exportsOnly: false,
        localIdentHashDigest: 'base64url',
        localIdentHashDigestLength: 6,
        localIdentHashFunction: 'xxhash64',
        localIdentHashSalt: 'my-salt',
        localIdentName: '[uniqueName]-[id]-[local]',
        esModule: true,
      },
      // Generator options for `css` modules
      css: {
        exportsOnly: false,
        esModule: true,
      },
      // Generator options for css/global modules
      'css/global': {
        exportsConvention: 'as-is',
        exportsOnly: false,
        localIdentHashDigest: 'base64url',
        localIdentHashDigestLength: 6,
        localIdentHashFunction: 'xxhash64',
        localIdentHashSalt: 'my-salt',
        localIdentName: '[uniqueName]-[id]-[local]',
        esModule: true,
      },
      // Generator options for css/module modules
      'css/module': {
        exportsConvention: 'as-is',
        exportsOnly: false,
        localIdentHashDigest: 'base64url',
        localIdentHashDigestLength: 6,
        localIdentHashFunction: 'xxhash64',
        localIdentHashSalt: 'my-salt',
        localIdentName: '[uniqueName]-[id]-[local]',
        esModule: true,
      },
      // Generator options for `json` modules
      json: {
        JSONParse: true,
      },
    },
  },
};
```

### asset

Generator options for `asset` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      asset: {
        // options
      },
    },
  },
};
```

### asset.binary

- **Type:** `boolean | undefined`
- **Default:** `undefined`

Whether or not this asset module should be considered binary. This can be set to `false` to treat this asset module as text.
If not set, the module type will be used to determine if the module is binary.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      asset: {
        binary: false,
      },
    },
  },
};
```

### asset.dataUrl

- **Type:** `Object | (source: Buffer, context: { filename: string, module: Module }) => string`
- **Default:** `{}`

Only for modules with module type `'asset'` or `'asset/inline'`.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      asset: {
        dataUrl: {
          encoding: 'base64',
          mimetype: 'image/png',
        },
      },
    },
  },
};
```

When used as a function, it executes for every module and must return a data URI string.

```js title="rspack.config.mjs"
import svgToMiniDataURI from 'mini-svg-data-uri';

export default {
  module: {
    generator: {
      asset: {
        dataUrl: ({ content }) => {
          return svgToMiniDataURI(content);
        },
      },
    },
  },
};
```

### asset.dataUrl.encoding

- **Type:** `false | 'base64'`
- **Default:** `'base64'`

When set to 'base64', module source will be encoded using Base64 algorithm. Setting encoding to false will disable encoding. Only for modules with module type `'asset'` or `'asset/inline'`.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      asset: {
        dataUrl: {
          encoding: false,
        },
      },
    },
  },
};
```

### asset.dataUrl.mimetype

- **Type:** `string`
- **Default:** `require('mime-types').lookup(ext)`

A mimetype for data URI. Resolves from module resource extension by default. Only for modules with module type `'asset'` or `'asset/inline'`.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      asset: {
        dataUrl: {
          mimetype: 'image/png',
        },
      },
    },
  },
};
```

### asset.importMode

- **Type:** `'url' | 'preserve'`
- **Default:** `'url'`

If `"url"`, a URL pointing to the asset will be generated based on [publicPath](#assetpublicpath).
If `"preserve"`, preserve import/require statement from generated asset.

Only for modules with module type `'asset'` or `'asset/resource'`.

- `'asset'`:

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      asset: {
        importMode: 'preserve',
      },
    },
  },
};
```

- `'asset/resource'`:

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        importMode: 'preserve',
      },
    },
  },
};
```

### asset.filename

- **Type:** `string | ((pathData: PathData, assetInfo?: AssetInfo) => string)`
- **Default:** `undefined`
- **Supported Template string:** see [`output.assetModuleFilename`](/config/output.md#outputassetmodulefilename)

Same as `output.assetModuleFilename`. Overrides `output.assetModuleFilename` and only works for `asset` and `asset/resource` module types.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      asset: {
        filename: 'static/[hash][ext]',
      },
    },
  },
};
```

### asset.outputPath

- **Type:** `string | ((pathData: PathData, assetInfo?: AssetInfo) => string)`
- **Default:** `undefined`

Emit the asset in the specified folder relative to [`output.path`](/config/output.md#outputpath).

Only for modules with module type `'asset'` or `'asset/resource'`.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      asset: {
        outputPath: 'foo/',
      },
    },
  },
};
```

### asset.publicPath

- **Type:** `string | ((pathData: PathData, assetInfo?: AssetInfo) => string)`
- **Default:** `undefined`

Override [`output.publicPath`](/config/output.md#outputpublicpath), only for modules with module type `'asset'` or `'asset/resource'`.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      asset: {
        publicPath: 'https://cdn.example.com/',
      },
    },
  },
};
```

### asset.emit

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

Whether to output assets to disk. You can set this option to `false` to avoid outputting unnecessary files for some scenarios such as SSR.

Only for modules with module type `'asset'` or `'asset/resource'`.

- `'asset'`:

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      asset: {
        emit: false,
      },
    },
  },
};
```

- `'asset/resource'`:

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        emit: false,
      },
    },
  },
};
```

### \["asset/inline"]

Generator options for `asset/inline` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/inline': {
        // options
      },
    },
  },
};
```

### \["asset/inline"].binary

Same as [`module.generator["asset"].binary`](#assetbinary).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/inline': {
        binary: false,
      },
    },
  },
};
```

### \["asset/inline"].dataUrl

Same as [`module.generator["asset"].dataUrl`](#assetdataurl).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/inline': {
        dataUrl: {
          // options
        },
      },
    },
  },
};
```

### \["asset/inline"].dataUrl.encoding

Same as [`module.generator["asset"].dataUrl.encoding`](#assetdataurlencoding).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/inline': {
        dataUrl: {
          encoding: false,
        },
      },
    },
  },
};
```

### \["asset/inline"].dataUrl.mimetype

Same as [`module.generator["asset"].dataUrl.mimetype`](#assetdataurlmimetype).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/inline': {
        dataUrl: {
          mimetype: 'image/png',
        },
      },
    },
  },
};
```

### \["asset/resource"]

Generator options for `asset/resource` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        // options
      },
    },
  },
};
```

### \["asset/resource"].binary

Same as [`module.generator["asset"].binary`](#assetbinary).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        binary: false,
      },
    },
  },
};
```

### \["asset/resource"].importMode

Same as [`module.generator["asset"].importMode`](#assetimportmode).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        importMode: 'preserve',
      },
    },
  },
};
```

### \["asset/resource"].filename

Same as [`module.generator["asset"].filename`](#assetfilename).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        filename: 'static/[hash][ext]',
      },
    },
  },
};
```

### \["asset/resource"].outputPath

Same as [`module.generator["asset"].outputPath`](#assetoutputpath).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        outputPath: 'foo/',
      },
    },
  },
};
```

### \["asset/resource"].publicPath

Same as [`module.generator["asset"].publicPath`](#assetpublicpath).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        publicPath: 'https://cdn.example.com/',
      },
    },
  },
};
```

### \["asset/resource"].emit

Same as [`module.generator["asset"].emit`](#assetemit).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        emit: false,
      },
    },
  },
};
```

### \["css/auto"]

Generator options for `css/auto` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/auto': {
        // options
      },
    },
  },
};
```

### \["css/auto"].exportsConvention

- **Type:** `'as-is' | 'camel-case' | 'camel-case-only' | 'dashes' | 'dashes-only'`
- **Default:** `'as-is'`

Customize how CSS export names are exported to javascript modules, such as keeping them as is, transforming them to camel case, etc.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/auto': {
        exportsConvention: 'camel-case',
      },
    },
  },
};
```

### \["css/auto"].exportsOnly

- **Type:** `boolean`
- **Default:** `true` when the target has no document support, otherwise `false`.

If `true`, **only exports** the identifier mappings from CSS into the output JavaScript files, without embedding any stylesheets in the template. Useful if you are using CSS Modules for pre-rendering (e.g. SSR).

If `false`, generate stylesheets and embed them in the template.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/auto': {
        exportsOnly: false,
      },
    },
  },
};
```

### \["css/auto"].localIdentName

- **Type:** `string`
- **Default:** `[uniqueName]-[id]-[local]` in development mode when [`output.uniqueName`](/config/output.md#outputuniquename) is non-empty, `[id]-[local]` in development mode otherwise, and `[fullhash]` in production mode.

Customize the format of the local class names generated for CSS modules, besides the substitutions at [File-level](/config/filename-placeholders.md#file-placeholders) and [Module-level](/config/filename-placeholders.md#module-placeholders), also include `[uniqueName]` and `[local]`.

Starting from Rspack `2.0.7`, the `[hash]` placeholder in `localIdentName` uses different hash inputs depending on whether the template includes `[local]`. When `localIdentName` does not include `[local]`, the local name is included in the hash input so different local names in the same CSS module generate different values. When `localIdentName` includes `[local]`, the local name is not included in the `[hash]` input because `[local]` already keeps the generated class name unique.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/auto': {
        localIdentName: '[local]-[hash:base64:6]',
      },
    },
  },
};
```

### \["css/auto"].localIdentHashDigest

- **Type:** `string`
- **Default:** `'base64url'`

Configure the digest encoding used for hashes in generated CSS Modules local identifiers. This has the same supported values as [`output.hashDigest`](/config/output.md#outputhashdigest).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/auto': {
        localIdentHashDigest: 'hex',
      },
    },
  },
};
```

### \["css/auto"].localIdentHashDigestLength

- **Type:** `number`
- **Default:** `6`

Configure how many characters from the hash are used in generated CSS Modules local identifiers.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/auto': {
        localIdentHashDigestLength: 8,
      },
    },
  },
};
```

### \["css/auto"].localIdentHashFunction

- **Type:** `string`
- **Default:** [`output.hashFunction`](/config/output.md#outputhashfunction), which defaults to `'xxhash64'`

Configure the hash function used for generated CSS Modules local identifiers. This has the same supported values as [`output.hashFunction`](/config/output.md#outputhashfunction).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/auto': {
        localIdentHashFunction: 'xxhash64',
      },
    },
  },
};
```

### \["css/auto"].localIdentHashSalt

- **Type:** `string`
- **Default:** [`output.hashSalt`](/config/output.md#outputhashsalt), which defaults to `undefined`

Configure a salt added to the hash used for generated CSS Modules local identifiers. When unset, Rspack uses [`output.hashSalt`](/config/output.md#outputhashsalt).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/auto': {
        localIdentHashSalt: 'my-salt',
      },
    },
  },
};
```

### \["css/auto"].esModule

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

This configuration is available for improved ESM-CJS interoperability purposes.

Whether to add `__esModule` to the exports of CSS; if added, it will be treated as ES modules during ESM-CJS interop, otherwise, it will be treated as a CommonJS Module.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/auto': {
        esModule: true,
      },
    },
  },
};
```

For example, a common use case, when using the CommonJS output from a third-party component library, it is sometimes necessary to add this configuration to ensure correct ESM-CJS interop, to obtain the correct exports (this can be used in conjunction with [rules\[\].test](/config/module-rules.md#rulestest) and other matching conditions to add it only for that particular component library).

The original source code of the third-party component library:

```js
import style from './style.css';

export function Button() {
  return <button className={style.btn}></button>;
}
```

The CommonJS format output published by the third-party component library:

```js
'use strict';

Object.defineProperty(exports, '__esModule', {
  value: true,
});
exports.Button = Button;
var _style = _interopRequireDefault(require('./style.css'));
var _jsxRuntime = require('react/jsx-runtime');
function _interopRequireDefault(obj) {
  return obj && obj.__esModule ? obj : { default: obj };
}
function Button() {
  return /*#__PURE__*/ (0, _jsxRuntime.jsx)('button', {
    className: _style['default'].btn, // <-- Note: After passing through _interopRequireDefault, this need to access default here.
  });
}
```

### css

Generator options for `css` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      css: {
        // options
      },
    },
  },
};
```

### css.exportsOnly

Same as [`module.generator["css/auto"].exportsOnly`](#cssautoexportsonly).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      css: {
        exportsOnly: false,
      },
    },
  },
};
```

### css.esModule

Same as [`module.generator["css/auto"].esModule`](#cssautoesmodule).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      css: {
        esModule: true,
      },
    },
  },
};
```

### \["css/global"]

Generator options for `css/global` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/global': {
        // options
      },
    },
  },
};
```

### \["css/global"].exportsConvention

Same as [`module.generator["css/auto"].exportsConvention`](#cssautoexportsconvention).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/global': {
        exportsConvention: 'camel-case',
      },
    },
  },
};
```

### \["css/global"].exportsOnly

Same as [`module.generator["css/auto"].exportsOnly`](#cssautoexportsonly).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/global': {
        exportsOnly: false,
      },
    },
  },
};
```

### \["css/global"].localIdentName

Same as [`module.generator["css/auto"].localIdentName`](#cssautolocalidentname).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/global': {
        localIdentName: '[local]-[hash:base64:6]',
      },
    },
  },
};
```

### \["css/global"].localIdentHashDigest

Same as [`module.generator["css/auto"].localIdentHashDigest`](#cssautolocalidenthashdigest).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/global': {
        localIdentHashDigest: 'hex',
      },
    },
  },
};
```

### \["css/global"].localIdentHashDigestLength

Same as [`module.generator["css/auto"].localIdentHashDigestLength`](#cssautolocalidenthashdigestlength).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/global': {
        localIdentHashDigestLength: 8,
      },
    },
  },
};
```

### \["css/global"].localIdentHashFunction

Same as [`module.generator["css/auto"].localIdentHashFunction`](#cssautolocalidenthashfunction).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/global': {
        localIdentHashFunction: 'xxhash64',
      },
    },
  },
};
```

### \["css/global"].localIdentHashSalt

Same as [`module.generator["css/auto"].localIdentHashSalt`](#cssautolocalidenthashsalt).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/global': {
        localIdentHashSalt: 'my-salt',
      },
    },
  },
};
```

### \["css/global"].esModule

Same as [`module.generator["css/auto"].esModule`](#cssautoesmodule).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/global': {
        esModule: true,
      },
    },
  },
};
```

### \["css/module"]

Generator options for `css/module` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/module': {
        // options
      },
    },
  },
};
```

### \["css/module"].exportsConvention

Same as [`module.generator["css/auto"].exportsConvention`](#cssautoexportsconvention).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/module': {
        exportsConvention: 'camel-case',
      },
    },
  },
};
```

### \["css/module"].exportsOnly

Same as [`module.generator["css/auto"].exportsOnly`](#cssautoexportsonly).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/module': {
        exportsOnly: false,
      },
    },
  },
};
```

### \["css/module"].localIdentName

Same as [`module.generator["css/auto"].localIdentName`](#cssautolocalidentname).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/module': {
        localIdentName: '[local]-[hash:base64:6]',
      },
    },
  },
};
```

### \["css/module"].localIdentHashDigest

Same as [`module.generator["css/auto"].localIdentHashDigest`](#cssautolocalidenthashdigest).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/module': {
        localIdentHashDigest: 'hex',
      },
    },
  },
};
```

### \["css/module"].localIdentHashDigestLength

Same as [`module.generator["css/auto"].localIdentHashDigestLength`](#cssautolocalidenthashdigestlength).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/module': {
        localIdentHashDigestLength: 8,
      },
    },
  },
};
```

### \["css/module"].localIdentHashFunction

Same as [`module.generator["css/auto"].localIdentHashFunction`](#cssautolocalidenthashfunction).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/module': {
        localIdentHashFunction: 'xxhash64',
      },
    },
  },
};
```

### \["css/module"].localIdentHashSalt

Same as [`module.generator["css/auto"].localIdentHashSalt`](#cssautolocalidenthashsalt).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/module': {
        localIdentHashSalt: 'my-salt',
      },
    },
  },
};
```

### \["css/module"].esModule

Same as [`module.generator["css/auto"].esModule`](#cssautoesmodule).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/module': {
        esModule: true,
      },
    },
  },
};
```

### json.JSONParse

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

Use `JSON.parse` when the JSON string is longer than 20 characters.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      json: {
        JSONParse: false,
      },
    },
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/module/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/module-parser.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Module parser

`module.parser` controls how Rspack reads modules after they are resolved. It affects how dependencies are collected, how syntax such as `import.meta` and dynamic `import()` is interpreted, and other parsing behavior for each module type.

## parser

- **Type:** `Object`
- **Default:** `{}`

Use `module.parser` to define parser options for each module type.

Available parser option groups:

- `asset`: [Asset parser options](#asset)
- `javascript`, `javascript/auto`, `javascript/dynamic`, `javascript/esm`: [JavaScript parser options](#javascript)
- `json`: [JSON parser options](#json)
- `css`, `css/auto`, `css/global`, `css/module`: [CSS parser options](#cssauto)

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      // Parser options for asset modules
      asset: {
        dataUrlCondition: {
          maxSize: 16192,
        },
      },
      // Parser options for javascript modules
      javascript: {
        dynamicImportMode: 'lazy',
        dynamicImportPrefetch: false,
        dynamicImportPreload: false,
        url: true,
        importMeta: true,
      },
      // Parser options for CSS modules
      css: {
        namedExports: true,
      },
      // Parser options for css/auto modules
      'css/auto': {
        namedExports: true,
      },
      // Parser options for css/module modules
      'css/module': {
        namedExports: true,
      },
    },
  },
};
```

### asset

Parser options for `asset` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      asset: {
        // options
      },
    },
  },
};
```

### asset.dataUrlCondition

- **Type:** `{ maxSize: number }`
- **Default:** `{ maxSize: 8096 }`

If the module size is less than or equal to `maxSize`, then the module will be Base64 encoded, otherwise a file will be created. This option can be used only for [Asset modules](/guide/features/asset-module.md).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      asset: {
        dataUrlCondition: {
          // Modules' size smaller than or equal to 4KB will be Base64 encoded.
          maxSize: 4 * 1024,
        },
      },
    },
  },
};
```

### javascript

Parser options for `javascript` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        // options
      },
    },
  },
};
```

### javascript.commonjsMagicComments


- Type: `boolean`
- Default:`false`



[Added in v1.5.6](https://github.com/web-infra-dev/rspack/releases/tag/v1.5.6)

Enable [Magic comments](/api/runtime-api/module-methods.md#magic-comments) support for CommonJS.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        commonjsMagicComments: true,
      },
    },
  },
};
```

Note that only the `rspackIgnore` and `webpackIgnore` comments are supported at the moment.

:::tip
Since Rspack 2.1.0, prefer `rspackIgnore`. `webpackIgnore` remains supported for compatibility.
:::

```js
const x = require(/* rspackIgnore: true */ 'x');
const y = require(/* webpackIgnore: true */ 'y');
```

### javascript.dynamicImportMode


- Type: `'lazy' | 'eager' | 'weak' | 'lazy-once'`
- Default:`'lazy'`


Specifies global mode for dynamic import, see [`rspackMode`](/api/runtime-api/module-methods.md#rspackmode) for more details.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        dynamicImportMode: 'eager',
      },
    },
  },
};
```

### javascript.dynamicImportPrefetch


- Type: `boolean | number`
- Default:`false`


Specifies global prefetch for dynamic import, see [`rspackPrefetch`](/api/runtime-api/module-methods.md#rspackprefetch) for more details.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        dynamicImportPrefetch: true,
      },
    },
  },
};
```

### javascript.dynamicImportPreload


- Type: `boolean | number`
- Default:`false`


Specifies global preload for dynamic import, see [`rspackPreload`](/api/runtime-api/module-methods.md#rspackpreload) for more details.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        dynamicImportPreload: true,
      },
    },
  },
};
```

### javascript.dynamicImportFetchPriority


- Type: `'low' | 'high' | 'auto'`
- Default:`'auto'`


Specifies global `fetchPriority` for dynamic import, see [`rspackFetchPriority`](/api/runtime-api/module-methods.md#rspackfetchpriority) for more details.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        dynamicImportFetchPriority: 'high',
      },
    },
  },
};
```

### javascript.url


- Type: `true | false | 'relative' | 'new-url-relative'`
- Default:`true`


Enable parsing of `new URL()` syntax.

- `true`: Generate absolute URLs that include the root URL (default behavior).
- `'relative'`: Generate relative URLs without the root URL.
- `'new-url-relative'`: Generate static relative URLs that are replaced at compile-time with the correct public path.

When using `'new-url-relative'`, Rspack generates relative URLs that will be replaced at compile-time with the correct public path:

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        url: 'new-url-relative',
      },
    },
  },
};
```

```js
new URL('./icon.svg', import.meta.url);

// would become 👇
new URL('./icon[hash].svg', import.meta.url);
```

When using `'relative'`, Rspack generates runtime code to calculate relative URLs for `new URL()` syntax, i.e., there's no base URL included in the result URL:

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        url: 'relative',
      },
    },
  },
};
```

```html
<!-- with 'relative' -->
<img src="icon.svg" />

<!-- without 'relative' -->
<img src="file:///path/to/project/dist/icon.svg" />
```

### javascript.exprContextCritical


- Type: `boolean | undefined`
- Default:`true`


Enable warnings for full dynamic dependencies (`import(variable)`).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        exprContextCritical: false,
      },
    },
  },
};
```

### javascript.wrappedContextCritical


- Type: `boolean | undefined`
- Default:`false`


Enable warnings for partial dynamic dependencies (`import("./path/to/" + variable)`).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        wrappedContextCritical: false,
      },
    },
  },
};
```

### javascript.unknownContextCritical


- Type: `boolean | undefined`
- Default:`true`


Enable warnings when using the `require` function in a non-statically-analyzable way (`require(variable)`).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        unknownContextCritical: false,
      },
    },
  },
};
```

### javascript.wrappedContextRegExp


- Type: `RegExp | undefined`
- Default:`/.*/`


Set a regular expression to match wrapped dynamic dependencies.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        wrappedContextRegExp: /\.js$/,
      },
    },
  },
};
```

### javascript.importMeta

- **Type:** `boolean | 'preserve-unknown' | ImportMetaParserOptions`
- **Default:** When using [ESM output](/guide/features/esm.md), the default value is `'preserve-unknown'`; otherwise, it is `true`

Control whether Rspack parses and replaces `import.meta` in source code. Available values:

- `"preserve-unknown"`: [Known `import.meta` properties](/api/runtime-api/module-variables.md#import-meta) are statically analyzed at compile-time, other properties are preserved and evaluated at runtime.
- `true`: All `import.meta` properties are statically analyzed at compile-time.
- `false`: All `import.meta` properties are evaluated at runtime.
- `ImportMetaParserOptions`: Configure each known `import.meta` property independently. Properties set to `false` are preserved for runtime evaluation, while omitted properties keep the default enabled behavior. Unknown `import.meta` properties are preserved.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        importMeta: false,
      },
    },
  },
};
```

The object form supports the following keys:

- Webpack-compatible keys: `dirname`, `filename`, `main`, `url`, `webpack`, and `webpackContext`.
- Rspack-specific keys: `glob`, `resolve`, `rspackBaseUri`, `rspackHash`, `rspackInitSharing`, `rspackNonce`, `rspackPublicPath`, `rspackRsc`, `rspackShareScopes`, `rspackUniqueId`, and `rspackVersion`.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        importMeta: {
          url: false,
          webpack: true,
          webpackContext: true,
          rspackHash: false,
        },
      },
    },
  },
};
```

`resolve` only controls whether an already enabled [`import.meta.resolve()`](#javascriptimportmetaresolve) expression is handled at compile time. To use `import.meta.resolve()`, you still need to enable `javascript.importMetaResolve`.

### javascript.exportsPresence


- Type: `'error' | 'warn' | 'auto' | false`
- Default:`'error'`


Warn or error for using non-existent exports and conflicting re-exports.

- `"error"`: Report errors.
- `"warn"`: Report warnings.
- `"auto"`: Depending on whether the module is a strict ESM, give an error if it is, otherwise give a warning.
- `false`: Disable this feature.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        exportsPresence: 'auto',
      },
    },
  },
};
```

### javascript.importExportsPresence


- Type: `'error' | 'warn' | 'auto' | false`


Warn or error for using non-existent exports, defaulting to the configuration of [module.parser.javascript.exportsPresence](#javascriptexportspresence).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        importExportsPresence: 'error',
      },
    },
  },
};
```

### javascript.reexportExportsPresence


- Type: `'error' | 'warn' | 'auto' | false`


Warn or error for conflicting re-exports, defaulting to the configuration of [module.parser.javascript.exportsPresence](#javascriptexportspresence).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        reexportExportsPresence: 'error',
      },
    },
  },
};
```

### javascript.typeReexportsPresence


[Added in v1.4.1](https://github.com/web-infra-dev/rspack/releases/tag/v1.4.1)

- **Type:** `'no-tolerant' | 'tolerant' | 'tolerant-no-check'`
- **Default:** `'no-tolerant'`

Controls error tolerance for type re-exports, commonly seen in these two scenarios:

```ts
// case 1:
export { TypeA } from './types';
// case 2:
import { TypeB } from './types';
export { TypeB };
```

When re-exporting types, since `TypeA` and `TypeB` are types but used in value namespace (`export {}`), Rspack will report warnings:

```txt
WARNING in ./re-exports.ts
  ⚠ ESModulesLinkingWarning: export 'TypeA' (reexported as 'TypeA') was not found in './types' (module has no exports)
   ╭─[2:0]
 1 │ // case 1:
 2 │ export { TypeA } from "./types";
   · ────────────────────────────────

WARNING in ./re-exports.ts
  ⚠ ESModulesLinkingWarning: export 'TypeB' (reexported as 'TypeB') was not found in './types' (module has no exports)
   ╭─[5:0]
 3 │ // case 2:
 4 │ import { TypeB } from "./types";
 5 │ export { TypeB };
   · ─────────────────
```

:::info Recommended with isolatedModules
When using Rspack to bundle TypeScript, we strongly recommend enabling [isolatedModules](https://www.typescriptlang.org/tsconfig/#isolatedModules) in tsconfig.json (also recommended with other bundlers as it matches how bundlers compile TypeScript: [.ts files are independent and compiled separately](/guide/languages/typescript.md#enable-isolatedmodules)). This will give TypeScript's own warning for type re-exports: `Re-exporting a type when 'isolatedModules' is enabled requires using 'export type'.`
:::

- `'no-tolerant'`: Default behavior, shows errors for type re-exports.
- `'tolerant'`: Tolerates type re-exports while verifying the existence of corresponding type exports in child modules. Requires coordination with [`collectTypeScriptInfo.typeExports`](/guide/features/builtin-swc-loader.md#collecttypescriptinfotypeexports) from builtin:swc-loader to collect type export information.
- `'tolerant-no-check'`: Tolerates type re-exports without checking child modules (may incorrectly tolerate some invalid cases, though IDEs usually provide warnings). Better performance as it skeps child module checks.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        typeReexportsPresence: 'tolerant',
      },
    },
    rules: [
      {
        test: /\.(?:js|mjs|ts)$/,
        use: [
          {
            loader: 'builtin:swc-loader',
            options: {
              detectSyntax: 'auto',
              collectTypeScriptInfo: {
                typeExports: true, // Must be enabled in "tolerant" mode
              },
            },
          },
        ],
      },
    ],
  },
};
```

Please refer to [type reexports presence example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/type-reexports-presence) for more details.

### javascript.worker


- Type: `string[] | boolean | { alias?: string[], url?: 'new-url-relative' }`


Provide custom syntax for Worker parsing, commonly used to support Worklet:

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        worker: [
          // Supports CSS paintWorklet
          'CSS.paintWorklet.addModule()',
          // Supports AudioWorklet, with the leading '*' indicating the recognition of a variable named 'context', for example:
          // let context = new AudioContext();
          // await context.audioWorklet.addModule(new URL("noise-processor.js", import.meta.url));
          '*context.audioWorklet.addModule()',
          // Extends default syntax: ["Worker", "SharedWorker", "navigator.serviceWorker.register()", "Worker from worker_threads"]
          '...',
        ],
      },
    },
  },
};
```

The `string[]` form is equivalent to setting the same values on `worker.alias`.
When `worker.url` is unset, Rspack keeps the existing Worker URL output. When
`worker.url` is set to `'new-url-relative'` and `output.module` is enabled,
Rspack emits a static `new URL()` expression for
`new Worker(new URL(..., import.meta.url))`. For non-ESM output, Rspack keeps
the existing runtime Worker URL output:

```js title="rspack.config.mjs"
export default {
  output: {
    module: true,
    chunkFilename: '[name].bundle.js',
  },
  module: {
    parser: {
      javascript: {
        worker: {
          url: 'new-url-relative',
        },
      },
    },
  },
};
```

```js
new Worker(new URL('./worker.js', import.meta.url));

// would become 👇
new Worker(new URL('./worker.bundle.js', import.meta.url));
```

> See [Web Workers](/guide/features/web-workers.md) for more details.

### javascript.overrideStrict


- Type: `'strict' | 'non-strict'`


Override the module to strict or non-strict.

This may affect the behavior of the module (some behaviors differ between strict and non-strict), so please configure this option carefully.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        overrideStrict: 'strict',
      },
    },
  },
};
```

### javascript.commonjs


- Type: `boolean | { exports?: boolean | 'skipInEsm' }`
- Default:`true`


Controls CommonJS-specific parser behaviour. The default `true` keeps Rspack's standard handling for CommonJS export mutations. Set `{ exports: 'skipInEsm' }` to skip rewriting CommonJS export assignments when the module is evaluated as ESM, preserving the original runtime side effects. Provide `false` to disable CommonJS export handling entirely.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        commonjs: {
          exports: 'skipInEsm',
        },
      },
    },
  },
};
```

### javascript.createRequire


- Type: `boolean | string`
- Default:`false`


Control whether Rspack parses `createRequire()` from Node.js `module` and turns the created `require` function into a statically analyzable dependency context.

When set to `true`, it is equivalent to `"createRequire from module"`. Rspack recognizes imports from both `module` and `node:module` for this default form.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        createRequire: true,
      },
    },
  },
};
```

```js title="index.js"
import { createRequire as r } from 'module';

const require = r(import.meta.url);
const value = require('./value.cjs');
```

Rspack also supports namespace and default imports:

```js title="index.js"
import moduleDefault from 'module';
import * as moduleNs from 'node:module';

moduleDefault.createRequire(import.meta.url)('./value.cjs');
moduleNs.createRequire(import.meta.url)('./value.cjs');
```

The `createRequire()` argument must be statically analyzable as a file URL or an absolute path, such as `import.meta.url`, `new URL('./dir/file.js', import.meta.url)`, or an absolute `file:` URL. When `import.meta.url` is used as the argument, Rspack treats it as the current module URL for the `createRequire` context.

You can use a string value in the form `"<specifier> from <module>"` to customize the imported specifier and module source:

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        createRequire: 'createRequire from module',
      },
    },
  },
};
```

### javascript.requireAlias


- Type: `boolean`
- Default:`false`


Control whether renaming of the CommonJS `require` function will be parsed and transformed.

When set to `true`, Rspack will parse and transform cases where `require` is assigned to a variable or passed as a parameter (e.g., `const req = require; req('./module')`).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        requireAlias: true,
      },
    },
  },
};
```

### javascript.requireAsExpression


- Type: `boolean`
- Default:`true`


Control whether `require` used as an expression will be parsed.

When set to `true`, Rspack will parse `require` when it's used as an expression (e.g., `const req = require; req('./module')`) and emit a warning. When set to `false`, this pattern will be ignored.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        requireAsExpression: false,
      },
    },
  },
};
```

### javascript.requireDynamic


- Type: `boolean`
- Default:`true`


Control whether dynamic `require` calls will be parsed.

When set to `false`, Rspack will not parse dynamic `require` calls where the module path is not a static string (e.g., `require(variable)`). This can improve build performance if your code doesn't use dynamic requires.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        requireDynamic: false,
      },
    },
  },
};
```

### javascript.requireResolve


- Type: `boolean`
- Default:`true`


Control whether `require.resolve()` calls will be parsed.

When set to `false`, Rspack will not parse `require.resolve()` calls. This can improve build performance if your code doesn't use `require.resolve()`.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        requireResolve: false,
      },
    },
  },
};
```

### javascript.importDynamic


- Type: `boolean`
- Default:`true`


Control whether dynamic `import()` calls will be parsed.

When set to `false`, Rspack will not parse dynamic `import()` calls where the module path is not a static string (e.g., `import(variable)`). This can improve build performance if your code doesn't use dynamic imports.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        importDynamic: false,
      },
    },
  },
};
```

### javascript.strictThisContextOnImports


- Type: `boolean`
- Default:`false`


Controls whether Rspack preserves the `this` binding strictly when calling exported functions as object members from imported modules.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        strictThisContextOnImports: false,
      },
    },
  },
};
```

This mainly affects cases where an exported function uses `this` to refer to the current module object, for example:

```js title="index.js"
import * as mod from './mod';

console.log(mod.fn());
```

```js title="mod.js"
export function fn() {
  return this.value;
}

export const value = 42;
```

In the example above, enabling this option prints `42`. When it is disabled, `value` is considered unused and removed for better tree shaking, so the result becomes `undefined`.

- When set to `true`, Rspack follows the spec more strictly and prioritizes correct runtime `this` semantics, but tree shaking can become less effective.
- When set to `false`, Rspack can generate more optimized output, but runtime `this` semantics may no longer be preserved in these patterns.

This pattern is uncommon in real-world ESM code, and enabling the option can reduce tree shaking effectiveness, so the default is `false`.

:::tip
If you run into this pattern in practice, it is usually better to avoid relying on it. If that is not possible, prefer enabling it only for specific modules with [module rule condition](/config/module-rules.md#condition).

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /index\.js$/, // Only enable strictThisContextOnImports for import statements in the index.js module
        parser: {
          strictThisContextOnImports: true,
        },
      },
    ],
  },
};
```

:::

### javascript.jsx


[Added in v1.5.7](https://github.com/web-infra-dev/rspack/releases/tag/v1.5.7)

Stability: Experimental


- Type: `boolean`
- Default:`false`


Allow the JavaScript parser to understand JSX syntax so that parsing and minimization can operate on files that keep JSX in the final bundle.

Enable this option when you set the loader's JSX mode to "preserve" and want to defer the actual JSX transform to a later tool (for example, libraries that ship JSX output or rely on a custom JSX runtime).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        jsx: true,
      },
    },
  },
};
```

:::warning
This option is experimental in Rspack and may change or be removed.
:::

### javascript.importMetaResolve


[Added in v2.0.0](https://github.com/web-infra-dev/rspack/releases/tag/v2.0.0)

Stability: Experimental


- Type: `boolean`
- Default:`false`


Allow the JavaScript parser to understand `import.meta.resolve()` syntax.

Currently, `import.meta.resolve("./module")` behaves similarly to [`require.resolve("./module")`](/api/runtime-api/module-methods.md#requireresolve): it includes the module in the final bundle and returns the module ID.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        importMetaResolve: true,
      },
    },
  },
};
```

:::warning
This option is experimental in Rspack and may change or be removed.
:::

### javascript.pureFunctions


Stability: Experimental


- Type: `string[]`


Manually mark top-level identifiers in matched modules as side-effect-free for pure-function-based tree shaking. Each name must resolve to a supported top-level name in the module — a function/class/variable declaration, an `import` specifier, an exported alias such as `export { foo as bar }`, or `default` for a default-exported function or arrow.

This option is mainly intended for third-party libraries whose source cannot be annotated directly. You can either configure it on the library file itself, or on a consumer file to assert that calls to a particular import are pure.

Although the option lives under `module.parser.javascript`, in practice it is usually better to apply it through `module.rules[i].parser` so you can configure `pureFunctions` more precisely for specific modules.

```js title="rspack.config.mjs"
export default {
  experiments: {
    pureFunctions: true,
  },
  module: {
    rules: [
      // Mark exports of a third-party library as pure.
      {
        test: /node_modules\/some-library\/index\.js$/,
        parser: {
          pureFunctions: ['isString'],
        },
      },
      // Or mark imports on the consumer side: calls to `cva` in this file
      // are treated as pure regardless of how the library declares itself.
      {
        test: /src\/styles\.js$/,
        parser: {
          pureFunctions: ['cva'],
        },
      },
    ],
  },
};
```

:::warning
This option only takes effect when `experiments.pureFunctions` is enabled, which is the default in production mode. Rspack emits a warning if a configured name does not appear as a top-level binding in the matched module.
:::

### \["javascript/auto"]

Parser options for `javascript/auto` modules, same as the [`javascript` parser options](#javascript).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'javascript/auto': {
        // options
      },
    },
  },
};
```

### \["javascript/dynamic"]

Parser options for `javascript/dynamic` modules, same as the [`javascript` parser options](#javascript).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'javascript/dynamic': {
        // options
      },
    },
  },
};
```

### \["javascript/esm"]

Parser options for `javascript/esm` modules, same as the [`javascript` parser options](#javascript).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'javascript/esm': {
        // options
      },
    },
  },
};
```

### json

Parser options for `json` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      json: {
        // options
      },
    },
  },
};
```

### json.exportsDepth

- **Type:** `number`
- **Default:** production mode is `Number.MAX_SAFE_INTEGER`, development mode is `1`

The depth of json dependency flagged as `exportInfo`.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      json: {
        // For example, for the following json
        // {
        //   "depth_1": {
        //     "depth_2": {
        //       "depth_3": "foo"
        //     }
        //   },
        //   "_depth_1": "bar"
        // }
        // when `exportsDepth: 1`, `depth_2` and `depth_3` will not be flagged as `exportInfo`.
        exportsDepth: 1,
      },
    },
  },
};
```

### json.parse

- **Type:** `(source: string) => any`
- **Default:** `undefined`

Customize how Rspack parses the source of `json` modules. The function receives the module source as a string. It is called synchronously and must return JSON-serializable data, such as an object, array, string, number, boolean, or `null`.

Rspack serializes the returned value with `JSON.stringify` and then parses that serialized JSON as the module data, so values that cannot be represented as valid JSON should not be returned. For normal JSON files you do not need to configure this option; it is mainly useful when modules are treated as `type: 'json'` but need custom source-to-data conversion.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      json: {
        parse: (source) => {
          return JSON.parse(source);
        },
      },
    },
  },
};
```

You can also use this option through `module.rules[].parser` when the matched rule sets `type: 'json'`. For example, parse `.json5` files as JSON modules:

```js title="rspack.config.mjs"
import JSON5 from 'json5';

export default {
  module: {
    rules: [
      {
        test: /\.json5$/,
        type: 'json',
        parser: {
          parse: JSON5.parse,
        },
      },
    ],
  },
};
```

### \["css/auto"]

Parser options for `css/auto` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        // options
      },
    },
  },
};
```

### \["css/auto"].exportType

- **Type:** `'link' | 'text' | 'css-style-sheet' | 'style'`
- **Default:** `'link'`

Configure how CSS content is exported to JavaScript.

By default, `exportType` is `'link'`, which emits CSS as stylesheet output and loads it with the built-in CSS loading runtime.

- `'link'`: emit the CSS as stylesheet output and keep CSS module exports available.
- `'text'`: export the generated CSS text as the default export.
- `'css-style-sheet'`: export a `CSSStyleSheet` instance as the default export.
- `'style'`: inject the generated CSS into the document through `<style>` tags at runtime.

When using `exportType: 'text'` or `exportType: 'css-style-sheet'`, the generated CSS becomes part of the JavaScript module and no separate CSS asset is emitted for that module.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        exportType: 'text',
      },
    },
  },
};
```

### \["css/auto"].namedExports

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

Use ES modules named export for CSS exports.

When using `namedExports: true`, you can use namespace export or named export:

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        namedExports: true,
      },
    },
  },
};
```

```js
// namespace export
import * as classes from './index.module.css';
// named export
import { class1, class2 } from './index.module.css';
```

When using `namedExports: false`, in addition to namespace export and named export, default export can also be used:

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        namedExports: false,
      },
    },
  },
};
```

```js
// namespace export
import * as classes from './index.module.css';
// named export
import { class1, class2 } from './index.module.css';
// default export
import classes from './index.module.css';
// default export and named export
import classes, { class1, class2 } from './index.module.css';
```

### \["css/auto"].url

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

Allow to enable/disables handling the CSS functions url.

When using `url: true`, Rspack will resolve the path in `url` function, the resolve file will be treated as an asset.
When using `url: false`, Rspack will ignore the path in the `url` function, keep the content unchanged.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      css: {
        url: true,
      },
    },
  },
};
```

### \["css/auto"].resolveImport


[Added in v1.7.2](https://github.com/web-infra-dev/rspack/releases/tag/v1.7.2)

- **Type:** `boolean | ((context: { url: string, media: string | undefined, resourcePath: string, supports: string | undefined, layer: string | undefined }) => boolean)`
- **Default:** `true`

Whether to resolve `@import` syntax.

- `true`: enable processing of `@import` rules (default).
- `false`: disable processing of `@import` rules.
- `function`: only process `@import` rules that satisfy the condition.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        resolveImport: ({ url }) => {
          return url.includes('style.css');
        },
      },
    },
  },
};
```

### \["css/auto"].import

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

Whether to handle CSS `@import` at-rules.

- `true`: resolve and process `@import` rules (default).
- `false`: leave `@import` rules unchanged in the generated CSS.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        import: true,
      },
    },
  },
};
```

### \["css/auto"].animation

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

Enable or disable renaming local `@keyframes` identifiers and their `animation` or `animation-name` usages.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        animation: true,
      },
    },
  },
};
```

### \["css/auto"].customIdents

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

Enable or disable renaming custom identifiers, such as local `@counter-style` and `@font-palette-values` names.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        customIdents: true,
      },
    },
  },
};
```

### \["css/auto"].container

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

Enable or disable renaming local CSS container names and their usages, such as `container-name`, `container`, and `@container`.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        container: true,
      },
    },
  },
};
```

### \["css/auto"].dashedIdents

- **Type:** `boolean`
- **Default:** `false`

Enable or disable renaming dashed identifiers, such as CSS custom properties and `@property` declarations.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        dashedIdents: true,
      },
    },
  },
};
```

### \["css/auto"].function

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

Enable or disable renaming local CSS function names and their usages, such as `@function --fn` and `--fn()`.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        function: true,
      },
    },
  },
};
```

### \["css/auto"].grid

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

Enable or disable renaming local CSS grid line and area names and their usages, such as `grid-template-areas`, `grid-area`, and `grid-row`.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        grid: true,
      },
    },
  },
};
```

### \["css/auto"].pure

- **Type:** `boolean`
- **Default:** `false`

Enable strict pure mode for CSS Modules. When enabled, every selector in a CSS Module must contain at least one local class or id selector.

For `css/auto`, this check only applies to files that are treated as CSS Modules.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        pure: true,
      },
    },
  },
};
```

### css

Parser options for `css` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      css: {
        // options
      },
    },
  },
};
```

### css.exportType

Same as [`module.parser["css/auto"].exportType`](#cssautoexporttype).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      css: {
        exportType: 'text',
      },
    },
  },
};
```

### css.namedExports

Same as [`module.parser["css/auto"].namedExports`](#cssautonamedexports).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      css: {
        namedExports: true,
      },
    },
  },
};
```

### css.url

Same as [`module.parser["css/auto"].url`](#cssautourl).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      css: {
        url: true,
      },
    },
  },
};
```

### css.resolveImport

Same as [`module.parser["css/auto"].resolveImport`](#cssautoresolveimport).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      css: {
        resolveImport: ({ url }) => {
          return url.includes('style.css');
        },
      },
    },
  },
};
```

### css.import

Same as [`module.parser["css/auto"].import`](#cssautoimport).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      css: {
        import: true,
      },
    },
  },
};
```

### \["css/global"]

Parser options for `css/global` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/global': {
        // options
      },
    },
  },
};
```

### \["css/global"].exportType

Same as [`module.parser["css/auto"].exportType`](#cssautoexporttype).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/global': {
        exportType: 'style',
      },
    },
  },
};
```

### \["css/global"].namedExports

Same as [`module.parser["css/auto"].namedExports`](#cssautonamedexports).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/global': {
        namedExports: true,
      },
    },
  },
};
```

### \["css/global"].url

Same as [`module.parser["css/auto"].url`](#cssautourl).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/global': {
        url: true,
      },
    },
  },
};
```

### \["css/global"].resolveImport

Same as [`module.parser["css/auto"].resolveImport`](#cssautoresolveimport).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/global': {
        resolveImport: ({ url }) => {
          return url.includes('style.css');
        },
      },
    },
  },
};
```

### \["css/global"].import

Same as [`module.parser["css/auto"].import`](#cssautoimport).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/global': {
        import: true,
      },
    },
  },
};
```

### \["css/global"].animation

Same as [`module.parser["css/auto"].animation`](#cssautoanimation).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/global': {
        animation: true,
      },
    },
  },
};
```

### \["css/global"].container

Same as [`module.parser["css/auto"].container`](#cssautocontainer).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/global': {
        container: true,
      },
    },
  },
};
```

### \["css/global"].customIdents

Same as [`module.parser["css/auto"].customIdents`](#cssautocustomidents).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/global': {
        customIdents: true,
      },
    },
  },
};
```

### \["css/global"].dashedIdents

Same as [`module.parser["css/auto"].dashedIdents`](#cssautodashedidents).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/global': {
        dashedIdents: true,
      },
    },
  },
};
```

### \["css/global"].function

Same as [`module.parser["css/auto"].function`](#cssautofunction).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/global': {
        function: true,
      },
    },
  },
};
```

### \["css/global"].grid

Same as [`module.parser["css/auto"].grid`](#cssautogrid).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/global': {
        grid: true,
      },
    },
  },
};
```

### \["css/module"]

Parser options for `css/module` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/module': {
        // options
      },
    },
  },
};
```

### \["css/module"].exportType

Same as [`module.parser["css/auto"].exportType`](#cssautoexporttype).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/module': {
        exportType: 'css-style-sheet',
      },
    },
  },
};
```

### \["css/module"].namedExports

Same as [`module.parser["css/auto"].namedExports`](#cssautonamedexports).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/module': {
        namedExports: true,
      },
    },
  },
};
```

### \["css/module"].url

Same as [`module.parser["css/auto"].url`](#cssautourl).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/module': {
        url: true,
      },
    },
  },
};
```

### \["css/module"].resolveImport

Same as [`module.parser["css/auto"].resolveImport`](#cssautoresolveimport).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/module': {
        resolveImport: ({ url }) => {
          return url.includes('style.css');
        },
      },
    },
  },
};
```

### \["css/module"].import

Same as [`module.parser["css/auto"].import`](#cssautoimport).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/module': {
        import: true,
      },
    },
  },
};
```

### \["css/module"].animation

Same as [`module.parser["css/auto"].animation`](#cssautoanimation).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/module': {
        animation: true,
      },
    },
  },
};
```

### \["css/module"].container

Same as [`module.parser["css/auto"].container`](#cssautocontainer).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/module': {
        container: true,
      },
    },
  },
};
```

### \["css/module"].customIdents

Same as [`module.parser["css/auto"].customIdents`](#cssautocustomidents).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/module': {
        customIdents: true,
      },
    },
  },
};
```

### \["css/module"].dashedIdents

Same as [`module.parser["css/auto"].dashedIdents`](#cssautodashedidents).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/module': {
        dashedIdents: true,
      },
    },
  },
};
```

### \["css/module"].function

Same as [`module.parser["css/auto"].function`](#cssautofunction).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/module': {
        function: true,
      },
    },
  },
};
```

### \["css/module"].grid

Same as [`module.parser["css/auto"].grid`](#cssautogrid).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/module': {
        grid: true,
      },
    },
  },
};
```

### \["css/module"].pure

Same as [`module.parser["css/auto"].pure`](#cssautopure).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/module': {
        pure: true,
      },
    },
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/module/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/module-rules.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Module rules

- **Type:** `(Rule | Falsy)[]`
- **Default:** `[]`

`module.rules` defines how Rspack processes different types of modules during the build.

It is an array of rules. Each rule is matched against a module's metadata when the module is resolved and created, such as its file path, file type, or query parameters. Once a rule matches, Rspack transforms or resolves the module according to the rule's configuration.

The most common use case is configuring [loaders](/guide/features/loader.md) for different kinds of modules. For example, transforming TypeScript into browser-executable JavaScript, or handling stylesheets, images, and other assets.

By combining various matching conditions with specific processing logic, `module.rules` provides fine-grained control over how different modules are built.

For example, use the [built-in swc-loader](/guide/features/builtin-swc-loader.md) to handle files ending with `.ts`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|ts)$/,
        use: 'builtin:swc-loader',
        options: {
          // loader options...
        },
      },
    ],
  },
};
```

## Concepts

### Rule

- **Type:** `Rule`
- **Default:** `{}`

Rule defines the conditions for matching a module and the behavior of handling those modules.

**Rule behavior**

Defines the processing behavior of the corresponding matching module, e.g. :

- Apply the list of Loader to these modules (`rules[].use`)
- Apply the module's type (`rules[].type`)
- Apply the module's resolve configuration (`rules[].resolve`)

### Condition

- **Type:**

```ts
type Condition =
  | string
  | RegExp
  | ((value: string) => boolean)
  | Conditions
  | LogicalConditions;

type Conditions = Condition[];

type LogicalConditions = {
  and?: Conditions;
  or?: Conditions;
  not?: Condition;
};
```

Defines a module's match conditions, common matches are [resource](#rulesresource), [resourceQuery](#rulesresourcequery), [include](#rulesinclude), and [exclude](#rulesexclude).

Example: app.js imports `./image.png?inline#foo`:

- `resource` is `/path/to/image.png`, and will match against with [rules\[\].resource](#rulesresource) Condition
- `resourceQuery` is `?inline`, and will match against with [rules\[\].resourceQuery](#rulesresourcequery) Condition
- `resourceFragment` is `#foo`, and will match against with [rules\[\].resourceFragment](#rulesresourcefragment) Condition

Condition represents the form of matching a given input, and it supports the following types:

- `String`: Given an input, the match is successful when the input string satisfies startsWith. Note: You can think of it as `input.startsWith(condition)`.
- `RegExp`: Given an input, the match is successful when the input string satisfies the regular expression. Note: You can think of it as `condition.test(input)`.
- `Condition[]`: A list of conditions. At least one of the Conditions must match.
- `LogicalConditions`: All Conditions must match.
  - `{ and: Condition[] }`: All Conditions must match.
  - `{ or: Condition[] }`: At least one of the Conditions must match.
  - `{ not: Condition }`: All Conditions must NOT match.
- `(value: string) => boolean`: If it's called with the input and return a truthy value, the match is succeeds.

### Nested rule

Nested Rule can be specified under the properties [`rules[].rules`](#rulesrules) and [`rules[].oneOf`](#rulesoneof), These rules are evaluated only when the parent Rule condition matches. Each nested rule can contain its own conditions.

The order of evaluation is as follows:

1. The parent Rule
2. [`rules[].rules`](#rulesrules)
3. [`rules[].oneOf`](#rulesoneof)

## rules\[].exclude

- **Type:** [`Condition`](#condition)
- **Default:** `undefined`

Excludes all modules that match this condition and will match against the absolute path of the resource (without query and fragment). This option cannot be present together with `rules[].resource`.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        exclude: /\.js$/,
      },
    ],
  },
};
```

## rules\[].include

- **Type:** [`Condition`](#condition)
- **Default:** `undefined`

Matches all modules that match this condition against the absolute path of the resource (without query and fragment). This option cannot be present together with `rules[].resource`.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        include: /\.js$/,
      },
    ],
  },
};
```

## rules\[].resource

- **Type:** [`Condition`](#condition)
- **Default:** `undefined`

Matches all modules that match this resource, and will match against Resource (the absolute path without query and fragment). This option cannot be present together with `rules[].test`.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        resource: /\.js$/,
      },
    ],
  },
};
```

## rules\[].resourceQuery

- **Type:** [`Condition`](#condition)
- **Default:** `undefined`

Matches all modules that match this resource against the Resource's query. Note: Containing `?`, when `rules[].resourceQuery` is `?raw`, it will match the resource request of `foo?raw`

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        resourceQuery: /inline/,
        type: 'asset/inline',
      },
    ],
  },
};
```

## rules\[].resourceFragment

- **Type:** [`Condition`](#condition)
- **Default:** `undefined`

Matches all modules that match this resource against the Resource's fragment. Note: Containing `#`, when `rules[].resourceFragment` is `#abc`, it will match the resource request of `foo#abc`

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        resourceFragment: '#abc',
      },
    ],
  },
};
```

## rules\[].test

- **Type:** [`Condition`](#condition)
- **Default:** `undefined`

Matches all modules that match this resource, and will match against Resource (the absolute path without query and fragment). This option cannot be present together with `rules[].resource`.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
      },
    ],
  },
};
```

## rules\[].issuer

- **Type:** [`Condition`](#condition)
- **Default:** `undefined`

Matches all modules that match this resource, and will match against Resource (the absolute path without query and fragment) of the module that issued the current module.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        issuer: /\.js$/,
      },
    ],
  },
};
```

## rules\[].issuerLayer

- **Type:** [`Condition`](#condition)
- **Default:** `undefined`

Matches all modules that match this resource, and will match against layer of the module that issued the current module.

For more information about layers, see the [Module layers guide](/guide/advanced/layer.md).

A basic example:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        issuerLayer: 'other-layer',
      },
    ],
  },
};
```

A more complex example is the combination with [entry options](/config/entry.md#entrydescriptionlayer) to build modern and legacy bundles at the same time:

```js title="rspack.config.mjs"
export default {
  entry: {
    index: {
      import: './src/index.js',
      layer: 'modern',
    },
    'index-legacy': {
      import: './src/index.js',
      layer: 'legacy',
    },
  },
  module: {
    rules: [
      {
        test: /\.js$/,
        issuerLayer: 'modern',
        options: {
          env: { targets: ['chrome >= 100'] },
        },
      },
      {
        test: /\.js$/,
        issuerLayer: 'legacy',
        options: {
          env: { targets: ['ie >= 11'] },
        },
      },
    ],
  },
};
```

## rules\[].dependency

- **Type:** [`Condition`](#condition)
- **Default:** `undefined`

Matches all modules that match this resource, and will match against the category of the dependency that introduced the current module, for example:

- `esm` for `import` and `import()`
- `cjs` for `require()`
- `url` for `new URL()` and `url()`.

For example, match all `.js` files, but exclude `url` type dependencies (such as `new URL('./path/to/foo.js', import.meta.url)`):

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        dependency: { not: 'url' },
      },
    ],
  },
};
```

## rules\[].phase


[Added in v2.0.8](https://github.com/web-infra-dev/rspack/releases/tag/v2.0.8)

Stability: Experimental

- **Type:** [`Condition`](#condition)
- **Default:** `undefined`

Matches modules by the import phase of the dependency that introduced the module.

The value passed to the condition is one of:

- `evaluation`: normal imports such as `import`, `import()`, `require()`, and other dependencies without a special import phase
- `defer`: `import defer` and `import.defer()` dependencies when [`experiments.deferImport`](/config/experiments.md#experimentsdeferimport) is enabled
- `source`: `import source` and `import.source()` dependencies when [`experiments.sourceImport`](/config/experiments.md#experimentssourceimport) is enabled

This is useful when the same resource needs different loaders, parser options, or module types depending on how it is imported.

```js title="rspack.config.mjs"
export default {
  experiments: {
    deferImport: true,
    sourceImport: true,
  },
  module: {
    rules: [
      {
        test: /module\.js$/,
        phase: 'evaluation',
        loader: './evaluation-loader.js',
      },
      {
        test: /module\.js$/,
        phase: 'defer',
        loader: './defer-loader.js',
      },
      {
        test: /module\.js$/,
        phase: 'source',
        loader: './source-loader.js',
      },
    ],
  },
};
```

## rules\[].scheme

- **Type:** [`Condition`](#condition)
- **Default:** `undefined`

Matches all modules that match this resource, and will match against the Resource's scheme.

For example, you can treat the inline data uri resource as a separate resource with the following configuration:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        scheme: 'data',
        type: 'asset/resource',
      },
    ],
  },
};
```

## rules\[].mimetype

- **Type:** [`Condition`](#condition)
- **Default:** `undefined`

Matches modules based on [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types) instead of file extension. It's primarily useful for [data URI module](/api/runtime-api/module-methods.md#data-uri-module).

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        mimetype: 'text/javascript',
        use: [
          // ...
        ],
      },
    ],
  },
};
```

## rules\[].descriptionData

- **Type:** `{ [key: string]: Condition }`
- **Default:** `undefined`

`descriptionData` matches property values in a module's description file, typically `package.json`, to determine which modules a rule applies to. This lets you configure rules for modules in specific packages based on metadata such as the package name or version.

Each key in the `descriptionData` object specifies a property to match, such as `name` or `version`, and the corresponding value is a [`Condition`](#condition) used to check that property's value. If you specify multiple properties, all must satisfy their conditions for the module to match `descriptionData`.

A string condition matches property values that start with the given string, so this example matches modules in packages such as `react` and `react-dom`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        descriptionData: { name: 'react' },
        // Other rule options...
      },
    ],
  },
};
```

A regular expression condition tests the property value against a pattern; this example uses `^` and `$` to match only modules in the package named `react`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        descriptionData: { name: /^react$/ },
        // Other rule options...
      },
    ],
  },
};
```

A function condition provides custom matching logic; this example matches modules in packages whose names contain `rspack`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        descriptionData: {
          name: (name) => name.includes('rspack'),
        },
        // Other rule options...
      },
    ],
  },
};
```

## rules\[].with

- **Type:** `{ [key: string]: Condition }`
- **Default:** `undefined`

`with` can be used in conjunction with [import attributes](https://github.com/tc39/proposal-import-attributes).

For example, the following configuration will match `{ type: "url" }` and will change the [`type`](/config/module-rules.md#rulestype) of the matched modules to `"asset/resource"`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        with: { type: 'url' },
        type: 'asset/resource',
      },
    ],
  },
};
```

The following import will match:

```ts
import url from './data' with { type: 'url' };
import('./data', { with: { type: 'url' } });
```

It should be noted that in order for Rspack to properly match the `with` syntax, when you use [builtin:swc-loader](/guide/features/builtin-swc-loader.md), you need to manually enable the `keepImportAttributes` configuration to preserve import attributes:

```diff title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        with: { type: 'url' },
        type: 'asset/resource',
      },
      {
        test: /\.(?:js|mjs|ts)$/,
        exclude: [/node_modules/],
        loader: 'builtin:swc-loader',
        options: {
          detectSyntax: 'auto',
          jsc: {
            experimental: {
+             keepImportAttributes: true,
            },
          },
        },
      },
    ],
  },
};
```

## rules\[].loader

`rules[].loader` is a shortcut to `rules[].use: [ { loader } ]`. See [rules\[\].use](/config/module-rules.md#rulesuse) for details.

For example, use the built-in swc-loader to compile TypeScript files:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|ts)$/,
        loader: 'builtin:swc-loader',
      },
    ],
  },
};
```

## rules\[].options

`rules[].options` is a shortcut to `rules[].use: [ { options } ]`. See [rules\[\].use](/config/module-rules.md#rulesuse) for details.

For example, pass options to the swc-loader:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.ts$/,
        loader: 'builtin:swc-loader',
        options: {
          detectSyntax: 'auto',
        },
      },
    ],
  },
};
```

## rules\[].parser

- **Type:** `Object`
- **Default:** `{}`

Parser options for the specific modules that matched by the rule conditions, this will override the parser options in `module.parser`.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css/,
        parser: {
          namedExports: false,
        },
        type: 'css/module',
      },
    ],
  },
};
```

For specific parser options and the corresponding module type, you can refer to [`module.parser`](/config/module-parser.md#parser).

## rules\[].generator

- **Type:** `Object`
- **Default:** `{}`

Generator options for the specific modules that matched by the rule conditions, this will override the parser options in `module.generator`.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.png/,
        generator: {
          filename: '[contenthash][ext]',
        },
        type: 'asset',
      },
    ],
  },
};
```

For specific generator options and the corresponding module type, you can refer to [`module.generator`](/config/module-generator.md#generator).

## rules\[].sideEffects

- **Type:** `boolean`

Flag the module for side effects, this will affect the result of [Tree Shaking](/guide/optimization/tree-shaking.md).

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /foo\.js$/,
        sideEffects: false,
      },
    ],
  },
};
```

## rules\[].enforce


- Type: `'pre' | 'post'`


Specifies the category of the loader. When not specified, it defaults to normal loader.

There is also an additional category "inlined loader" which are loaders applied inline of the import/require.

When specified as `'pre'`, the loader will execute before all other loaders.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        enforce: 'pre',
        loader: 'my-pre-loader',
      },
    ],
  },
};
```

When specified as `'post'`, the loader will execute after all other loaders.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        enforce: 'post',
        loader: 'my-post-loader',
      },
    ],
  },
};
```

There are two phases that all loaders enter one after the other:

- **Pitching phase:** the `pitch` method on loaders is called in the order `post, inline, normal, pre`. See [Pitching Loader](/api/loader-api/writing-loaders.md#pitching-loader) for details.
- **Normal phase:** the default method on loaders is executed in the order `pre, normal, inline, post`. Transformation on the source code of a module happens in this phase.

## rules\[].type

- **Type:** `string`

Common built-in values:

```ts
type BuiltinRuleType =
  | 'asset'
  | 'asset/source'
  | 'asset/resource'
  | 'asset/inline'
  | 'asset/bytes'
  | 'css'
  | 'css/auto'
  | 'css/global'
  | 'css/module'
  | 'javascript/auto'
  | 'javascript/dynamic'
  | 'javascript/esm'
  | 'json';
```

Used to mark the type of the matching module, which affects how the module is handled by Rspack's built-in processing.

By default, Rspack will determine the type of the module based on the file extension. For example:

- `.js` files will be treated as `javascript/auto` modules.
- `.mjs` files, as well as `.js` files in packages with `type="module"` in package.json, will be treated as `javascript/esm` modules.
- `.json` files will be treated as `json` modules.
- `.css` files will be treated as `css/auto` modules.

For example, if you want to load a `.json` file through a custom loader, you'd need to set the type to `javascript/auto` to bypass Rspack's built-in JSON importing.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.json$/,
        type: 'javascript/auto',
        loader: 'custom-json-loader',
      },
    ],
  },
};
```

The meanings of all `type` options are as follows:

- `'javascript/auto'`: JavaScript modules. Rspack automatically determines the module type based on file content, providing the best compatibility.
- `'javascript/esm'`: JavaScript modules, treated as strict ES modules.
- `'javascript/dynamic'`: JavaScript modules, treated as Script.
- `'json'`: JSON data module, see [JSON](/guide/languages/json.md).
- `'css' | 'css/auto' | 'css/global' | 'css/module'`: CSS module, see [Built-in CSS support](/guide/languages/css.md#built-in-css-support).
- `'asset' | 'asset/source' | 'asset/resource' | 'asset/inline' | 'asset/bytes'`: Asset module, see [Asset Module](/guide/features/asset-module.md).

## rules\[].layer

- **Type:** `string`

Used to mark the layer of the matching module. A group of modules could be united in one layer which could then be used in split chunks, stats or [entry options](/config/entry.md#entrydescriptionlayer).

For more information about layers, see the [Module layers guide](/guide/advanced/layer.md).

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        layer: 'layer-name',
      },
    ],
  },
};
```

## rules\[].use

- **Type:**

```ts
type RuleSetUse =
  | RuleSetUseItem
  | RuleSetUseItem[]
  | ((ctx: RawFuncUseCtx) => RuleSetUseItem[]);

type RuleSetUseItem = string | RuleSetLoaderWithOptions;

type RuleSetLoaderWithOptions = {
  ident?: string;
  loader: string;
  options?: string | Record<string, any>;
  parallel?: boolean | { maxWorkers?: number };
};
```

An array to pass the Loader package name and its options. `string[]` e.g.: `use: ['svgr-loader']` is shorthand for `use: [ { loader: 'svgr-loader' } ]`.
Loaders will be executed in right-to-left order.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        use: [
          'svgr-loader',
          {
            loader: 'svgo-loader',
            options: {
              configFile: false,
            },
          },
        ],
      },
    ],
  },
};
```

A function can also be used:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.svg$/,
        type: 'asset',
        use: (info) => [
          {
            loader: 'svgo-loader',
            options: {
              plugins: [
                {
                  cleanupIDs: { prefix: basename(info.resource) },
                },
              ],
            },
          },
        ],
      },
    ],
  },
};
```

## rules\[].use.ident

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

Provides a stable name for object-form loader options. Rspack uses it when building the loader request, so generated rules or reused options can keep the same `??<ident>` reference.

Most configurations do not need to set it manually. If omitted, Rspack uses `options.ident` when present, otherwise it generates an internal identifier.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.svg$/,
        use: [
          {
            loader: 'svgo-loader',
            ident: 'svgo-inline',
            options: {
              multipass: true,
            },
          },
        ],
      },
    ],
  },
};
```

## rules\[].use.parallel


[Added in v1.3.1](https://github.com/web-infra-dev/rspack/releases/tag/v1.3.1)

- **Type**: `boolean | { maxWorkers?: number }`
- **Default:** `false`

Controls whether a given loader should run in worker threads for parallel execution. Loaders marked with `parallel` are scheduled across multiple threads, reducing pressure on the main thread and improving overall build performance.

- When set to `true`, the loader runs in a worker. Rspack automatically selects an appropriate number of worker threads.
- When set to `{ maxWorkers }`, you can explicitly define the maximum number of workers to use.
- When set to `false` or omitted, the loader runs on the main thread.

For example, enabling parallel execution for `less-loader`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          {
            loader: 'less-loader',
            parallel: true,
            options: {
              // loader options
            },
          },
        ],
      },
    ],
  },
};
```

When multiple loaders within the same rule have `parallel` enabled, Rspack executes them sequentially inside the same worker until it encounters a non-parallel loader or a Rust-implemented builtin loader. This preserves loader order while maximizing parallel efficiency.

:::tip

- The loader options must comply with the [HTML structured clone algorithm](https://nodejs.org/api/worker_threads.html#portpostmessagevalue-transferlist), otherwise transmission will fail.
- In worker mode, most methods on `LoaderContext._compilation`, `LoaderContext._compiler`, `LoaderContext._module` are not supported.

:::

## rules\[].use.parallel.maxWorkers

- **Type:** `number`
- **Default:** `undefined`

Limits the maximum number of worker threads used by the shared loader worker pool when `parallel` is configured as an object. Use a positive integer.

When `maxWorkers` is omitted, Rspack automatically chooses the worker count. The loader worker pool is shared within the current process, so use a consistent `maxWorkers` value if multiple loaders configure `parallel`.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          {
            loader: 'less-loader',
            parallel: {
              maxWorkers: 4,
            },
            options: {},
          },
        ],
      },
    ],
  },
};
```

## rules\[].resolve

Set specific module [resolve](/config/resolve.md) options based on the matching modules.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        resolve: {
          preferRelative: true,
        },
      },
    ],
  },
};
```

## rules\[].rules

- **Type:** <code>[Rule](#rule)\[]</code>
- **Default:** `undefined`

A kind of [Nested Rule](#nested-rule), an array of Rules that is also used when the parent Rule matches.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        // When a CSS file is matched, continue to use these nested rules
        rules: [
          {
            // Handle CSS files with "?raw" query
            resourceQuery: /raw/,
            type: 'asset/source',
          },
          {
            // Handle normal CSS files
            resourceQuery: {
              not: /raw/,
            },
            type: 'css/auto',
          },
        ],
      },
    ],
  },
};
```

## rules\[].oneOf

- **Type:** <code>([Rule](#rule) | Falsy)\[]</code>
- **Default:** `undefined`

A kind of [Nested Rule](#nested-rule), an array of Rules from which only the first matching Rule is used when the parent Rule matches.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(png|jpg)$/i,
        oneOf: [
          {
            // Handle images with "?raw" query
            resourceQuery: /raw/,
            type: 'asset/source',
          },
          {
            // Otherwise, output as a separate file
            type: 'asset/resource',
          },
        ],
      },
    ],
  },
};
```

## rules\[].extractSourceMap


[Added in v1.6.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.6.0)

- **Type**: `boolean`
- **Default:** `false`

Extracts existing source map data from files (from their `//# sourceMappingURL` comment), useful for preserving the source maps of third-party libraries.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.m?js$/,
        extractSourceMap: true,
      },
    ],
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/module/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/node.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Node

The following Node.js options configure whether to polyfill or mock certain [Node.js globals](https://nodejs.org/docs/latest/api/globals.html).

- **Type:** `false | object`

Set `node` to `false` to disable all Node.js global polyfills and mocks. Otherwise, configure the individual options below.

## node.global

- **Type:** `boolean | 'warn'`
- **Default:** `'warn'`

Controls whether Rspack should provide a polyfill for the Node.js `global` object when bundling for non-Node environments.

See [the Node.js documentation](https://nodejs.org/api/globals.html#globals_global) for the exact behavior of this object.

### Available values

- `true`: Rspack injects a polyfill so that `global` is available in the bundle. This ensures compatibility with code that relies on Node.js globals in non-Node runtimes
- `false`: No polyfill is provided. References to `global` remain untouched. If your target environment does not define `global`, accessing it will throw a `ReferenceError` at runtime
- `'warn'`: Inject a polyfill like `true`, but also emit a warning when `global` is used

### Examples

For example, to disable `global` polyfill:

```js title="rspack.config.mjs"
export default {
  node: {
    global: false,
  },
};
```

## node.\_\_filename

- **Type:** `boolean | 'mock' | 'warn-mock' | 'eval-only' | 'node-module'`
- **Default:**
  - If `target` does not include `node`, defaults to `'warn-mock'`.
  - If `target` includes `node`, uses `'node-module'` if [output.module](/config/output.md#outputmodule) is enabled, otherwise `'eval-only'`.

Controls how Rspack handles the Node.js [`__filename`](https://nodejs.org/api/modules.html#__filename) and [`import.meta.filename`](https://nodejs.org/api/esm.html#importmetafilename) variables when bundling for non-Node environments.

### Available values

- `true`: Replace with the relative file path of the source file, relative to the [`context`](/config/context.md) option
- `false`: Do nothing and keep the native behavior
- `'mock'`: Replace with `'/index.js'`
- `'eval-only'`: Equivalent to `false`
- `'warn-mock'`: Replace with `'/index.js'`, and emit a warning to indicate a potential Node.js dependency in the code
- `'node-module'`: Only used when [output.module](/config/output.md#outputmodule) is enabled. Replace `__filename` in CommonJS with an equivalent implementation based on `import.meta.url`, suitable for ESM output

### Examples

For example, to avoid processing `__filename` and `import.meta.filename`, preserving the original content in the output:

```js title="rspack.config.mjs"
export default {
  node: {
    __filename: false,
  },
};
```

To replace `__filename` and `import.meta.filename` in ESM output with `fileURLToPath(import.meta.url)`:

```js title="rspack.config.mjs"
export default {
  target: 'node',
  output: {
    module: true,
  },
  node: {
    __filename: 'node-module',
  },
};
```

## node.\_\_dirname

- **Type:** `boolean | 'mock' | 'warn-mock' | 'eval-only' | 'node-module'`
- **Default:**
  - If `target` does not include `node`, defaults to `'warn-mock'`.
  - If `target` includes `node`, uses `'node-module'` if [output.module](/config/output.md#outputmodule) is enabled, otherwise `'eval-only'`.

Controls how Rspack handles the Node.js [`__dirname`](https://nodejs.org/api/modules.html#__dirname) and [`import.meta.dirname`](https://nodejs.org/api/esm.html#importmetadirname) variables when bundling for non-Node environments.

### Available values

- `true`: Replace with the directory path of the source file, relative to the [`context`](/config/context.md) option
- `false`: Do nothing and keep the native behavior
- `'mock'`: Replace with `'/'`
- `'eval-only'`: Equivalent to `false`
- `'warn-mock'`: Replace with `'/'`, and emit a warning to indicate a potential Node.js dependency in the code
- `'node-module'`: Only used when [output.module](/config/output.md#outputmodule) is enabled. Replace `__dirname` in CommonJS with an equivalent implementation based on `import.meta.url`, suitable for ESM output

### Examples

For example, to avoid processing `__dirname` and `import.meta.dirname`, preserving the original content in the output:

```js title="rspack.config.mjs"
export default {
  node: {
    __dirname: false,
  },
};
```

To replace `__dirname` and `import.meta.dirname` in ESM output with `fileURLToPath(import.meta.url + "/..")`:

```js title="rspack.config.mjs"
export default {
  target: 'node',
  output: {
    module: true,
  },
  node: {
    __dirname: 'node-module',
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/node/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/optimization.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Optimization

Rspack will select appropriate optimization configuration based on the [`mode`](/config/mode.md). You can also customize the configuration via [`optimization`](/config/optimization.md).

## optimization.avoidEntryIife


- Type: `boolean`
- Default:`false`


Use `optimization.avoidEntryIife` to avoid wrapping the entry module in an IIFE when it is required (search for `"This entry needs to be wrapped in an IIFE because"` in [rspack\_plugin\_javascript](https://github.com/web-infra-dev/rspack/blob/main/crates/rspack_plugin_javascript/src/plugin/mod.rs)). This approach helps optimize performance for JavaScript engines and helps tree shaking when building ESM libraries.

Currently, `optimization.avoidEntryIife` can only optimize a single entry module along with other modules.

```js title="rspack.config.mjs"
export default {
  optimization: {
    avoidEntryIife: true,
  },
};
```

:::warning
The `⁠optimization.avoidEntryIife` option can negatively affect build performance. If you prioritize build performance over these optimizations, consider not enabling this option.
:::

## optimization.chunkIds


- Type: `false | 'natural' | 'named' | 'deterministic' | 'compact-hashed' | 'size' | 'total-size'`
- Default:[development mode](/config/mode#development) is`'named'`, [production mode](/config/mode#production) is`'deterministic'`


Tells Rspack which algorithm to use when generating chunk ids.

The following string values are supported:

| option             | description                                                                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `'natural'`        | Use numeric ids in order of usage.                                                                                                             |
| `'named'`          | Readable ids for better debugging.                                                                                                             |
| `'deterministic'`  | Short numeric ids which will not be changing between compilation. Good for long term caching. By default a minimum length of 3 digits is used. |
| `'compact-hashed'` | Use the shortest available prefix of a stable lowercase alphanumeric hash.                                                                     |
| `'size'`           | Use numeric ids to make the initial download package smaller.                                                                                  |
| `'total-size'`     | Use numeric ids to make the overall download package smaller.                                                                                  |
| `false`            | Disable Rspack's built-in chunk id algorithm, allowing a custom plugin to provide chunk ids.                                                   |

```js title="rspack.config.mjs"
export default {
  optimization: {
    chunkIds: 'deterministic',
  },
};
```

The `compact-hashed` option uses the shortest available prefix of a stable lowercase alphanumeric hash as the chunk id, balancing long-term caching, bundle size, and runtime performance.

:::warning Deprecated alias
`compat-hashed` was available in Rspack 2.2.0. It is deprecated and was renamed to `compact-hashed` in Rspack 2.2.1. It remains available as a compatibility alias.
:::

```js title="rspack.config.mjs"
export default {
  optimization: {
    chunkIds: 'compact-hashed',
  },
};
```

:::tip
The `compact-hashed` option is available in Rspack 2.2.1 and later.
:::

## optimization.concatenateModules


- Type: `boolean`
- Default:[production mode](/config/mode#production) is`true`, [development mode](/config/mode#development) is`false`


Tells Rspack to find segments of the module graph which can be safely concatenated into a single module. Depends on [optimization.providedExports](#optimizationprovidedexports) and [optimization.usedExports](#optimizationusedexports). By default `optimization.concatenateModules` is enabled in `production` mode and disabled elsewise.

```js title="rspack.config.mjs"
export default {
  optimization: {
    concatenateModules: false,
  },
};
```

## optimization.emitOnErrors


- Type: `boolean`
- Default:[production mode](/config/mode#production) is`false`, [development mode](/config/mode#development) is`true`


Use the `optimization.emitOnErrors` to emit assets whenever there are errors while compiling. This ensures that erroring assets are emitted. The errors are emitted into the generated code and will cause errors at runtime.

```js title="rspack.config.mjs"
export default {
  optimization: {
    emitOnErrors: true,
  },
};
```

## optimization.inlineExports


[Added in v1.7.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.7.0)


- Type: `boolean`
- Default:[production mode](/config/mode#production) is`true`, [development mode](/config/mode#development) is`false`


Performs cross-module inline optimization for:

1. Exported top-level constant values that can be statically evaluated:
   - `null` or `undefined`
   - `boolean` values (`true` or `false`)
   - `number` with length \<= 6
   - `string` with length \<= 6

2. Exported TypeScript enums that collected by [`builtin:swc-loader collectTypeScriptInfo.exportedEnum`](/guide/features/builtin-swc-loader.md#collecttypescriptinfoexportedenum)

This optimization helps reduce bundle size and can improve runtime performance.

A common use case is with `constants.js` files:

```js
// constants.js
export const A = true;
export const B = 'hello';

// index.js
import { A, B } from './constants';
console.log(A ? 1 : 2);
console.log(B.length);
```

When `inlineExports` is enabled, constant values will be inlined at their usage sites:

```js
// Bundled by Rspack: output.js
const __webpack_modules__ = {
  './index.js': () => {
    // Constants are inlined directly
    console.log(true ? 1 : 2);
    console.log('hello'.length);
    // If all exports from constants.js are inlined, the constants.js module
    // will be optimized away and won't appear in the final output
  },
};
```

:::tip
Since this feature relies on module export usage information ([optimization.usedExports](#optimizationusedexports)), it is recommended to enable it only in production mode where `usedExports` is enabled by default.
:::

:::warning TDZ behavior
Inlining constant exports from modules in circular dependencies may change code that would otherwise throw a temporal dead zone (TDZ) error so that it no longer throws. Most tools in the ecosystem generally do not preserve TDZ errors when optimizing; Rspack also follows this optimization-first behavior.
:::

For more details, refer to the [inline const example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/inline-const).

## optimization.innerGraph


- Type: `boolean`
- Default:[production mode](/config/mode#production) is`true`, [development mode](/config/mode#development) is`false`


`optimization.innerGraph` tells Rspack whether to perform a more detailed analysis of variable assignments. This helps Rspack to identify unused module exports, thereby reducing the size of the bundled output.

For example:

```js
import { value } from 'lib';

const value2 = value;

function f1() {
  console.log(value);
}

function f2() {
  console.log(value2);
}
```

Here we assign the `value` to `value2`. Both `value2` and `value` are accessed within the functions `f2` and `f1` respectively, but the functions are not called, hence `value2` and `value` are not actually used, thus the import of `value` can be removed.

## optimization.mangleExports


- Type: `boolean | 'deterministic' | 'size'`
- Default:[production mode](/config/mode#production) is`true`, [development mode](/config/mode#development) is`false`


`optimization.mangleExports` controls how export names are mangled.

The following values are supported:

| option            | description                                                                                                    |
| ----------------- | -------------------------------------------------------------------------------------------------------------- |
| `'size'`          | Use the shortest possible export names to reduce bundle size.                                                  |
| `'deterministic'` | Use short and stable export names for better long-term cache stability. Enabled by default in production mode. |
| `true`            | Same as `'deterministic'`.                                                                                     |
| `false`           | Disable export mangling and keep original export names. Enabled by default in development mode.                |

For example, with the following source code:

```js title="src/math.js"
export const veryLongExportName = 1;
```

When `mangleExports` is disabled, the export name is preserved:

```js title="dist/main.js"
__webpack_require__.d(__webpack_exports__, {
  veryLongExportName: () => veryLongExportName,
});
```

When `mangleExports` is set to `'size'`, the export name is shortened:

```js title="rspack.config.mjs"
export default {
  optimization: {
    mangleExports: 'size',
  },
};
```

```js title="dist/main.js"
__webpack_require__.d(__webpack_exports__, {
  a: () => veryLongExportName,
});
```

## optimization.mergeDuplicateChunks


- Type: `boolean`
- Default:`true`


Whether to merge chunks which contain the same modules. Setting `optimization.mergeDuplicateChunks` to `false` will disable this optimization.

```js title="rspack.config.mjs"
export default {
  optimization: {
    mergeDuplicateChunks: false,
  },
};
```

## optimization.minimize


- Type: `boolean`
- Default:[production mode](/config/mode#production) is`true`, [development mode](/config/mode#development) is`false`


Whether to use the minimizer declared in [`optimization.minimizer`](#optimizationminimizer) to minimize the bundle.

```js title="rspack.config.mjs"
export default {
  optimization: {
    minimize: true,
  },
};
```

## optimization.minimizer


- Type: `('...' | Plugin)[]`
- Default:`[new SwcJsMinimizerRspackPlugin(), new LightningCssMinimizerRspackPlugin()]`


Customize the minimizer. By default, [`rspack.SwcJsMinimizerRspackPlugin`](/plugins/swc-js-minimizer-rspack-plugin.md) and [`rspack.LightningCssMinimizerRspackPlugin`](/plugins/lightning-css-minimizer-rspack-plugin.md) are used.

When `optimization.minimizer` is specified, the default minimizers will be disabled.

```js title="rspack.config.mjs"
import TerserPlugin from 'terser-webpack-plugin';

export default {
  optimization: {
    minimizer: [new TerserPlugin()],
  },
};
```

Use Rspack's built-in minimizer with custom options:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  optimization: {
    // when `optimization.minimizer` is specified, the default minimizers are disabled by default
    // but you can use '...', it represents the default minimizers
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin({
        minimizerOptions: {
          format: {
            comments: false,
          },
        },
      }),
      new rspack.LightningCssMinimizerRspackPlugin({
        minimizerOptions: {
          errorRecovery: false,
        },
      }),
    ],
  },
};
```

## optimization.moduleIds


- Type: `false | 'natural' | 'named' | 'deterministic' | 'compact-hashed' | 'hashed'`
- Default:[production mode](/config/mode#production) is`'deterministic'`, [development mode](/config/mode#development) is`'named'`, [none mode](/config/mode#none) is`'natural'`


Tells Rspack which algorithm to use when generating module ids.

The following string values are supported:

| option           | description                                                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `natural`        | Use numeric ids in order of usage.                                                                                             |
| `named`          | Use meaningful, easy-to-debug content as id.                                                                                   |
| `deterministic`  | Use the hashed module identifier as the id to benefit from long-term caching. By default a minimum length of 3 digits is used. |
| `compact-hashed` | Use the shortest available prefix of a stable alphanumeric hash.                                                               |
| `hashed`         | Use hashed module identifiers as ids. Equivalent to using `HashedModuleIdsPlugin` with default options (md4, base64, 4 chars). |
| `false`          | Disable Rspack's built-in module id algorithm, allowing a custom plugin to provide module ids.                                 |

We recommend using `named` in development and `deterministic` or `compact-hashed` in production.

Use `process.env.NODE_ENV` to determine the current environment:

```js title="rspack.config.mjs"
const isDev = process.env.NODE_ENV === 'development';

export default {
  optimization: {
    moduleIds: isDev ? 'named' : 'deterministic',
  },
};
```

The `compact-hashed` option uses the shortest available prefix of a stable alphanumeric hash as the module id, balancing long-term caching, bundle size, and runtime performance.

:::warning Deprecated alias
`compat-hashed` was available in Rspack 2.2.0. It is deprecated and was renamed to `compact-hashed` in Rspack 2.2.1. It remains available as a compatibility alias.
:::

:::warning
`compact-hashed` module ids are case-sensitive and may contain uppercase letters. On case-insensitive file systems, avoid using `[id]` as the only distinguishing placeholder in [Asset module filenames](/config/output.md#outputassetmodulefilename) or [WebAssembly module filenames](/config/output.md#outputwebassemblymodulefilename). Prefer `[contenthash]`, or include it alongside `[id]`.
:::

```js title="rspack.config.mjs"
const isDev = process.env.NODE_ENV === 'development';

export default {
  optimization: {
    moduleIds: isDev ? 'named' : 'compact-hashed',
  },
};
```

:::tip
The `compact-hashed` option is available in Rspack 2.2.1 and later.
:::

## optimization.nodeEnv

- **Type:** `string | false`
- **Default:** Determined by [`mode`](/config/mode.md):
  - [`production` mode](/config/mode.md#production): `'production'`
  - [`development` mode](/config/mode.md#development): `'development'`
  - [`none` mode](/config/mode.md#none): `false`

`optimization.nodeEnv` controls the value used to replace `process.env.NODE_ENV` at compile time. Rspack performs this replacement with [DefinePlugin](/plugins/define-plugin.md).

You can override the mode-dependent default with either of the following values:

- Any string: replace `process.env.NODE_ENV` with the specified string.
- `false`: disable the replacement and leave `process.env.NODE_ENV` unchanged.

```js title="rspack.config.mjs"
export default {
  optimization: {
    nodeEnv: 'production',
  },
};
```

## optimization.providedExports


- Type: `boolean`
- Default:`true`


After enabling, Rspack will analyze which exports the module provides, including re-exported modules. A warning or error will be issued when importing members that reference non-existent exports. By default, `optimization.providedExports` is enabled. This analysis will increase build time. You may consider disabling this configuration in development mode. Disabling it may lead to errors related to runtime circular dependencies as mentioned in the [SideEffects section](/guide/optimization/tree-shaking.md#re-export-analysis).

```js title="rspack.config.mjs"
export default {
  optimization: {
    providedExports: false,
  },
};
```

## optimization.realContentHash


- Type: `boolean`
- Default:[production mode](/config/mode#production) is`true`, [development mode](/config/mode#development) is`false`


Adds an additional hash compilation pass after the assets have been processed to get the correct asset content hashes. This feature will enable by default in production mode.

If realContentHash is set to false, internal data is used to calculate the hash and it can change when assets are identical in some cases.

```js title="rspack.config.mjs"
export default {
  optimization: {
    realContentHash: true,
  },
};
```

## optimization.removeEmptyChunks


- Type: `boolean`
- Default:`true`


Detect and remove empty chunks generated in the compilation. Setting `optimization.removeEmptyChunks` to `false` will disable this optimization.

```js title="rspack.config.mjs"
export default {
  optimization: {
    removeEmptyChunks: false,
  },
};
```

## optimization.runtimeChunk


- Type: `boolean | 'single' | 'multiple' | { name?: string | ((entrypoint: { name: string }) => string) }`
- Default:`false`


Used to control how the Rspack's [runtime](/misc/glossary.md#runtime) chunk is generated.

Defaults to `false`, which means the runtime code is inlined into the entry chunks.

Setting it to `true` or `'multiple'` will add an additional chunk containing only the runtime for each entry point. This setting is an alias for:

```js title="rspack.config.mjs"
export default {
  optimization: {
    runtimeChunk: {
      name: (entrypoint) => `runtime~${entrypoint.name}`,
    },
  },
};
```

Setting it to `'single'` will extract the runtime code of all entry points into a single separate chunk named `runtime`. This setting is an alias for:

```js title="rspack.config.mjs"
export default {
  optimization: {
    runtimeChunk: {
      name: 'runtime',
    },
  },
};
```

By setting `optimization.runtimeChunk` to an object it can provide an optional `name` property which stands for the name for the runtime chunks.

```js title="rspack.config.mjs"
export default {
  optimization: {
    runtimeChunk: {
      // this will generate a chunk named `my-name.js`
      name: 'my-name',
    },
  },
};
```

:::tip
Imported modules are initialized for each runtime chunk separately, so if you include multiple entry chunks on a page, beware of this behavior. You will need to set `optimization.runtimeChunk` to `'single'` or use another configuration that ensures the page only contains one runtime instance.
:::

## optimization.sideEffects


- Type: `boolean | 'flag'`
- Default:[production mode](/config/mode#production) is`true`, [development mode](/config/mode#development) is`'flag'`


If you only want Rspack use the manual `sideEffects` flag via (`package.json` and `rules[].sideEffects`) and don't analyse source code:

```js title="rspack.config.mjs"
export default {
  optimization: {
    sideEffects: 'flag',
  },
};
```

`flag` tells Rspack to recognise the sideEffects flag in package.json or [rules\[\].sideEffects](/config/module-rules.md#rulessideeffects) to skip over modules which are flagged to contain no side effects when exports are not used.

`true` tells Rspack not only recognise the sideEffects flag, but also analyse modules which are not flagged explicitly, and determine if they have side effects or not.

```js title="rspack.config.mjs"
export default {
  optimization: {
    sideEffects: true,
  },
};
```

:::tip
`optimization.sideEffects` depends on [`optimization.providedExports`](#optimizationprovidedexports) to be enabled.
This dependency has a build time cost, but eliminating modules has positive impact on performance because of less code generation.
Effect of this optimization depends on your codebase, try it for possible performance wins.
:::

## optimization.splitChunks


- Type: `false | object`


Rspack supports splitting chunks with the `optimization.splitChunks` configuration item.

It is enabled by default for dynamically imported modules.

To turn it off, set it to `false`.

See available options for configuring this behavior in the [SplitChunksPlugin](/plugins/split-chunks-plugin.md) page.

## optimization.usedExports


- Type: `boolean | 'global'`
- Default:[production mode](/config/mode#production) is`true`, [development mode](/config/mode#development) is`false`


Tells Rspack to determine used exports for each module. This depends on `optimization.providedExports`.
Information collected by `optimization.usedExports` is used by other optimizations or code generation i.e.
Exports are not generated for unused exports, export names are mangled to single char identifiers when all usages are compatible. Dead code elimination in minimizers will benefit from this and can remove unused exports.

```js title="rspack.config.mjs"
export default {
  optimization: {
    usedExports: false,
  },
};
```

To opt-out from used exports analysis per runtime:

```js title="rspack.config.mjs"
export default {
  optimization: {
    usedExports: 'global',
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/optimization/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/output.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Output

The top-level output key contains a set of options instructing Rspack on how and where it should output your bundles, assets, and anything else you bundle or load with Rspack.

- **Type:** `Object`

## output.assetModuleFilename

- **Type:** `string | ((pathData: PathData, assetInfo?: AssetInfo) => string)`
- **Default:** `'[hash][ext][query]'`

The same as [`output.filename`](#outputfilename) but for [Asset Modules](/guide/features/asset-module.md).

`[name]`, `[file]`, `[query]`, `[fragment]`, `[base]`, and `[path]` are set to an empty string for the assets built from data URI replacements.

The name of the file to be output by the Asset module. This value can be overridden by [rules\[\].generator.filename](/config/module-rules.md#rulesgenerator).

:::info Asset module output as a separate file

- Module type is `'asset'` and asset is set to satisfy [rules\[\].parser.dataUrlCondition](/config/module-parser.md#assetdataurlcondition)
- Module type is `'asset/resource'`

:::

## output.asyncChunks

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

Controls whether dynamically imported modules are emitted as separate async chunks or bundled into existing chunks.

- `true`: Modules loaded via `import()` are split into independent async chunks. These chunks are emitted as separate files and are loaded on demand at runtime. This enables code splitting and keeps the initial bundle smaller.
- `false`: Dynamically imported modules are bundled into existing chunks instead of being emitted as separate files. No additional async chunk files are generated.

```js title="rspack.config.mjs"
export default {
  output: {
    asyncChunks: false,
  },
};
```

## output.bundlerInfo


[Added in v2.0.0](https://github.com/web-infra-dev/rspack/releases/tag/v2.0.0)

> In versions 1.x, use `experiments.rspackFuture.bundlerInfo` instead.

- **Type**:

  ```ts
  type BundlerInfo = {
    version?: string,
    bundler?: string,
    force?: ('version' | 'uniqueId')[] ｜ boolean;
  };
  ```

Used to inject the currently used Rspack information into the generated asset:

- `version`: Used to specify the Rspack version, defaults to the `version` field in `@rspack/core/package.json`.
- `bundler`: Used to specify the name of the packaging tool, defaults to `rspack`.
- `force`: Whether to force the injection of Rspack information, which will be added to chunk as a runtime module, and defaults to `false`. An array can be used to select the items to be forced injected.

By default, injection occurs when either `import.meta.rspackVersion` or `import.meta.rspackUniqueId` is detected in the code, and only the corresponding runtime module is injected. Set `force` to `true` to always inject both:

- [`import.meta.rspackVersion`](/api/runtime-api/module-variables.md#importmetarspackversion): Inject version information.
- [`import.meta.rspackUniqueId`](/api/runtime-api/module-variables.md#importmetarspackuniqueid): Inject the unique ID of the bundler.

```js title="rspack.config.mjs"
export default {
  output: {
    bundlerInfo: { force: true },
  },
};
```

## output.chunkFilename

- **Type:** `string | ((pathData: PathData, assetInfo?: AssetInfo) => string)`
- **Default:** Determined by [`output.filename`](/config/output.md#outputfilename) when it is not a function, otherwise `'[id].js'`.

This option determines the name of non-initial chunk files. See [`output.filename`](/config/output.md#outputfilename) option for details on the possible values.

Note that these filenames need to be generated at runtime to send the requests for chunks. Because of this, placeholders like `[name]` and `[chunkhash]` need to add a mapping from chunk id to placeholder value to the output bundle with the Rspack runtime. This increases the size and may invalidate the bundle when placeholder value for any chunk changes.

When this option is omitted, Rspack derives it from [`output.filename`](#outputfilename):

- If `output.filename` is a string containing `[name]`, `[id]`, `[chunkhash]`, or `[contenthash]`, Rspack reuses that string. In particular, `[name]` is not replaced with `[id]`.
- Otherwise, Rspack inserts `[id].` before the basename, preserving the directory and query string.
- If `output.filename` is a function, the default is `'[id].js'`. Rspack does not call that function to derive `output.chunkFilename`.

| `output.filename`     | Default `output.chunkFilename` |
| --------------------- | ------------------------------ |
| `'[name].js'`         | `'[name].js'`                  |
| `'[name].mjs'`        | `'[name].mjs'`                 |
| `'scripts/bundle.js'` | `'scripts/[id].bundle.js'`     |
| A function            | `'[id].js'`                    |

To choose a different template explicitly:

```js title="rspack.config.mjs"
export default {
  output: {
    chunkFilename: '[id].js',
  },
};
```

:::tip
See [Filename placeholders](/config/filename-placeholders.md) for more information.
:::

Usage as a function:

```js title="rspack.config.mjs"
export default {
  output: {
    chunkFilename: (pathData) => {
      return pathData.chunk.name === 'main' ? '[name].js' : '[name]/[name].js';
    },
  },
};
```

## output.chunkFormat

- **Type:** `false | 'array-push' | 'commonjs' | 'module' | string`
- **Default:** Determined by [`target`](/config/target.md) and [`output.module`](#outputmodule)

The format of chunks (formats included by default are `'array-push'` (web/webworker), `'commonjs'` (node.js), `'module'` (ESM), but others might be added by plugins).

:::tip

The default value of this option depends on the [`target`](/config/target.md) and [`output.module`](#outputmodule) setting. For more details, search for "chunkFormat" [in the Rspack defaults](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack/src/config/defaults.ts).

:::

```js title="rspack.config.mjs"
export default {
  output: {
    chunkFormat: 'commonjs',
  },
};
```

## output.chunkLoading

- **Type:** `false | 'jsonp' | 'import-scripts' | 'require' | 'async-node' | 'import' | string`

The method to load chunks (methods included by default are `'jsonp'` (web), `'import'` (ESM), `'import-scripts'` (webworker), `'require'` (sync node.js), `'async-node'` (async node.js), but others might be added by plugins). The default value will be determined based on the configuration of [`target`](/config/target.md) and [`chunkFormat`](#outputchunkformat).

:::tip

The default value of this option depends on the [`target`](/config/target.md) and [`chunkFormat`](#outputchunkformat) setting. For more details, search for `"chunkLoading"` [in the Rspack defaults](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack/src/config/defaults.ts).

:::

```js title="rspack.config.mjs"
export default {
  output: {
    chunkLoading: 'async-node',
  },
};
```

## output.chunkLoadingGlobal

- **Type:** `string`
- **Default:** Determined by [`output.uniqueName`](/config/output.md#outputuniquename)

The global variable is used by Rspack for loading chunks.

```js title="rspack.config.mjs"
export default {
  output: {
    chunkLoadingGlobal: 'myCustomFunc',
  },
};
```

## output.chunkLoadTimeout

- **Type:** `number`
- **Default:** `120000`

The Number of milliseconds before chunk request timed out.

```js title="rspack.config.mjs"
export default {
  output: {
    chunkLoadTimeout: 30000, // 30 seconds before chunk request timed out.
  },
};
```

## output.clean

- **Type:** `boolean | { keep?: string | RegExp | ((path: string) => boolean) }`
- **Default:** `false`

Before generating the products, delete all files in the output directory.

```js title="rspack.config.mjs"
export default {
  output: {
    clean: true, // Clean the output directory before emit.
  },

  // or
  output: {
    clean: {
      keep: 'ignored/dir', // keep these assets under 'dist/ignored/dir'.
    },
  },

  // or
  output: {
    clean: {
      keep: /ignored\/dir/, // keep these assets under 'dist/ignored/dir'.
    },
  },

  // or
  output: {
    clean: {
      keep: (path) => path.includes('ignored/dir'), // keep these assets under 'dist/ignored/dir'.
    },
  },
};
```

## output.compareBeforeEmit

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

Tells Rspack to check if to be emitted file already exists and has the same content before writing to the output file system.

:::warning
Rspack will not write output file when file already exists on disk with the same content.
:::

```js title="rspack.config.mjs"
export default {
  output: {
    compareBeforeEmit: false,
  },
};
```

## output.crossOriginLoading

- **Type:** `false | 'anonymous' | 'use-credentials'`
- **Default:** `false`

The `crossOriginLoading` config allows you to set the [crossorigin attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-crossorigin) for dynamically loaded chunks.

If `target` is `'web'`, Rspack will dynamically create `<script>` and `<link>` tags to load asynchronous JavaScript and CSS resources. Rspack will add the `crossorigin` attribute to the `<script>` and `<link>` tags if the URLs of these resources are on other domains and `crossOriginLoading` is not `false`.

**Optional values**

`crossOriginLoading` has the following optional values:

- `false`: Do not set the [crossorigin attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-crossorigin).
- `'anonymous'`: Set `crossorigin` to `'anonymous'` to enable cross-origin without user credentials.
- `'use-credentials'`: Set `crossorigin` to `'use-credentials'` enable cross-origin with user credentials.

**Example**

For example, set [output.publicPath](#outputpublicpath) to `https://example.com/` and `output.crossOriginLoading` to `'anonymous'`:

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  output: {
    publicPath: 'https://example.com/',
    crossOriginLoading: 'anonymous',
  },
};
```

When Rspack dynamically loads JavaScript resources, it will generate the following HTML:

```html
<script src="https://example.com/foo.js" crossorigin="anonymous"></script>
```

## output.cssChunkFilename

- **Type:** `string | ((pathData: PathData, assetInfo?: AssetInfo) => string)`
- **Default:** Determined by [`output.chunkFilename`](/config/output.md#outputchunkfilename) when it is not a function, otherwise `'[id].css'`.

This option determines the name of non-initial CSS output files on disk. See [`output.filename`](/config/output.md#outputfilename) option for details on the possible values.

For a string `output.chunkFilename`, Rspack replaces its `.js`, `.mjs`, or `.cjs` extension with `.css`, preserving any query string. For a function, the default is `'[id].css'`; the function is not called to derive the CSS filename.

You **must not** specify an absolute path here. However, feel free to include folders separated by `'/'`. This specified path combines with the [`output.path`](#outputpath) value to pinpoint the location on the disk.

## output.cssFilename

- **Type:** `string | ((pathData: PathData, assetInfo?: AssetInfo) => string)`
- **Default:** Derived from [`output.filename`](#outputfilename) when it is a string, otherwise `'[id].css'`.

This option determines the name of CSS output files on disk. See [`output.filename`](/config/output.md#outputfilename) option for details on the possible values.

For a string `output.filename`, Rspack replaces its `.js`, `.mjs`, or `.cjs` extension with `.css`, preserving any query string. If none of these extensions is present, the string is unchanged.

| `output.filename`        | Default `output.cssFilename` |
| ------------------------ | ---------------------------- |
| `'scripts/[name].js'`    | `'scripts/[name].css'`       |
| `'[name].mjs?version=1'` | `'[name].css?version=1'`     |
| A function               | `'[id].css'`                 |

When using a function for JavaScript filenames, configure CSS filenames separately if you need named CSS assets:

```js title="rspack.config.mjs"
export default {
  output: {
    filename: () => 'scripts/[name].js',
    cssFilename: 'styles/[name].css',
  },
};
```

You **must not** specify an absolute path here. However, feel free to include folders separated by `'/'`. This specified path combines with the [`output.path`](#outputpath) value to pinpoint the location on the disk.

## output.devtoolFallbackModuleFilenameTemplate

- **Type:**

```ts
type DevtoolFallbackModuleFilenameTemplate =
  string | ((context: ModuleFilenameTemplateContext) => string);
```

- **Default:** `undefined`

A fallback is used when the template string or function above yields duplicates.

See [`output.devtoolModuleFilenameTemplate`](/config/output.md#outputdevtoolmodulefilenametemplate).

## output.devtoolModuleFilenameTemplate

- **Type:**

```ts
type DevtoolModuleFilenameTemplate =
  string | ((context: ModuleFilenameTemplateContext) => string);
```

- **Default:** `webpack://[namespace]/[resource-path]?[loaders]'`

This option is only used when [`devtool`](/config/devtool.md) uses an option that requires module names.

Customize the names used in each source map's `sources` array. This can be done by passing a template string or function. For example, when using `devtool: 'eval'`.

```js title="rspack.config.mjs"
export default {
  output: {
    devtoolModuleFilenameTemplate:
      'webpack://[namespace]/[resource-path]?[loaders]',
  },
};
```

The following substitutions are available in template strings

| Template                  | Description                                                                                                           |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| \[absolute-resource-path] | The absolute filename                                                                                                 |
| \[relative-resource-path] | Resource path relative to the source map file’s directory, or to the emitted asset’s directory for inline source maps |
| \[all-loaders]            | Automatic and explicit loaders and params up to the name of the first loader                                          |
| \[hash]                   | The hash of the module identifier                                                                                     |
| \[id]                     | The module identifier                                                                                                 |
| \[loaders]                | Explicit loaders and params up to the name of the first loader                                                        |
| \[resource]               | The path used to resolve the file and any query params used on the first loader                                       |
| \[resource-path]          | The path used to resolve the file without any query params                                                            |
| \[namespace]              | The modules namespace. This is usually the library name when building as a library, empty otherwise                   |

When using a function, the same options are available camel-cased via the `info` parameter:

```js title="rspack.config.mjs"
export default {
  output: {
    devtoolModuleFilenameTemplate: (info) => {
      return `webpack:///${info.resourcePath}?${info.loaders}`;
    },
  },
};
```

If multiple modules would result in the same name, [`output.devtoolFallbackModuleFilenameTemplate`](#outputdevtoolfallbackmodulefilenametemplate) is used instead for these modules.

## output.devtoolNamespace

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

This option determines the module's namespace used with the [`output.devtoolModuleFilenameTemplate`](#outputdevtoolmodulefilenametemplate). When not specified, it will default to the value of: [`output.uniqueName`](#outputuniquename). It's used to prevent source file path collisions in sourcemaps when loading multiple libraries built with Rspack.

For example, if you have 2 libraries, with namespaces `library1` and `library2`, which both have a file `./src/index.js` (with potentially different contents), they will expose these files as `webpack://library1/./src/index.js` and `webpack://library2/./src/index.js`.

## output.enabledChunkLoadingTypes

- **Type:** `('jsonp' | 'import-scripts' | 'require' | 'async-node' | string)[]`
- **Default:** Determined by [`output.chunkLoading`](#outputchunkloading), [`output.workerChunkLoading`](#outputworkerchunkloading) and Entry's chunkLoading config.

List of chunk loading types enabled for use by entry points. Will be automatically filled by Rspack. Only needed when using a function as entry option and returning chunkLoading option from there.

```js title="rspack.config.mjs"
export default {
  output: {
    enabledChunkLoadingTypes: ['jsonp', 'require'],
  },
};
```

## output.enabledLibraryTypes

- **Type:** `string[]`
- **Default:** Determined by [output.library](#outputlibrary) and [Entry](/config/entry.md)

List of library types enabled for use by entry points.

```js title="rspack.config.mjs"
export default {
  output: {
    enabledLibraryTypes: ['module'],
  },
};
```

## output.enabledWasmLoadingTypes

- **Type:** `('...' | 'fetch' | 'async-node' | 'universal')[]`
- **Default:** Determined by [`output.wasmLoading`](#outputwasmloading) and [`output.workerWasmLoading`](#outputworkerwasmloading)

List of Wasm loading types enabled for use by entry points.

```js title="rspack.config.mjs"
export default {
  output: {
    enabledWasmLoadingTypes: ['fetch'],
  },
};
```

## output.environment

- **Type:**

```ts
type Environment = {
  /** The environment supports arrow functions ('() => { ... }'). */
  arrowFunction?: boolean;
  /** The environment supports async function and await ('async function () { await ... }'). */
  asyncFunction?: boolean;
  /** The environment supports BigInt as literal (123n). */
  bigIntLiteral?: boolean;
  /** The environment supports const and let for variable declarations. */
  const?: boolean;
  /** The environment supports computed property names in object literals ('{ [expr]: value }'). */
  computedProperty?: boolean;
  /** The environment supports destructuring ('{ a, b } = obj'). */
  destructuring?: boolean;
  /** The environment supports 'document' variable. */
  document?: boolean;
  /** The environment supports an async import() function to import ECMAScript modules. */
  dynamicImport?: boolean;
  /** The environment supports an async import() when creating a worker, only for web targets at the moment. */
  dynamicImportInWorker?: boolean;
  /** The environment supports `import.meta.dirname` and `import.meta.filename`. */
  importMetaDirnameAndFilename?: boolean;
  /** The environment supports 'for of' iteration ('for (const x of array) { ... }'). */
  forOf?: boolean;
  /** The environment supports 'globalThis'. */
  globalThis?: boolean;
  /** The environment supports { fn() {} } */
  methodShorthand?: boolean;
  /** The environment supports ECMAScript Module syntax to import ECMAScript modules (import ... from '...'). */
  module?: boolean;
  /**
   * Determines if the node: prefix is generated for core module imports in environments that support it.
   * This is only applicable to Rspack runtime code.
   * */
  nodePrefixForCoreModules?: boolean;
  /** The environment supports optional chaining ('obj?.a' or 'obj?.()'). */
  optionalChaining?: boolean;
  /** The environment supports logical assignment ('a ||= b'). */
  logicalAssignment?: boolean;
  /** The environment supports template literals. */
  templateLiteral?: boolean;
};
```

`output.environment` specifies which ECMAScript language features and host environment capabilities Rspack is allowed to use when generating its runtime code.

This setting affects only code emitted by Rspack itself, such as runtime helpers. It does not downgrade your application source code.

### Default behavior

By default, `output.environment` is automatically inferred from your [target](/config/target.md) configuration.

Rspack evaluates `target` to determine which features your target environment supports. For example:

- If the target browsers support arrow functions, Rspack will use arrow functions in the runtime to produce more compact output.
- If `target` specifies a particular Node.js version, Rspack will infer the supported syntax from that version’s capabilities.

In general, you do not need to configure this option manually. You would override it only when you want to explicitly enforce or restrict specific features. Manual configuration replaces the inferred values and gives you direct control over the syntax used in the generated runtime.

### Example

Suppose `target` is set to `['web', 'es2018']`. In this case, Rspack will infer that `const` is supported and enable it by default. You can disable it by setting `output.environment.const: false`. Rspack will then emit runtime code that uses `var` declarations instead.

```js title="rspack.config.mjs"
export default {
  target: ['web', 'es2018'],
  output: {
    environment: {
      const: false,
    },
  },
};
```

## output.filename

- **Type:** `string | ((pathData: PathData, assetInfo?: AssetInfo) => string)`
- **Default:** When [`output.module`](#outputmodule) is `true`, it is `'[name].mjs'`, otherwise it is `'[name].js'`.

This option determines the name of each output bundle. The bundle is written to the directory specified by the [`output.path`](#outputpath) option.

For a single [`entry`](/config/entry.md) point, this can be a static name.

```js title="rspack.config.mjs"
export default {
  output: {
    filename: 'bundle.js',
  },
};
```

However, when creating multiple bundles via more than one entry point, code splitting, or various plugins, you should use one of the following substitutions to give each bundle a unique name...

:::info Description of other cases where multiple bundles can be split

Rspack performs code splitting optimizations on user input code, which may include, but are not limited to, code splitting, bundle splitting, or splitting implemented through other plugins. These splitting actions can result in multiple bundles being generated, so the filenames of the bundles need to be generated dynamically.


:::

Use [Entry](/config/entry.md) name:

```js title="rspack.config.mjs"
export default {
  output: {
    filename: '[name].bundle.js',
  },
};
```

Using internal chunk id:

```js title="rspack.config.mjs"
export default {
  output: {
    filename: '[id].bundle.js',
  },
};
```

Using hashes generated from the generated content:

```js title="rspack.config.mjs"
export default {
  output: {
    filename: '[contenthash].bundle.js',
  },
};
```

Combining multiple substitutions:

```js title="rspack.config.mjs"
export default {
  output: {
    filename: '[name].[contenthash].bundle.js',
  },
};
```

:::tip
See [Filename placeholders](/config/filename-placeholders.md) for more information.
:::

Using the function to return the filename:

```js title="rspack.config.mjs"
export default {
  output: {
    filename: (pathData) => {
      return pathData.chunk.name === 'main' ? '[name].js' : '[name]/[name].js';
    },
  },
};
```

Note this option is called filename but you are still allowed to use something like `'js/[name]/bundle.js'` to create a folder structure.

Note this option does not affect output files for on-demand-loaded chunks. It only affects output files that are initially loaded. For on-demand-loaded chunk files, the [`output.chunkFilename`](#outputchunkfilename) option is used. Files created by loaders also aren't affected. In this case, you would have to try the specific loader's available options.

## output.globalObject

- **Type:** `string`
- **Default:** `'self'`

When targeting a library, especially when `library.type` is `'umd'`, this option indicates what global object will be used to mount the library. To make UMD build available on both browsers and Node.js, set `output.globalObject` option to `'this'`. Defaults to `self` for Web-like targets.

The return value of your entry point will be assigned to the global object using the value of `output.library.name`. Depending on the value of the `type` option, the global object could change respectively, e.g., `self`, `global`, or `globalThis`.

For example:

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'myLib',
      type: 'umd',
    },
    filename: 'myLib.js',
    globalObject: 'this',
  },
};
```

## output.hashDigest

- **Type:** `string`
- **Default:** `'hex'`

The encoding to use when generating the hash. Using `'base64'` for filenames might be problematic since it has the character `/` in its alphabet. Likewise `'latin1'` could contain any character.

## output.hashDigestLength

- **Type:** `number`
- **Default:** `16`

The prefix length of the hash digest to use, see [Hash length](/config/filename-placeholders.md#hash-length) for more details.

```js title="rspack.config.mjs"
export default {
  output: {
    hashDigestLength: 8,
  },
};
```

## output.hashFunction

- **Type:** `'md4' | 'xxhash64' | 'sha256'`
- **Default:** `'xxhash64'`

The hashing algorithm to use.

```js title="rspack.config.mjs"
export default {
  output: {
    hashFunction: 'xxhash64',
  },
};
```

## output.hashSalt

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

An optional salt to update the hash.

## output.hotUpdateChunkFilename

- **Type:** `string`
- **Default:** When [`output.module`](#outputmodule) is `true`, it is `'[id].[fullhash].hot-update.mjs'`, otherwise it is `'[id].[fullhash].hot-update.js'`.

Customize the filenames of hot update chunks. See [`output.filename`](#outputfilename) option for details on the possible values.

The only placeholders allowed here are `[id]` and `[fullhash]`. For example:

```js title="rspack.config.mjs"
export default {
  output: {
    hotUpdateChunkFilename: '[id].[fullhash].hot-update.js',
  },
};
```

:::tip
Typically you don't need to change `output.hotUpdateChunkFilename`.
:::

## output.hotUpdateGlobal

- **Type:** `string`
- **Default:** `"rspackHotUpdate" + output.uniqueName`

Only used when [`target`](/config/target.md) is set to `'web'`, which uses JSONP for loading hot updates.

A JSONP function is used to asynchronously load hot-update chunks.

For details see [`output.chunkLoadingGlobal`](#outputchunkloadingglobal).

## output.hotUpdateMainFilename

- **Type:** `string`
- **Default:** When [`output.module`](#outputmodule) is `true`, it is `'[runtime].[fullhash].hot-update.json.mjs'`, otherwise it is `'[runtime].[fullhash].hot-update.json'`.

Customize the main hot update filename. `[fullhash]` and `[runtime]` are available as placeholder.

:::tip
Typically you don't need to change `output.hotUpdateMainFilename`.
:::

## output.iife

- **Type:** `boolean`
- **Default:** `false` when [`output.module`](#outputmodule) is `true`, otherwise `true`.

Tells Rspack to add [IIFE](https://developer.mozilla.org/en-US/docs/Glossary/IIFE) wrapper around emitted code.

```js title="rspack.config.mjs"
export default {
  output: {
    iife: true,
  },
};
```

## output.importFunctionName

- **Type:** `string`
- **Default:** `'import'`

The name of the native `import()` function. Can be used for polyfilling, e.g. with [`dynamic-import-polyfill`](https://github.com/GoogleChromeLabs/dynamic-import-polyfill).

```js title="rspack.config.mjs"
export default {
  output: {
    importFunctionName: '__import__',
  },
};
```

## output.importMetaName

- **Type:** `string`
- **Default:** `'import.meta'`

The name of the native `import.meta` object (can be exchanged for a polyfill).

```js title="rspack.config.mjs"
export default {
  output: {
    importMetaName: 'pseudoImport.meta',
  },
};
```

## output.library

Output a library exposing the exports of your entry point.

- **Type:** `string | string[] | object`

Let's take a look at an example.

```js title="rspack.config.mjs"
export default {
  entry: './src/index.js',
  output: {
    library: 'MyLibrary',
  },
};
```

Say you have exported a function in your `src/index.js` entry:

```js
export function hello(name) {
  console.log(`hello ${name}`);
}
```

Now the variable `MyLibrary` will be bound with the exports of your entry file, and here's how to consume the Rspack bundled library:

```html
<script src="https://example.org/path/to/my-library.js"></script>
<script>
  MyLibrary.hello('rspack');
</script>
```

In the above example, we're passing a single entry file to `entry`, however, Rspack can accept [many kinds of entry point](/config/entry.md), e.g., an `array`, or an `object`.

1. If you provide an `array` as the `entry` point, only the last one in the array will be exposed.

   ```js title="rspack.config.mjs"
   export default {
     entry: ['./src/a.js', './src/b.js'], // only exports in b.js will be exposed
     output: {
       library: 'MyLibrary',
     },
   };
   ```

2. If an `object` is provided as the `entry` point, all entries can be exposed using the `array` syntax of `library`:

   ```js title="rspack.config.mjs"
   export default {
     entry: {
       a: './src/a.js',
       b: './src/b.js',
     },
     output: {
       filename: '[name].js',
       library: ['MyLibrary', '[name]'], // name is a placeholder here
     },
   };
   ```

   Assuming that both `a.js` and `b.js` export a function `hello`, here's how to consume the libraries:

   ```html
   <script src="https://example.org/path/to/a.js"></script>
   <script src="https://example.org/path/to/b.js"></script>
   <script>
     MyLibrary.a.hello('rspack');
     MyLibrary.b.hello('rspack');
   </script>
   ```

### output.library.amdContainer

- **Type:** `string`

Use a container(defined in global space) for calling `define`/`require` functions in an AMD module.

:::warning
Note that the value of `amdContainer` **must be** set as a global variable.
:::

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      amdContainer: 'window["clientContainer"]',
      type: 'amd', // or 'amd-require'
    },
  },
};
```

Which will result in the following bundle:

```js
window['clientContainer'].define(/*define args*/); // or 'amd-require' window['clientContainer'].require(/*require args*/);
```

### output.library.name

Specify a name for the library.

- **Type:** `string | string[] | {amd?: string, commonjs?: string, root?: string | string[]}`

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
    },
  },
};
```

### output.library.type

Configure how the library will be exposed.

- **Type:** `string`

  Types included by default are `'var'`, `'module'`, `'modern-module'`, `'system'`, `'assign'`, `'assign-properties'`, `'this'`, `'window'`, `'self'`, `'global'`, `'commonjs'`, `'commonjs2'`, `'commonjs-module'`, `'commonjs-static'`, `'amd'`, `'amd-require'`, `'umd'`, `'umd2'`, `'jsonp'`, but others might be added by plugins.

For the following examples, we'll use `_entry_return_` to indicate the values returned by the entry point.

#### Expose a variable

These options assign the return value of the entry point (e.g. whatever the entry point exported) to the name provided by [`output.library.name`](#outputlibraryname) at whatever scope the bundle was included at.

##### type: 'var'

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'var',
    },
  },
};
```

When your library is loaded, the **return value of your entry point** will be assigned to a variable:

```js
var MyLibrary = _entry_return_;

// In a separate script with `MyLibrary` loaded…
MyLibrary.doSomething();
```

##### type: 'assign'

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'assign',
    },
  },
};
```

This will generate an implied global which has the potential to reassign an existing value (use with caution):

```js
MyLibrary = _entry_return_;
```

Be aware that if `MyLibrary` isn't defined earlier your library will be set in global scope.

##### type: 'assign-properties'

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'assign-properties',
    },
  },
};
```

Similar to [`type: 'assign'`](#type-assign) but a safer option as it will reuse `MyLibrary` if it already exists:

```js
// only create MyLibrary if it doesn't exist
MyLibrary = typeof MyLibrary === 'undefined' ? {} : MyLibrary;
// then copy the return value to MyLibrary
// similarly to what Object.assign does

// for instance, you export a `hello` function in your entry as follow
export function hello(name) {
  console.log(`Hello ${name}`);
}

// In another script with MyLibrary loaded
// you can run `hello` function like so
MyLibrary.hello('World');
```

#### Expose via object assignment

These options assign the return value of the entry point (e.g. whatever the entry point exported) to a specific object under the name defined by [`output.library.name`](#outputlibraryname).

##### type: 'this'

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'this',
    },
  },
};
```

The **return value of your entry point** will be assigned to `this` under the property named by `output.library.name`. The meaning of `this` is up to you:

```js
this['MyLibrary'] = _entry_return_;

// In a separate script
this.MyLibrary.doSomething();
MyLibrary.doSomething(); // if `this` is window
```

##### type: 'window'

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'window',
    },
  },
};
```

The **return value of your entry point** will be assigned to the `window` object using the `output.library.name` value.

```js
window['MyLibrary'] = _entry_return_;

window.MyLibrary.doSomething();
```

##### type: 'global'

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'global',
    },
  },
};
```

The **return value of your entry point** will be assigned to the global object using the `output.library.name` value. Depending on the [`target`](/config/target.md) value, the global object could change respectively, e.g., `self`, `global` or `globalThis`.

```js
global['MyLibrary'] = _entry_return_;

global.MyLibrary.doSomething();
```

##### type: 'commonjs'

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'commonjs',
    },
  },
};
```

The **return value of your entry point** will be assigned to the `exports` object using the `output.library.name` value. As the name implies, this is used in CommonJS environments.

```js
exports['MyLibrary'] = _entry_return_;

require('MyLibrary').doSomething();
```

:::warning
Note that not setting a `output.library.name` will cause all properties returned by the entry point to be assigned to the given object; there are no checks against existing property names.
:::

#### Module definition systems

These options will result in a bundle that comes with a complete header to ensure compatibility with various module systems. The `output.library.name` option will take on a different meaning under the following `output.library.type` options.

##### type: 'module'

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      // do not specify a `name` here
      type: 'module',
    },
  },
};
```

Output ES modules.

This is the more compatibility-oriented ESM library path: Rspack still uses the regular chunk / runtime rendering pipeline and then converts the entry exports into `export` statements. It fits simpler ESM library output, or cases where you mainly want webpack-style `module` semantics.

##### type: 'modern-module'

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      // do not specify a `name` here
      type: 'modern-module',
    },
  },
};
```

This configuration enables Rspack's dedicated rendering pipeline for ESM libraries. It emits direct `import` / `export` statements and supports library-oriented tree shaking, scope hoisting, code splitting, and [`output.library.preserveModules`](#outputlibrarypreservemodules).

:::tip `module` vs `modern-module`

- `module` stays on the regular chunk / runtime rendering pipeline and is closer to webpack-compatible ESM semantics.
- `modern-module` is handled by a dedicated ESM library plugin that owns chunk rendering, linking, scope hoisting, and splitChunks behavior, making it a better fit for publishable tree-shakable, code-split ESM libraries.
- `modern-module` currently exists as a separate type to fill the ESM library capability gap; once it is mature enough, the long-term direction is to converge it with `module` into a single `library.type`.
- `preserveModules` is only available with `modern-module`.
- When `output.library` is configured and `output.module = true`, Rspack currently defaults `output.library.type` to `modern-module` if you don't specify one explicitly.
- Do not mix `modern-module` with other library types in the same compilation, because it also changes chunk loading, chunk rendering, and scope-hoisting behavior.

:::

##### type: 'commonjs2'

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      // note there's no `name` here
      type: 'commonjs2',
    },
  },
};
```

The **return value of your entry point** will be assigned to the `module.exports`. As the name implies, this is used in Node.js (CommonJS) environments:

```js
module.exports = _entry_return_;

require('MyLibrary').doSomething();
```

If we specify `output.library.name` with `type: commmonjs2`, the return value of your entry point will be assigned to the `module.exports.[output.library.name]`.

:::tip
Wondering the difference between CommonJS and CommonJS2 is? While they are similar, there are some subtle differences between them that are not usually relevant in the context of Rspack. (For further details, please [read this issue](https://github.com/webpack/webpack/issues/1114).)
:::

##### type: 'commonjs-static'

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      // note there's no `name` here
      type: 'commonjs-static',
    },
  },
};
```

Individual exports will be set as properties on `module.exports`. The "static" in the name refers to the output being statically analysable, and thus named exports are importable into ESM via Node.js:

Input:

```js
export function doSomething() {}
```

Output:

```js
function doSomething() {}

exports.doSomething = __webpack_exports__.doSomething;
```

Consumption (CommonJS):

```js
const { doSomething } = require('./output.cjs'); // doSomething => [Function: doSomething]
```

Consumption (ESM):

```js
import { doSomething } from './output.cjs'; // doSomething => [Function: doSomething]
```

:::tip
This is useful when source code is written in ESM and the output should be compatible with both CJS and ESM. For further details, please [read this issue](https://github.com/webpack/webpack/issues/14998) or [this article](https://dev.to/jakobjingleheimer/configuring-commonjs-es-modules-for-nodejs-12ed) (specifically, [this section](https://dev.to/jakobjingleheimer/configuring-commonjs-es-modules-for-nodejs-12ed#publish-only-a-cjs-distribution-with-property-exports)).
:::

:::tip How To Choose A CommonJS `library.type`

| Type              | Writes To           | Better Fit                                                                              |
| ----------------- | ------------------- | --------------------------------------------------------------------------------------- |
| `commonjs`        | `exports[...]`      | Compatibility with legacy configs that intentionally write to the `exports` object      |
| `commonjs2`       | `module.exports`    | General Node.js / CJS library output; the preferred choice for most new configs         |
| `commonjs-module` | `module.exports`    | Currently equivalent to `commonjs2`, mainly for historical webpack config compatibility |
| `commonjs-static` | `exports.foo = ...` | When you want Node.js ESM to be able to perform named imports from the CJS output       |

Rspack keeps these spellings primarily for webpack ecosystem compatibility and does not currently deprecate them at the config level. For new projects, prefer `commonjs2` or `commonjs-static` in most cases; reach for `commonjs` / `commonjs-module` mainly when migrating existing configs or when you explicitly need `exports` assignment semantics.

:::

##### type: 'amd'

This will expose your library as an AMD module.

AMD modules require that the entry chunk (e.g. the first script loaded by the `<script>` tag) be defined with specific properties, such as to `define` and `require` which is typically provided by RequireJS or any compatible loaders (such as almond). Otherwise, loading the resulting AMD bundle directly will result in an error like `define is not defined`.

With the following configuration:

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'amd',
    },
  },
};
```

The generated output will be defined with the name `"MyLibrary"`, i.e.:

```js
define('MyLibrary', [], function () {
  return _entry_return_;
});
```

The bundle can be included as part of a script tag, and the bundle can be invoked like so:

```js
require(['MyLibrary'], function (MyLibrary) {
  // Do something with the library...
});
```

If `output.library.name` is undefined, the following is generated instead.

```js
define(function () {
  return _entry_return_;
});
```

This bundle will not work as expected, or not work at all (in the case of the almond loader) if loaded directly with a `<script>` tag. It will only work through a RequireJS compatible asynchronous module loader through the actual path to that file, so in this case, the `output.path` and `output.filename` may become important for this particular setup if these are exposed directly on the server.

##### type: 'amd-require'

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'amd-require',
    },
  },
};
```

This packages your output with an immediately executed AMD `require(dependencies, factory)` wrapper.

The `'amd-require'` type allows for the use of AMD dependencies without needing a separate later invocation. As with the `'amd'` type, this depends on the appropriate [`require` function](https://github.com/amdjs/amdjs-api/blob/master/require.md) being available in the environment in which the Rspack output is loaded.

With this type, the library name can't be used.

##### type: 'umd'

This exposes your library under all the module definitions, allowing it to work with CommonJS, AMD, and as global variable. Take a look at the [UMD Repository](https://github.com/umdjs/umd) to learn more.

In this case, you need the `library.name` property to name your module:

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'umd',
    },
  },
};
```

And finally the output is:

```js
(function webpackUniversalModuleDefinition(root, factory) {
  if (typeof exports === 'object' && typeof module === 'object')
    module.exports = factory();
  else if (typeof define === 'function' && define.amd) define([], factory);
  else if (typeof exports === 'object') exports['MyLibrary'] = factory();
  else root['MyLibrary'] = factory();
})(global, function () {
  return _entry_return_;
});
```

Note that omitting `library.name` will result in the assignment of all properties returned by the entry point be assigned directly to the root object, as documented under the [object assignment section](#expose-via-object-assignment). Example:

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      type: 'umd',
    },
  },
};
```

The output will be:

```js
(function webpackUniversalModuleDefinition(root, factory) {
  if (typeof exports === 'object' && typeof module === 'object')
    module.exports = factory();
  else if (typeof define === 'function' && define.amd) define([], factory);
  else {
    var a = factory();
    for (var i in a) (typeof exports === 'object' ? exports : root)[i] = a[i];
  }
})(global, function () {
  return _entry_return_;
});
```

You may specify an object for `library.name` for differing names per targets:

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: {
        root: 'MyLibrary',
        amd: 'my-library',
        commonjs: 'my-common-library',
      },
      type: 'umd',
    },
  },
};
```

##### type: 'system'

This will expose your library as a [`System.register`](https://github.com/systemjs/systemjs/blob/master/docs/system-register.md) module.

System modules require that a global variable `System` is present in the browser when the Rspack bundle is executed. Compiling to `System.register` format allows you to `System.import('/bundle.js')` without additional configuration and has your Rspack bundle loaded into the System module registry.

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      type: 'system',
    },
  },
};
```

Output:

```js
System.register([], function (__WEBPACK_DYNAMIC_EXPORT__, __system_context__) {
  return {
    execute: function () {
      // ...
    },
  };
});
```

By adding `output.library.name` to configuration in addition to having `output.library.type` set to `system`, the output bundle will have the library name as an argument to `System.register`:

```js
System.register(
  'MyLibrary',
  [],
  function (__WEBPACK_DYNAMIC_EXPORT__, __system_context__) {
    return {
      execute: function () {
        // ...
      },
    };
  },
);
```

#### Other types

**type: 'jsonp'**

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'jsonp',
    },
  },
};
```

This will wrap the return value of your entry point into a jsonp wrapper.

```js
MyLibrary(_entry_return_);
```

The dependencies for your library will be defined by the [`externals`](/config/externals.md) config.

### output.library.export

Specify which export should be exposed as a library.

- **Type:** `string | string[]`
- **Default:** `undefined`

It is `undefined` by default, which will export the whole (namespace) object. The examples below demonstrate the effect of this configuration when using [`output.library.type: 'var'`](#type-var).

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'var',
      export: 'default',
    },
  },
};
```

The default export of your entry point will be assigned to the library name:

```js
// If your library has a default export
var MyLibrary = _entry_return_.default;
```

You can pass an array to `output.library.export` as well, it will be interpreted as a path to a module to be assigned to the library name:

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'var',
      export: ['default', 'subModule'],
    },
  },
};
```

And here's the library code:

```js
var MyLibrary = _entry_return_.default.subModule;
```

### output.library.auxiliaryComment

Add a comment in the UMD wrapper.

- **Type:** `string | { amd?: string, commonjs?: string, commonjs2?: string, root?: string }`
- **Default:** `undefined`

To insert the same comment for each `umd` type, set `auxiliaryComment` to a string:

```js title="rspack.config.mjs"
export default {
  mode: 'development',
  output: {
    library: {
      name: 'MyLibrary',
      type: 'umd',
      auxiliaryComment: 'Test Comment',
    },
  },
};
```

which will yield the following:

```js
(function webpackUniversalModuleDefinition(root, factory) {
  //Test Comment
  if (typeof exports === 'object' && typeof module === 'object')
    module.exports = factory();
  //Test Comment
  else if (typeof define === 'function' && define.amd) define([], factory);
  //Test Comment
  else if (typeof exports === 'object') exports['MyLibrary'] = factory();
  //Test Comment
  else root['MyLibrary'] = factory();
})(self, function () {
  return _entry_return_;
});
```

For fine-grained control, pass an object:

```js title="rspack.config.mjs"
export default {
  mode: 'development',
  output: {
    library: {
      name: 'MyLibrary',
      type: 'umd',
      auxiliaryComment: {
        root: 'Root Comment',
        commonjs: 'CommonJS Comment',
        commonjs2: 'CommonJS2 Comment',
        amd: 'AMD Comment',
      },
    },
  },
};
```

### output.library.umdNamedDefine

- **Type:** `boolean`
- **Default:** `undefined`

When using `output.library.type: "umd"`, setting `output.library.umdNamedDefine` to `true` will name the AMD module of the UMD build. Otherwise, an anonymous `define` is used.

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      name: 'MyLibrary',
      type: 'umd',
      umdNamedDefine: true,
    },
  },
};
```

The AMD module will be:

```js
define('MyLibrary', [], factory);
```

### output.library.preserveModules

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

:::info
Only available when `library.type` is set to `modern-module`.
:::

When enabled, Rspack will preserve the original directory structure of modules within the specified directory. Each module will be emitted as a separate file, maintaining the same relative path as the source.

`preserveModules` is a special form of bundling — it can be thought of as **bundle + splitChunks where each module gets its own chunk**. Unlike a bundleless tool, Rspack still applies its full bundling pipeline (tree shaking, scope hoisting, minification, etc.), but splits the output so that each module in the specified directory becomes its own output file.

:::warning
**Barrel files may not be emitted or exposed as you expect.** Since `preserveModules` is still a form of bundling, Rspack only emits modules that are reachable from the configured entries. Non-entry barrel files (for example, an `index.ts` that re-exports from other modules) can still be emitted with their re-exports if they are part of the module graph, but only the configured entry exports are exposed through the main library entry. Unused barrel re-exports may be tree-shaken, and a barrel file may not be emitted at all if nothing references it. If you need to expose exports from a barrel file via your library entry, configure it as an entry point.
:::

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  output: {
    library: {
      type: 'modern-module',
      preserveModules: path.resolve('./src'),
    },
  },
};
```

## output.module

- **Type:** `boolean`
- **Default:** `false`

Output JavaScript files as module type.

When enabled, [`output.iife`](#outputiife) defaults to `false` and [`output.scriptType`](#outputscripttype) defaults to `'module'`. Explicit values for these options take precedence over the defaults.

The built-in [SwcJsMinimizerRspackPlugin](/plugins/swc-js-minimizer-rspack-plugin.md#minimizeroptions) detects ESM assets from their metadata unless `minimizerOptions.module` is explicitly configured.

If you set [`output.library.type`](#outputlibrarytype) to 'module' or 'modern-module', Rspack will set `output.module` to `true` for you automatically.

```js title="rspack.config.mjs"
export default {
  output: {
    module: true,
  },
};
```

## output.path

- **Type:** `string`
- **Default:** `path.resolve(process.cwd(), 'dist')`

The output directory as an **absolute** path.


**ESM**

```js title="rspack.config.mjs"
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

export default {
  output: {
    path: path.resolve(__dirname, 'dist/assets'),
  },
};
```


**CJS**

```js title="rspack.config.cjs"
const path = require('node:path');

module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist/assets'),
  },
};
```


Note that `[fullhash]` in this parameter will be replaced with a hash of the compilation.

:::warning

- The path must not contain an exclamation mark (`!`) as it is reserved by Rspack for loader syntax.
- Relative paths are resolved against `context`.

:::

## output.pathinfo

- **Type:** `boolean | 'verbose'`
- **Default:** `false`

Controls whether Rspack adds module-related comments to the generated bundle. These comments are useful for debugging, inspecting build output, and understanding tree-shaking behavior.

- `true`: Enables basic comments, including module path information.
- `false`: Disables all comments, which is the default behavior.
- `'verbose'`: Outputs detailed comments, such as module exports, runtime details, tree-shaking information, and bailout reasons. This mode is helpful when diagnosing build issues or performing in-depth bundle analysis.

For example, enabling `pathinfo`:

```js title="rspack.config.mjs"
export default {
  output: {
    pathinfo: true,
  },
};
```

The generated bundle will contain comments like:

```js
/*!**********************!*\
  !*** ./src/index.js ***!
  \**********************/
```

:::warning
`pathinfo` is primarily intended for development and debugging. These comments increase bundle size and may expose details about your source structure. Avoid using it in production.
:::

## output.publicPath

- **Type:** `'auto' | string | ((pathData: PathData, assetInfo?: AssetInfo) => string)`
- **Default:** `'auto'` when [target](/config/target.md) is `'web'` or `'webworker'`, `undefined` otherwise

Set the base URL path prefix for bundled static assets (such as JS, CSS, images, etc.).

```js title="rspack.config.mjs"
export default {
  output: {
    publicPath: '/assets/',
  },
};
```

See [Asset base path](/guide/features/asset-base-path.md) for more details.

## output.scriptType

- **Type:** `false | 'text/javascript' | 'module'`
- **Default:** `false`

This option allows loading asynchronous chunks with a custom script type, such as `<script type="module" ...>`.

:::tip
If [`output.module`](#outputmodule) is set to `true`, `output.scriptType` will default to `'module'` instead of `false`.
:::

```js title="rspack.config.mjs"
export default {
  output: {
    scriptType: 'module',
  },
};
```

## output.sourceMapFilename

- **Type:** `string`
- **Default:** `'[file].map[query]'`

Configure how source maps are named. Only takes effect when [`devtool`](/config/devtool.md) is set to `'source-map'`, which writes an output file.

The `[name]`, `[id]`, `[fullhash]` and `[chunkhash]` substitutions from [`output.filename`](#outputfilename) can be used. In addition to those, you can use substitutions listed under Filename-level in [Filename placeholders](/config/filename-placeholders.md).

## output.strictModuleErrorHandling

- **Type:** `boolean`
- **Default:** `false`

Handle error in module loading as per ECMAScript Modules spec at a performance cost.

```js title="rspack.config.mjs"
export default {
  output: {
    strictModuleErrorHandling: true,
  },
};
```

## output.strictModuleExceptionHandling

- **Types:** boolean

Tell Rspack to remove a module from the module instance cache (require.cache) if it throws an exception when it is required.

## output.trustedTypes

- **Type:** `true | string | object`
- **Default:** `undefined`

Controls [Trusted Types](https://web.dev/trusted-types) compatibility. When enabled, Rspack will detect Trusted Types support and, if they are supported, use Trusted Types policies to create script URLs it loads dynamically. Use when the application runs under a [`require-trusted-types-for`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/require-trusted-types-for) Content Security Policy directive.

It is disabled by default (no compatibility, script URLs are strings). Set it to `true` to enable Trusted Types with a policy name derived from [`output.uniqueName`](#outputuniquename).

```js title="rspack.config.mjs"
export default {
  output: {
    trustedTypes: true,
  },
};
```

### output.trustedTypes.policyName

- **Type:** `string`
- **Default:** Derived from [`output.uniqueName`](#outputuniquename)

The name of the Trusted Types policy created by Rspack to serve bundle chunks. Use this option when the policy name must match a CSP `trusted-types` allowlist.

If `policyName` is omitted, Rspack derives it from [`output.uniqueName`](#outputuniquename), replacing unsupported characters with `_`. If the derived name is empty, it falls back to `'rspack'`. The string shorthand `trustedTypes: 'my-policy'` is equivalent to setting `trustedTypes.policyName`.

```js title="rspack.config.mjs"
export default {
  output: {
    trustedTypes: {
      policyName: 'my-application#rspack',
    },
  },
};
```

### output.trustedTypes.onPolicyCreationFailure

- **Type:** `"stop" | "continue"`
- **Default:** `"stop"`

Determine whether to proceed with loading in anticipation that [`require-trusted-types-for 'script'`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/require-trusted-types-for) has not been enforced or to immediately fail when the call to `trustedTypes.createPolicy(...)` fails due to the policy name being absent from the CSP `trusted-types` list or being a duplicate.

```js title="rspack.config.mjs"
export default {
  output: {
    trustedTypes: {
      policyName: 'my-application#rspack',
      onPolicyCreationFailure: 'continue',
    },
  },
};
```

## output.uniqueName

- **Type:** `string`
- **Default:** Derived in the following priority order:
  1. The `name` of [`output.library`](#outputlibrary)
  2. The `name` field in `package.json` under the `context` directory
  3. `''` (empty string)

This option is used to identify a unique name for the current build. It mainly helps prevent runtime code conflicts when multiple Rspack applications run in the same global environment.

`output.uniqueName` affects the default values of the following options:

- [output.chunkLoadingGlobal](#outputchunkloadingglobal)
- [output.hotUpdateGlobal](#outputhotupdateglobal)
- [output.devtoolNamespace](#outputdevtoolnamespace)
- [output.trustedTypes.policyName](#outputtrustedtypespolicyname)

To override the default value:

```js title="rspack.config.mjs"
export default {
  output: {
    uniqueName: 'my-package-xyz',
  },
};
```

## output.wasmLoading

- **Type:** `false | 'fetch' | 'async-node' | 'universal'`
- **Default:** `'fetch'`

Option to set the method of loading WebAssembly Modules. Supported methods are `'fetch'` (web/webworker), `'async-node'` (Node.js), and `'universal'`.

The default value can be affected by different [`target`](/config/target.md):

- Defaults to `'fetch'` if [`target`](/config/target.md) is set to `'web'`, `'webworker'`, `'electron-renderer'` or `'node-webkit'`.
- Defaults to `'async-node'` if [`target`](/config/target.md) is set to `'node'`, `'async-node'`, `'electron-main'` or `'electron-preload'`.

```js title="rspack.config.mjs"
export default {
  output: {
    wasmLoading: 'fetch',
  },
};
```

## output.wasmStreamingFallback

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

Controls whether the generated WebAssembly loading runtime falls back to a non-streaming API when `WebAssembly.compileStreaming` or `WebAssembly.instantiateStreaming` rejects because the response does not use the `application/wasm` MIME type.

Set this option to `false` to omit the fallback runtime code when your server always serves WebAssembly files with the correct MIME type.

```js title="rspack.config.mjs"
export default {
  output: {
    wasmStreamingFallback: false,
  },
};
```

## output.webassemblyModuleFilename

- **Type:** `string`
- **Default:** `'[hash].module.wasm'`

Specifies the filename of WebAssembly modules. It should be provided as a relative path within the `output.path` directory

```js title="rspack.config.mjs"
export default {
  output: {
    webassemblyModuleFilename: '[contenthash:8].wasm',
  },
};
```

:::tip
See [Filename placeholders](/config/filename-placeholders.md) for more information.
:::

## output.workerChunkLoading

- **Type:** `false | 'jsonp' | 'import-scripts' | 'require' | 'async-node' | 'import' | string`
- **Default:** `false`

The new option `workerChunkLoading` controls the chunk loading of workers.

:::tip
The default value of this option depends on the [`target`](/config/target.md) setting. For more details, search for `"workerChunkLoading"` [in the Rspack defaults](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack/src/config/defaults.ts).
:::

```js title="rspack.config.mjs"
export default {
  output: {
    workerChunkLoading: false,
  },
};
```

## output.workerPublicPath

- **Type:** `string`
- **Default:** `""`

Set a public path for Worker, defaults to value of [output.publicPath](#outputpublicpath). Only use this option if your worker scripts are located in a different path from your other scripts.

```js title="rspack.config.mjs"
export default {
  output: {
    workerPublicPath: '/workerPublicPath2/',
  },
};
```

## output.workerWasmLoading

- **Type:** `false | 'fetch' | 'async-node' | 'universal'`
- **Default:** `false`

Option to set the method of loading WebAssembly Modules in workers, defaults to the value of [output.wasmLoading](#outputwasmloading).

```js title="rspack.config.mjs"
export default {
  output: {
    workerWasmLoading: 'fetch',
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/output/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/performance.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Performance

`performance` configures Rspack's performance hint mechanism, helping you identify oversized outputs during the build.

It compares asset sizes and entrypoint total sizes against thresholds to decide whether hints should be emitted, and `hints` controls the hint level (`warning` / `error` / disabled).

You can define budget thresholds with `maxAssetSize` and `maxEntrypointSize`, and use `assetFilter` to exclude files that should not be counted, so hints better match your real performance goals.

## performance


- Type: `false | object`


Set `performance` to `false` to disable the performance hints:

```js title="rspack.config.mjs"
export default {
  performance: false,
};
```

## performance.assetFilter


- Type: `(assetFilename: string) => boolean`


Used to filter which assets are included in performance hint calculations. Files returning `true` are included, and files returning `false` are ignored.

Ignore CSS files when calculating performance hints:

```js title="rspack.config.mjs"
export default {
  performance: {
    assetFilter: (assetFilename) => !assetFilename.endsWith('.css'),
  },
};
```

## performance.hints


- Type: `false | 'error' | 'warning'`
- Default:[production mode](/config/mode#production) is`warning`, [development mode](/config/mode#development) is`false`


Controls whether performance hints are enabled and which level to use:

- `false`: Disable performance hints
- `'warning'`: Emit hints as warnings
- `'error'`: Emit hints as errors, which fails the build

Treat performance hints as build errors:

```js title="rspack.config.mjs"
export default {
  performance: {
    hints: process.env.NODE_ENV === 'production' ? 'error' : false,
  },
};
```

## performance.maxAssetSize

- **Type:**: `number`
- **Default:**: `307200` (`300 KiB`)

Sets the size threshold for a single asset (in bytes). Rspack emits a performance hint when an asset exceeds this value.

Lower the single asset size limit to catch oversized files earlier:

```js title="rspack.config.mjs"
export default {
  performance: {
    maxAssetSize: 100000,
  },
};
```

## performance.maxEntrypointSize

- **Type:**: `number`
- **Default:**: `512000` (`500 KiB`)

Sets the total size threshold for an entrypoint (in bytes). Entrypoint total size means the total size needed for the initial load of that entry. Rspack emits a performance hint when the entrypoint total size exceeds this value.

For example, set the entrypoint size threshold to 500 KB:

```js title="rspack.config.mjs"
export default {
  performance: {
    maxEntrypointSize: 500000,
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/performance/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/plugins.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Plugins

- **Type:**

```ts
type Falsy = false | '' | 0 | null | undefined;

type Plugin =
  | RspackPluginInstance
  | RspackPluginFunction
  | WebpackPluginInstance
  | WebpackPluginFunction
  | Falsy;

type Plugins = Plugin[];
```

- **Default:** `[]`

The `plugins` option is used to register a set of Rspack or webpack plugins to customize the build process.

Please refer to [Plugins page](/guide/features/plugin.md) for more information on using plugins in Rspack.

## Built-in plugins

Rspack comes with a variety built-in plugins available under `rspack.PluginName`.

For example, [`DefinePlugin`](/plugins/define-plugin.md) allows you to replaces variables in your code with other values or expressions at compile time. You can access it via `rspack.DefinePlugin` and create a plugin instance with `new`:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.DefinePlugin({
      // pass plugin options
    }),
  ],
};
```

## webpack plugins

Rspack strives to maintain compatibility with the webpack plugin ecosystem to leverage the excellent features that have been accumulated and validated by the community. Please refer to [Community plugin compatibility](/plugins/community-plugin-compatibility.md) to access a list of webpack plugins that have passed our compatibility tests:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';
import HtmlWebpackPlugin from 'html-webpack-plugin';

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

## Disable plugins

Rspack ignores `false`, `''`, `0`, `null` and `undefined` values in the `plugins` array, which allows you to easily disable a plugin.

For example, enable [HotModuleReplacementPlugin](/plugins/hot-module-replacement-plugin.md) only in the development environment:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

const isDev = process.env.NODE_ENV === 'development';

export default {
  plugins: [isDev && new rspack.HotModuleReplacementPlugin()],
};
```



---
url: /config/resolve.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Resolve

Used to configure the Rspack module resolution logic.

- **Type:** `Object`

## resolve.alias

- **Type:**

```ts
type ResolveAlias = false | Record<string, false | string | (false | string)[]>;
```

- **Default:** `{}`

Use `resolve.alias` to redirect module requests to other paths:

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  resolve: {
    alias: {
      '@': path.resolve(import.meta.dirname, './src'),
    },
  },
};
```

With this configuration, `import '@/a'` will attempt to resolve `<root>/src/a`.

### Exact matching

Add `$` to the end of an alias key to match only the complete module request. The `$` is a special `resolve.alias` marker and is not part of the module request:

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  resolve: {
    alias: {
      abc$: path.resolve(import.meta.dirname, './src/abc'),
    },
  },
};
```

With this configuration:

- `import 'abc'` will attempt to resolve `<root>/src/abc`.
- `import 'abc/file.js'` will not match the alias and will continue through normal module resolution, which typically attempts to resolve `node_modules/abc/file.js`.

Without the `$`, an `abc` alias would also match subpath requests such as `import 'abc/file.js'`.

### Impact on package resolution

Using `resolve.alias` to redirect a package request such as `import 'lib'` to a file system path within a monorepo or `node_modules` changes how Rspack resolves that request:

- **Without an alias**: `lib` is treated as a package request. Rspack reads the package's `package.json` and applies package resolution rules such as [`exports`](https://nodejs.org/api/packages.html#exports) to select an entry point or subpath.
- **With an alias**: Rspack first replaces `lib` with the configured file system path. For example, after mapping `lib` to `./node_modules/lib`, Rspack resolves the replacement as a regular path, so the `exports` mappings for the package name `lib` no longer apply.

This behavior follows the semantics of the `exports` field: it controls how package names and package subpaths are resolved, but does not apply to direct file system paths.

### Monorepo usage

If you want packages in a monorepo to resolve like regular npm dependencies, including support for `exports`, avoid using `alias` to map package names directly to their source directories.

Instead, use your package manager's workspace feature to link the packages into `node_modules`, and continue importing them by package name. Rspack can then treat each request as a package request and apply the corresponding `package.json` resolution rules.

### Disable aliases

Set `resolve.alias` to `false` to clear all aliases from the merged resolve options. This is different from leaving it `undefined` or setting it to `{}`, which does not add aliases but still keeps aliases merged from other resolve options.

```js title="rspack.config.mjs"
export default {
  resolve: {
    alias: false,
  },
};
```

## resolve.aliasFields

- **Type:** `string[]`
- **Default:** `['browser']`

Define a field, such as `browser`, that should be parsed in accordance with [this specification](https://github.com/defunctzombie/package-browser-field-spec).

## resolve.byDependency

- **Type:** `Record<string, ResolveOptions>`

Configure resolve options based on the dependency type, which describes how a module is referenced in source code, such as ES module imports, CommonJS `require`, or URL-based requests.

It is useful when different request forms require different resolution strategies.

Each key represents a dependency type, and the value is a set of standard `resolve` options applied only to requests of that type.

### Dependency types

Rspack supports the following dependency types:

- `esm`: Modules referenced via `import` statements or dynamic `import()`.
- `commonjs`: Modules referenced via CommonJS `require()`.
- `amd`: Modules referenced using AMD-style definitions, such as `define()`.
- `url`: Modules referenced via URLs, such as `new URL('./asset.png', import.meta.url)`.
- `wasm`: WebAssembly modules referenced using ES module semantics.
- `worker`: Modules referenced via `new Worker(new URL('./worker.js', import.meta.url))`.
- `css-import`: CSS modules referenced via `@import`.
- `unknown`: A fallback type used when the type cannot be determined.

### Example

```js title="rspack.config.mjs"
export default {
  resolve: {
    byDependency: {
      esm: {
        mainFields: ['browser', 'module'],
      },
      commonjs: {
        aliasFields: ['browser'],
      },
      url: {
        preferRelative: true,
      },
    },
  },
};
```

In this example:

- ES module references prioritize the `browser` and `module` fields.
- CommonJS references read aliases from the `browser` field.
- URL-based references prefer relative paths during resolution.

### Merge rules

When a request matches an entry such as `resolve.byDependency.esm` or `resolve.byDependency.commonjs`, Rspack starts from the top-level `resolve` option and then applies that matching `byDependency` entry for the request type.

- Object options follow normal object merging.
- Array options replace the current value by default.
- Use `'...'` in an array to insert the top-level value at that position.

```js title="rspack.config.mjs"
export default {
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.json'],
    byDependency: {
      esm: {
        extensions: ['.mjs'],
        // final value for esm: ['.mjs']
      },
      commonjs: {
        extensions: ['.cjs', '...'],
        // final value for commonjs: ['.cjs', '.ts', '.tsx', '.js', '.json']
      },
    },
  },
};
```

## resolve.conditionNames

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

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

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

### Default value

Rspack's default `conditionNames` are determined by [mode](/config/mode.md), [target](/config/target.md) and module type.

```js
// For ES modules
['import', 'module', 'webpack', mode, target];

// For CommonJS
['require', 'module', 'webpack', mode, target];

// For CSS module
[mode, 'style'];
```

In the above example:

- `mode` is determined by [mode](/config/mode.md) config, which is `development` in development mode and `production` in other modes.
- `target` is determined by [target](/config/target.md) config:
  - If `target` includes `web`, it will be `browser`.
  - If `target` includes `node`, it will be `node`.
  - If `target` includes `webworker`, it will be `worker`.
  - If `target` includes `electron`, it will be `electron`.
  - If `target` includes `nwjs`, it will be `nwjs`.

### Example

Rspack will match [export conditions](https://nodejs.org/api/packages.html#conditional-exports) that are listed within the `resolve.conditionNames` array.

Note that the key order in the `exports` object determines priority. During condition matching, earlier entries have higher priority than later entries.

For example:

```json title="package.json"
{
  "name": "foo",
  "exports": {
    ".": {
      "import": "./index-import.js",
      "require": "./index-require.js",
      "node": "./index-node.js"
    },
    "./bar": {
      "node": "./bar-node.js",
      "require": "./bar-require.js"
    },
    "./baz": {
      "import": "./baz-import.js",
      "node": "./baz-node.js"
    }
  }
}
```

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

Importing:

- `'foo'` will resolve to `'foo/index-require.js'`
- `'foo/bar'` will resolve to `'foo/bar-node.js'` as the `"node"` key comes before `"require"` key in the conditional exports object.
- `'foo/baz'` will resolve to `'foo/baz-node.js'`

### Extend default value

If you want to add your custom conditions names while still retaining the default Rspack values, you can use `"..."`:

```js title="rspack.config.mjs"
export default {
  resolve: {
    conditionNames: ['my-custom-condition', '...'],
  },
};
```

Alternatively, to prioritize the default value first and then add your custom condition names:

```js title="rspack.config.mjs"
export default {
  resolve: {
    conditionNames: ['...', 'my-custom-condition'],
  },
};
```

## resolve.descriptionFiles

- **Type:** `string[]`
- **Default:** `['package.json']`

The JSON files to use for descriptions.

```js title="rspack.config.mjs"
export default {
  resolve: {
    descriptionFiles: ['package.json'],
  },
};
```

## resolve.enforceExtension

- **Type:** `boolean`

By default, It changes to `true` if [resolve.extensions](#resolveextensions) contains an empty string; otherwise, this value changes to `false`.

If `true`, it will not allow extension-less files. So by default `require('./foo')` works if `./foo` has a `.js` extension, but with this enabled only `require('./foo.js')` will work.

```js title="rspack.config.mjs"
export default {
  resolve: {
    enforceExtension: false,
  },
};
```

## resolve.exportsFields

- **Type:** `string[]`
- **Default:** `["exports"]`

Customize the `exports` field in package.json. e.g.

```json title="lib/package.json"
{
  "name": "lib",
  "testExports": {
    ".": "./test.js"
  },
  "exports": {
    ".": "./index.js"
  }
}
```

When this configuration is `["testExports", "exports"]`, the result of `import value from 'lib'` is `lib/test.js`.

## resolve.extensionAlias

- **Type:** `Record<string, string[] | string>`
- **Default:** `{}`

Define alias for the extension. e.g.

```js title="rspack.config.mjs"
export default {
  resolve: {
    extensionAlias: {
      '.js': ['.ts', '.js'],
    },
  },
};
```

This is particularly useful for TypeScript projects, as TypeScript recommends using the `.js` extension to reference TypeScript files.

```ts title="index.ts"
import { foo } from './foo.js'; // actually refers to `foo.ts`
```

Rspack will try to resolve `'./foo.ts'` and `'./foo.js'` sequentially when resolving `import './foo.js'`.

## resolve.extensions

- **Type:** `string[]`
- **Default:** depends on the dependency type. Typical JavaScript module requests use `[".js", ".json"]` by default, while CSS `@import` uses `[".css"]`.

Automatically resolve file extensions when importing modules. This means you can import files without explicitly writing their extensions.

For example, for a typical JavaScript module request, if importing `./index`, Rspack will try to resolve using the following order:

- `./index.js`
- `./index.json`

For a CSS request like `@import './base'`, Rspack will try:

- `./base.css`

### Example

Here's how to configure custom extensions including TypeScript and JSX files:

```js title="rspack.config.mjs"
export default {
  resolve: {
    extensions: ['.ts', '.tsx', '.mjs', '.js', '.jsx', '.json'],
  },
};
```

When multiple files with the same name but different extensions exist, Rspack will resolve the file with the extension that appears first in the array.

For example, if both `index.js` and `index.ts` exist in the same directory, and your configuration is `['.ts', '.js']`, then `import './index'` will resolve to `index.ts`.

### Default value

At the implementation level, the top-level `resolve.extensions` default is actually `[]`. Rspack still tries `.js`, `.json`, or `.css` in common cases because it applies defaults from [resolve.byDependency](#resolvebydependency) based on the request type.

If you are not familiar with [resolve.byDependency](#resolvebydependency), you can read it as "different default `resolve` settings for different ways of referencing a module". For example:

- `import`, `require()` use `[".js", ".json"]` by default
- CSS `@import` uses `[".css"]` by default

### Extend default value

To add custom extensions while keeping Rspack's defaults for the current dependency type, use the spread syntax `'...'`:

```js title="rspack.config.mjs"
export default {
  resolve: {
    // for typical JavaScript module requests, equivalent to ['.ts', '.js', '.json']
    extensions: ['.ts', '...'],
  },
};
```

### Performance considerations

- Avoid adding too many extensions as each one adds overhead to the resolution process. Keep the `extensions` array as short as possible to improve resolution performance.
- Place the most commonly used extensions first in the array.

## resolve.fallback

- **Type:**

```ts
type ResolveFallback =
  false | Record<string, false | string | (false | string)[]>;
```

- **Default:** `{}`

Redirect module requests when normal resolving fails.

```js title="rspack.config.mjs"
export default {
  resolve: {
    fallback: {
      abc: false, // do not include a polyfill for abc
      xyz: path.resolve(__dirname, 'path/to/file.js'), // include a polyfill for xyz
    },
  },
};
```

Rspack does not polyfills Node.js core modules automatically which means if you use them in your code running in browsers or alike, you will have to install compatible modules from NPM and include them yourself.

You could use [node-polyfill-webpack-plugin](https://www.npmjs.com/package/node-polyfill-webpack-plugin) to polyfill Node.js core API automatically.

```js title="rspack.config.mjs"
import NodePolyfillPlugin from 'node-polyfill-webpack-plugin';

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

Or refer to the list of Node.js polyfills used by webpack 4:

```js title="rspack.config.mjs"
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);

export default {
  resolve: {
    fallback: {
      assert: require.resolve('assert'),
      buffer: require.resolve('buffer'),
      console: require.resolve('console-browserify'),
      constants: require.resolve('constants-browserify'),
      crypto: require.resolve('crypto-browserify'),
      domain: require.resolve('domain-browser'),
      events: require.resolve('events'),
      http: require.resolve('stream-http'),
      https: require.resolve('https-browserify'),
      os: require.resolve('os-browserify/browser'),
      path: require.resolve('path-browserify'),
      punycode: require.resolve('punycode'),
      process: require.resolve('process/browser'),
      querystring: require.resolve('querystring-es3'),
      stream: require.resolve('stream-browserify'),
      string_decoder: require.resolve('string_decoder'),
      sys: require.resolve('util'),
      timers: require.resolve('timers-browserify'),
      tty: require.resolve('tty-browserify'),
      url: require.resolve('url'),
      util: require.resolve('util'),
      vm: require.resolve('vm-browserify'),
      zlib: require.resolve('browserify-zlib'),
    },
  },
};
```

## resolve.fullySpecified

- **Type:** `boolean`
- **Default:** `false`

No longer resolve extensions, no longer resolve mainFiles in package.json (but does not affect requests from mainFiles, browser, alias).

## resolve.importsFields

- **Type:** `string[]`
- **Default:** `["imports"]`

Customize the `imports` field in package.json which are used to provide the internal requests of a package (requests starting with `#` are considered internal).

e.g.

```json title="package.json"
{
  "name": "lib",
  "imports": {
    "#foo": "./src/foo.js",
    "#common/*": "./src/common/*.js"
  },
  "testImports": {
    "#foo": "./src/test/foo.js"
  }
}
```

When this configuration is `["testImports", "imports"]`, the result of `import value from '#foo'` in current package is `src/test/foo.js`.

> See [Module resolution - package.json `imports`](/guide/features/module-resolution.md#packagejson-imports) for more details.

## resolve.mainFields

- **Type:** `string[]`
- **Default:** Based on the [target](/config/target.md) option

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.

If `target` is `'web'`, `'webworker'`, or not specified, the default value is `["browser", "module", "main"]`.

```js title="rspack.config.mjs"
export default {
  resolve: {
    mainFields: ['browser', 'module', 'main'],
  },
};
```

For any other `target` (including `'node'`), the default value is `["module", "main"]`.

```js title="rspack.config.mjs"
export default {
  resolve: {
    mainFields: ['module', 'main'],
  },
};
```

For example, consider an arbitrary library called `foo` with a `package.json` that contains the following fields:

```json title="package.json"
{
  "name": "foo",
  "browser": "./dist/browser.js",
  "module": "./dist/module.js"
}
```

When `import foo from 'foo'`, Rspack resolves to the module in the `browser` field, because the `browser` field has the highest priority in `mainFields` array.

Note that the [`exports` field](https://nodejs.org/api/packages.html#packages_exports) takes precedence over `mainFields`. If an entry is resolved via `exports`, Rspack ignores the `browser`, `module`, and `main` fields.

For example, with the following package.json, `lib` is resolved via the `exports` field to `./dist/index.mjs`, and the `main` field is ignored.

```json title="package.json"
{
  "name": "lib",
  "main": "./dist/index.cjs",
  "exports": {
    ".": "./dist/index.mjs"
  }
}
```

## resolve.mainFiles

- **Type:** `string[]`
- **default:** `["index"]`

The filename suffix when resolving directories, e.g. `require('. /dir/')` will try to resolve `'. /dir/index'`.

Can configure multiple filename suffixes:

```js title="rspack.config.mjs"
export default {
  resolve: {
    mainFiles: ['index', 'main'],
  },
};
```

## resolve.modules

- **Type:** `string[]`
- **Default:** `["node_modules"]`

Specifies the directories Rspack searches when resolving bare module requests, such as `import 'react'` or `import 'utils/format'`. Relative requests such as `import './utils/format'` are resolved from the importing file and are not searched through `resolve.modules`.

Entries are tried in array order, and can be directory names, relative paths, or absolute paths:

- A directory name or relative path is searched from the directory containing the importing file, and then from each parent directory. For example, `node_modules` searches `<importer-directory>/node_modules`, then each ancestor's `node_modules` directory.
- An absolute path refers to that exact directory; it is not resolved again from each ancestor.

For example, the following configuration allows modules inside `src` to be imported with bare requests, while preserving the normal lookup of third-party packages from `node_modules`:

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  resolve: {
    modules: [path.resolve(import.meta.dirname, 'src'), 'node_modules'],
  },
};
```

With this configuration, `import 'utils/format'` can resolve to `<project>/src/utils/format.js`. If a request is not found in `src`, Rspack continues with the `node_modules` lookup.

Setting `resolve.modules` replaces the default array. Include `'node_modules'` explicitly when normal package lookup should remain enabled.

## resolve.pnp

- **Type:** `boolean`
- **Default:** `!!process.versions.pnp`

When enabled, it will enable [Yarn PnP](https://yarnpkg.com/features/pnp) resolution.

It's enabled by default if [`!!process.versions.pnp`](https://yarnpkg.com/advanced/pnpapi#processversionspnp) is `true`, which means the application is running in Yarn PnP environments.

Example:

```js title="rspack.config.mjs"
export default {
  resolve: {
    pnp: true,
  },
};
```

## resolve.preferAbsolute

- **Type:** `boolean`
- **Default:** `false`

Opt for absolute paths when resolving, in relation to `resolve.roots`.

## resolve.preferRelative

- **Type:** `boolean`
- **Default:** `false`

When enabled, `require('file')` will first look for the `./file` file in the current directory, not `<modules>/file`.

## resolve.restrictions

- **Type:** `string[]`
- **Default:** `[]`

A list of resolve restrictions to restrict the paths that a request can be resolved on.

## resolve.roots

- **Type:** `string[]`
- **Default:** `[]`

A list of directories where server-relative URLs (beginning with '/') are resolved. On systems other than Windows, these requests are initially resolved as an absolute path.

For example, importing `'/static/app.js'` and expecting it to resolve relative to the project root:

```js title="rspack.config.mjs"
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

export default {
  resolve: {
    roots: [__dirname],
  },
};
```

## resolve.symlinks

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

Whether to resolve symlinks to their symlinked location.

When enabled, symlinked resources are resolved to their real path, not their symlinked location. Note that this may cause module resolution to fail when using tools that symlink packages (like `npm link`).

## resolve.tsConfig

- **Type:** `string | object | undefined`
- **Default:** `undefined`

The replacement of [tsconfig-paths-webpack-plugin](https://www.npmjs.com/package/tsconfig-paths-webpack-plugin) in Rspack.

- string:

```js title="rspack.config.mjs"
export default {
  resolve: {
    // string
    tsConfig: path.resolve(__dirname, './tsconfig.json'),
  },
};
```

- object:

```js title="rspack.config.mjs"
export default {
  resolve: {
    tsConfig: {
      configFile: path.resolve(__dirname, './tsconfig.json'),
      references: 'auto',
    },
  },
};
```

[Click to see the example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/basic-ts).

### resolve.tsConfig.configFile

- **Type:** `string`

If you pass the path of `tsconfig.json` via the option, Rspack will try to resolve modules based on the `paths` and `baseUrl` of `tsconfig.json`, functionally equivalent to [tsconfig-paths-webpack-plugin](https://www.npmjs.com/package/tsconfig-paths-webpack-plugin).

### resolve.tsConfig.references

- **Type:** `string[] | "auto" | undefined`
- **Default:** `undefined`

Supports [tsconfig project references](https://www.typescriptlang.org/docs/handbook/project-references.html) defined in [tsconfig-paths-webpack-plugin](https://github.com/dividab/tsconfig-paths-webpack-plugin#references-_string-defaultundefined).

The list of tsconfig paths can be provided manually, or you may specify `auto` to read the paths list from `tsconfig.references` automatically.

This feature is disabled when the value is `undefined`.


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/resolve/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/resolve-loader.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# ResolveLoader

This configuration item is consistent in type with [`resolve`](/config/resolve.md), but this setting only affects the resolution of [loaders](/guide/features/loader.md).

- **Type:** Consistent with [`resolve`](/config/resolve.md)
- **Default:**

```js
{
  conditionNames: ["loader", "require", "node"],
  exportsFields: ["exports"],
  mainFields: ["loader", "main"],
  extensions: [".js"],
  mainFiles: ["index"]
}
```

## Example

For example, if you are developing a loader and want to showcase its usage from a user's perspective in an example, you can write:


**ESM**

```js title="rspack.config.mjs"
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);

export default {
  resolveLoader: {
    alias: {
      'amazing-loader': require.resolve('path-to-your-amazing-loader'),
    },
  },
};
```


**CJS**

```js title="rspack.config.cjs"
module.exports = {
  resolveLoader: {
    alias: {
      'amazing-loader': require.resolve('path-to-your-amazing-loader'),
    },
  },
};
```


Then, in the example code, you can write:

```js
require('!!amazing-loader!./amazing-file.js');
```

::: info Inline Loaders
The loader mentioned above uses the syntax of inline loaders. For details, please refer to [here](/api/loader-api/inline.md).
:::



---
url: /config/stats.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Stats

Generate packaging information that can be used to analyze module dependencies and optimize compilation speed.

:::info Output JSON file of stats

- Using `@rspack/cli`, `rspack build --json stats.json`.
- Using Rspack's JavaScript API, `stats.toJson(options)`, `stats.toString(options)`.

:::

- **Type:**

```ts
type StatsPresets =
  | 'normal'
  | 'none'
  | 'verbose'
  | 'errors-only'
  | 'errors-warnings'
  | 'minimal'
  | 'detailed'
  | 'summary';

type Stats = boolean | StatsOptions | StatsPresets;
```

- **Default in `@rspack/core`:** `{}`
- **Default in `@rspack/cli`:** `{ "preset":"errors-warnings", "timings":true, "logging":false }`

## Stats presets

| Preset              | Description                                                    |
| ------------------- | -------------------------------------------------------------- |
| `'normal'` (`true`) | Output by default value of stats options                       |
| `'none'` (`false`)  | Output nothing                                                 |
| `'verbose'`         | Output everything                                              |
| `'errors-only'`     | Output only error-related information                          |
| `'errors-warnings'` | Output only error and warning related information              |
| `'minimal'`         | Output only when errors or new compilation happen              |
| `'detailed'`        | Output everything except `chunkModules` and `chunkRootModules` |
| `'summary'`         | Output only the summary information                            |

You can specify exactly which packing information to output, all the following fields are optional.

## Preset options

### stats.all


- Type: `boolean`
- Default:`undefined`


A fallback value for stats options when an option is not defined. It has precedence over local Rspack defaults.

:::warning
Enabling `stats.all` will lead to a large amount of data transmission between Rust and JavaScript, which will significantly increase the time consumption for stats generation. Please use it with caution.
:::

### stats.preset


- Type: `boolean | StatsPresets`
- Default:`undefined`


Sets the [preset](/config/stats.md#stats-presets) for the type of information that gets displayed. It is useful for [extending stats behaviours](/config/stats.md#extending-stats-behaviours).

## Asset options

### stats.assets


- Type: `boolean`
- Default:`true`


Whether to display the asset information. See [Asset Object](/api/javascript-api/stats-json.md#asset-object) for more details.

### stats.assetsSort


- Type: `string`
- Default:`"id"`


Sort the assets by a given field. All of the [sorting fields](/config/stats.md#sorting-fields) are allowed to be used. Use `!` prefix in the value to reverse the sort order by a given field.

### stats.assetsSpace


- Type: `number`
- Default:`15`


How many items of assets should be displayed (groups will be collapsed to fit this space).

### stats.relatedAssets


- Type: `boolean`
- Default:`false`


Whether to display information about assets that are related to other assets (like SourceMaps for assets).

### stats.excludeAssets


- Type: `boolean | string | RegExp | ((name: string, asset: any) => boolean) | Array<string | RegExp | ((name: string, asset: any) => boolean)>`
- Default:`false`


Exclude the matching assets information. This can be done with a string, a RegExp, or a function that receives the asset name and asset object and returns a boolean. `stats.excludeAssets` can be an array of any of the above.

### stats.cachedAssets


- Type: `boolean`
- Default:`true`


Whether to display information about the cached assets. Setting `stats.cachedAssets` to `false` will tell stats to only show the emitted files (not the ones that were built).

## Asset grouping options

### stats.groupAssetsByChunk


- Type: `boolean`


Whether to group assets by how their are related to chunks.

### stats.groupAssetsByEmitStatus


- Type: `boolean`


Whether to group assets by their status (emitted, compared for emit or cached).

### stats.groupAssetsByExtension


- Type: `boolean`


Whether to group assets by their extension.

### stats.groupAssetsByInfo


- Type: `boolean`


Whether to group assets by their asset info (immutable, development, hotModuleReplacement, etc).

### stats.groupAssetsByPath


- Type: `boolean`


Whether to group assets by their asset path.

## Chunk options

### stats.chunks


- Type: `boolean`
- Default:`true`


Whether to display information about the chunk, see [chunk object](/api/javascript-api/stats-json.md#chunk-object) for more details.

### stats.chunkModules


- Type: `boolean`
- Default:`true`


Whether to display information about the built modules to information about the chunk.

### stats.chunkModulesSpace


- Type: `number`
- Default:`10`


How many items of chunk modules should be displayed (groups will be collapsed to fit this space).

### stats.chunkModulesSort


- Type: `string`
- Default:`"name"`


Sort the chunk modules by a given field. All of the [sorting fields](/config/stats.md#sorting-fields) are allowed to be used. Use `!` prefix in the value to reverse the sort order by a given field.

### stats.dependentModules


- Type: `boolean`
- Default:`false`


Whether to display chunk modules that are dependencies of other modules of the chunk.

### stats.chunkOrigins


- Type: `boolean`
- Default:`true`


Whether to display information about the origins of chunks and chunk merging.

### stats.chunkRelations


- Type: `boolean`
- Default:`false`


Whether to display chunk parents, children and siblings.

### stats.chunksSort


- Type: `string`
- Default:`"id"`


Sort the chunks by a given field. All of the [sorting fields](/config/stats.md#sorting-fields) are allowed to be used. Use `!` prefix in the value to reverse the sort order by a given field.

### stats.ids


- Type: `boolean`
- Default:`false`


Whether to display IDs of modules and chunks.

## ChunkGroup options

### stats.chunkGroups


- Type: `boolean`
- Default:`true`


Whether to display information about the `namedChunkGroups`, see [chunk group object](/api/javascript-api/stats-json.md#entrychunkgroup-object) for more details.

### stats.chunkGroupAuxiliary


- Type: `boolean`
- Default:`true`


Whether to display auxiliary assets in chunk groups.

### stats.chunkGroupChildren


- Type: `boolean`
- Default:`true`


Whether to display children of the chunk groups (e.g. prefetched, preloaded chunks and assets).

### stats.chunkGroupMaxAssets


- Type: `number`
- Default:`5`


How many assets should be displayed in chunk groups.

### stats.entrypoints


- Type: `boolean | 'auto'`
- Default:`false`


Whether to display the entry points with the corresponding bundles, , see [entrypoint object](/api/javascript-api/stats-json.md#entrychunkgroup-object) for more details.

When `stats.entrypoints` is set to `'auto'`, Rspack will decide automatically whether to display the entry points in the stats output.

## Module options

### stats.modules


- Type: `boolean`
- Default:`true`


Whether to display information about the built modules, see [module object](/api/javascript-api/stats-json.md#module-object) for more details.

### stats.moduleTrace


- Type: `boolean`
- Default:`true`


Whether to display dependencies and the origin of warnings/errors.

### stats.moduleAssets


- Type: `boolean`
- Default:`true`


Whether to add information about assets inside modules.

### stats.modulesSpace


- Type: `number`
- Default:`15`


How many items of modules should be displayed (groups will be collapsed to fit this space).

### stats.modulesSort


- Type: `string`
- Default:`"id"`


Sort the modules by a given field. All of the [sorting fields](/config/stats.md#sorting-fields) are allowed to be used. Use `!` prefix in the value to reverse the sort order by a given field.

### stats.reasons


- Type: `boolean`
- Default:`true`


Whether to display information about the reasons of why modules are included.

### stats.reasonsSpace


- Type: `number`
- Default:`1000`


How many characters should the reasons be displayed (groups will be collapsed to fit this space).

### stats.source


- Type: `boolean`
- Default:`false`


Whether to display the source code of modules.

### stats.depth


- Type: `boolean`
- Default:`false`


Whether to display the distance from the entry point for each module.

### stats.orphanModules


- Type: `boolean`
- Default:`false`


Whether to display the orphan modules.

> A module is an orphan if it is not included in any chunk.

### stats.runtimeModules


- Type: `boolean`
- Default:`true`


Whether to display information about runtime modules.

> The runtime modules are built-in modules of Rspack, used to provide various runtime capabilities.

:::tip
`stats.runtime` is a compatibility alias for `stats.runtimeModules`. It only takes effect when `stats.runtimeModules` is not specified; if both are set, `stats.runtimeModules` takes precedence.
:::

### stats.cachedModules


- Type: `boolean`
- Default:`true`


Whether to display information about cached (not built) modules.

:::tip
`stats.cached` is a compatibility alias for `stats.cachedModules`. It only takes effect when `stats.cachedModules` is not specified; if both are set, `stats.cachedModules` takes precedence.
:::

### stats.excludeModules


- Type: `boolean | string | RegExp | ((name: string, module: any, type: any) => boolean) | Array<string | RegExp | ((name: string, module: any, type: any) => boolean)>`
- Default:`false`


Exclude the matching modules information. This can be done with a string, a RegExp, or a function that receives the module name, module object, and module type and returns a boolean. `stats.excludeModules` can be an array of any of the above.

### stats.nestedModules


- Type: `boolean`
- Default:`true`


Whether to display information about modules nested in other modules (like with module concatenation).

### stats.nestedModulesSpace


- Type: `number`
- Default:`10`


How many items of nested modules should be displayed (groups will be collapsed to fit this space).

### stats.nestedModulesSort


- Type: `string`


Sort the nested modules by a given field. All of the [sorting fields](/config/stats.md#sorting-fields) are allowed to be used. Use `!` prefix in the value to reverse the sort order by a given field.

## Module grouping options

### stats.groupModulesByAttributes


- Type: `boolean`


Whether to group modules by their attributes (errors, warnings, assets, optional, orphan, or dependent).

### stats.groupModulesByCacheStatus


- Type: `boolean`


Whether to group modules by their cache status (cached or built and cacheable).

### stats.groupModulesByExtension


- Type: `boolean`


Whether to group modules by their extension.

### stats.groupModulesByPath


- Type: `boolean`


Whether to group modules by their path.

### stats.groupModulesByType


- Type: `boolean`


Whether to group modules by their type.

### stats.groupModulesByLayer


- Type: `boolean`


Whether to group modules by their layer.

### stats.groupReasonsByOrigin


- Type: `boolean`


Group reasons by their origin module to avoid large set of reasons.

## Optimization options

### stats.providedExports


- Type: `boolean`
- Default:`false`


Whether to display the exports of the modules.

### stats.usedExports


- Type: `boolean`
- Default:`false`


Whether to display which exports of a module are used.

### stats.optimizationBailout


- Type: `boolean`
- Default:`false`


Whether to display the reasons why optimization bailed out for modules.

## Error/Warning options

### stats.errors


- Type: `boolean`
- Default:`true`


Whether to display the errors.

### stats.errorsCount


- Type: `boolean`
- Default:`true`


Whether to display the errors count.

### stats.errorDetails


- Type: `boolean`
- Default:`false`


Whether to display the details to the errors. It defaults to `'auto'` which will show error details when there're only 2 or less errors.

### stats.errorsSpace


- Type: `number`
- Default:`5`


How many lines should an error be displayed.

### stats.errorStack


- Type: `boolean`
- Default:`true`


Whether to display stack trace of errors.

### stats.warnings


- Type: `boolean`
- Default:`true`


Whether to display the warnings.

### stats.warningsCount


- Type: `boolean`
- Default:`true`


Whether to display the warnings count.

### stats.warningsSpace


- Type: `number`
- Default:`5`


How many lines should a warning be displayed.

## Logging options

### stats.logging


- Type: `'info' | 'none' | 'error' | 'warn' | 'log' | 'verbose' | boolean`


Whether to add logging output:

- `'none'`, `false`: disable logging
- `'error'`: errors only
- `'warn'`: errors and warnings only
- `'info'`: errors, warnings, and info messages
- `'log'`, `true`: errors, warnings, info messages, log messages, groups, clears. Collapsed groups are displayed in a collapsed state.
- `'verbose'`: log everything except debug and trace. Collapsed groups are displayed in expanded state.

### stats.loggingDebug

- **Type:**

```ts
type FilterItemTypes = RegExp | string | ((value: string) => boolean);
type StatsLoggingDebug = boolean | FilterItemTypes | FilterItemTypes[];
```

Whether to display the debug information of the specified [loggers](/api/javascript-api/logger.md) such as Plugins or Loaders. When `stats.logging` is set to `false`, `stats.loggingDebug` option is ignored.

```js title="rspack.config.mjs"
export default {
  stats: {
    loggingDebug: [
      'MyPlugin',
      /rspack/, // To get core logging
    ],
  },
};
```

### stats.loggingTrace


- Type: `boolean`
- Default:`true`


Whether to display stack traces in the logging output for errors, warnings and traces.

### stats.colors

- **Type:**

```ts
type StatsColorOptions = {
  bold?: string;
  cyan?: string;
  green?: string;
  magenta?: string;
  red?: string;
  yellow?: string;
};

type StatsColors = boolean | StatsColorOptions;
```

- **Default:** environment-dependent

Whether to output in the different colors.

When an object is provided, it customizes the ANSI escape sequences used for each supported color. By default, Rspack enables colors when the current environment supports color output.

## Compilation options

### stats.hash


- Type: `boolean`
- Default:`true`


Whether to display information about the hash of the compilation.

### stats.env


- Type: `boolean`
- Default:`false`


Whether to display the `--env` information.

### stats.builtAt


- Type: `boolean`
- Default:`true`


Whether to display the build date and the build time information.

### stats.version


- Type: `boolean`
- Default:`true`


Whether to add information about the Rspack version used.

### stats.publicPath


- Type: `boolean`
- Default:`true`


Whether to display the [`publicPath`](/config/output.md#outputpublicpath).

### stats.outputPath


- Type: `boolean`
- Default:`true`


Whether to display the [`output.path`](/config/output.md#outputpath).

### stats.children


- Type: `boolean`
- Default:`true`


Whether to display the [`output.path`](/config/output.md#outputpath).

### stats.performance


- Type: `boolean`
- Default:`true`


Whether to display performance hint when the file size exceeds [`performance.maxAssetSize`](/config/performance.md#performancemaxassetsize).

### stats.timings


- Type: `boolean`
- Default:`true`


Whether to display the timing information.

## Sorting fields

For `assetsSort`, `chunksSort` and `modulesSort` there are several possible fields that you can sort items by:

- `'id'`: the item's id, an item is an asset, a module or a chunk.
- `'name'`: the item's name that was assigned to it upon importing.
- `'size'`: the size of item in bytes.
- `'chunks'`: what chunks the item originates from (for example, if there are multiple subchunks for one chunk: the subchunks will be grouped according to their main chunk).
- `'errors'`: number of errors in items.
- `'warnings'`: number of warnings in items.
- `'failed'`: whether the item has failed compilation.
- `'cacheable'`: whether the item is cacheable.
- `'built'`: whether the item has been built.
- `'prefetched'`: whether the item will be prefetched.
- `'optional'`: whether the item is optional.
- `'identifier'`: identifier of the item.
- `'index'`: item's processing index.
- `'issuer'`: the identifier of the issuer.
- `'issuerId'`: the id of the issuer.
- `'issuerName'`: the name of the issuer.
- `'issuerPath'`: the full issuer path.

## Extending stats behaviours

If you want to use the preset output behavior but want to output more or less of individual fields, you can customize the output behavior of the fields after specifying preset or all.

For example, only the error and the reason why the module was introduced are output.

```js title="rspack.config.mjs"
export default {
  stats: {
    preset: 'errors-only',
    reasons: true,
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/stats/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/target.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Target

The `target` option describes the environment in which the output code will run. Rspack uses it to determine which platform APIs and ECMAScript syntax the target environment supports, then sets compatible defaults for module resolution conditions, externals presets, and chunk loading. The runtime code generated by Rspack also uses syntax supported by the target environment.

When their own target options are omitted, Rspack's built-in loaders and minimizers can also inherit defaults from `target`. However, `target` does not add polyfills for missing APIs.

- **Type:**

```ts
type Target = false | string | string[];
```

- **Default:** `browserslist` when the project includes a standard Browserslist configuration; otherwise `web`

## Recommended configurations

### Browsers

For browser applications, define the supported browsers in a shared [Browserslist](https://github.com/browserslist/browserslist#config-file) configuration (see [Browserslist](#browserslist) for details):

```json title="package.json"
{
  "browserslist": ["fully supports es6"]
}
```

Use the following configuration:

```js title="rspack.config.mjs"
export default {
  target: 'browserslist',
};
```

When the project includes a standard Browserslist configuration, `target` defaults to `browserslist`, so the explicit option can be omitted. Keeping it explicit makes the intended runtime policy clearer.

#### Syntax version

If you do not use Browserslist and want browser output whose runtime uses at most ES2020 syntax, combine the platform and syntax targets (see [Target arrays](#target-arrays) for details):

```js title="rspack.config.mjs"
export default {
  target: ['web', 'es2020'],
};
```

`web` selects the platform. `es2020` limits the syntax used by the Rspack runtime; built-in transforms that inherit `target` also use it as their default output target.

### Node.js

For a Node.js application, specify the oldest Node.js version used in deployment:

```js title="rspack.config.mjs"
export default {
  target: 'node22',
};
```

Replace `22` with the version your application supports. A versioned target lets Rspack use runtime features known to be available in that release. An unversioned `node` target uses more conservative compatibility assumptions.

### Web workers

For code that runs in a Web Worker, Shared Worker, or Service Worker, use:

```js title="rspack.config.mjs"
export default {
  target: 'webworker',
};
```

This selects worker globals and chunk-loading behavior instead of browser APIs that depend on `document`.

## Common values

In the patterns below, `X` and `Y` are version numbers, and brackets indicate optional parts. For example, `node22`, `node22.12`, and `electron34-renderer` are valid values; the brackets are not typed literally.

| Value                      | Use                                                                                                       |
| -------------------------- | --------------------------------------------------------------------------------------------------------- |
| `async-node[X[.Y]]`        | A Node.js environment that loads chunks asynchronously with `fs` and `vm`                                 |
| `browserslist[:...]`       | Infer the platform and supported features from a Browserslist configuration, environment, or inline query |
| `electron[X[.Y]]-main`     | Electron main process                                                                                     |
| `electron[X[.Y]]-preload`  | Electron preload script                                                                                   |
| `electron[X[.Y]]-renderer` | Electron renderer process                                                                                 |
| `esX`                      | Limit ECMAScript features used by the runtime; normally combined with a platform target                   |
| `false`                    | Disable target inference and target-derived defaults                                                      |
| `node[X[.Y]]`              | Node.js environment; chunks are loaded with `require()`                                                   |
| `node-webkit[X[.Y]]`       | Alias for the corresponding NW\.js target                                                                 |
| `nwjs[X[.Y]]`              | NW\.js environment                                                                                        |
| `web`                      | Browser-like environment                                                                                  |
| `webworker`                | Web Worker, Shared Worker, or Service Worker environment                                                  |

- Supported ECMAScript targets are `es3`, `es5`, and `es2015` through `es2025`.
- An `esX` target describes syntax capabilities, not a runtime platform. It should usually be combined with a platform target such as `web` or `node`.
- Versions can be specified for Node.js, Electron, and NW\.js targets.

## Effects

### Output defaults

Rspack derives several defaults from the selected target, including:

- [module resolution conditions](/config/resolve.md#resolveconditionnames) such as `browser`, `node`, and `electron`
- [`output.environment`](/config/output.md#outputenvironment), chunk format, chunk loading, worker loading, and WebAssembly loading
- [externals presets](/config/externals.md#externalspresets), such as keeping Node.js or Electron built-in modules external
- platform globals and capabilities, such as `document`, `require`, `global`, and `importScripts`

These are defaults. You can override the corresponding options when the target preset does not match a specific output requirement.

### Source transforms \{#target-inheritance}

`target` directly controls the syntax that Rspack may use in its generated runtime. It does not, by itself, lower the syntax of every application module.

When used without an explicit transform target, the following built-in tools inherit a compatible default from `target`:

- [`builtin:swc-loader`](/guide/features/builtin-swc-loader.md) derives `env.targets` or `jsc.target`
- [`builtin:lightningcss-loader`](/guide/features/builtin-lightningcss-loader.md) derives browser targets when available
- [`SwcJsMinimizerRspackPlugin`](/plugins/swc-js-minimizer-rspack-plugin.md) derives its ECMAScript target
- [`LightningCssMinimizerRspackPlugin`](/plugins/lightning-css-minimizer-rspack-plugin.md) derives browser targets when available

Only code processed by these tools receives their transformations. Code processed by Babel follows Babel's own configuration. Built-in tools may also limit inherited targets to the versions they support.

## Target arrays \{#target-arrays}

A target array applies the common subset of features supported by every item to a single compilation. A typical combination adds an ECMAScript constraint to a platform target:

```js title="rspack.config.mjs"
export default {
  target: ['web', 'es2018'],
};
```

A target array does not create a separate compilation for each environment. Combining conflicting platform targets such as `['web', 'node']` can leave defaults such as the chunk format indeterminate.

When you need separate browser and Node.js artifacts, export multiple configurations instead:

```js title="rspack.config.mjs"
export default [
  {
    name: 'client',
    entry: './src/client.js',
    target: 'web',
    output: {
      filename: 'client.js',
    },
  },
  {
    name: 'server',
    entry: './src/server.js',
    target: 'node22',
    output: {
      filename: 'server.js',
    },
  },
];
```

Rspack runs these configurations through [MultiCompiler](/api/javascript-api/compiler.md#multicompiler) and creates a separate compilation for each one.

## Browserslist

The `browserslist` target uses a Browserslist query to infer both the platform and supported ECMAScript features. Browser queries select a web target, while Node.js queries select a Node.js target with matching runtime capabilities.

Rspack recognizes the following forms:

| Value                                 | Resolution                                                       |
| ------------------------------------- | ---------------------------------------------------------------- |
| `browserslist`                        | Use the nearest configuration and its active environment         |
| `browserslist:modern`                 | Use the `modern` environment from the nearest configuration      |
| `browserslist:last 2 versions`        | Use an inline query and ignore the project configuration         |
| `browserslist:/path/to/config`        | Use an explicit configuration file                               |
| `browserslist:/path/to/config:modern` | Use the `modern` environment from an explicit configuration file |

The nearest configuration can come from a `browserslist` or `.browserslistrc` file, or from the `browserslist` field in `package.json`. An explicitly selected `browserslist` target can also use the `BROWSERSLIST` environment variable. Rspack supports browser and Node.js queries; Electron queries are not supported.

### Baseline \{#baseline-queries}

Rspack 2.1.9 and later support [Baseline](https://web.dev/baseline) queries. For example, the following target includes browsers that support every feature in Baseline Widely Available:

```js title="rspack.config.mjs"
export default {
  target: 'browserslist:baseline widely available',
};
```

You can also use a year query such as `baseline 2024`, or a fixed-date query such as `baseline widely available on 2025-05-01`. See [Use Baseline with Browserslist](https://web.dev/articles/use-baseline-with-browserslist) for details.

### Limitations

Rspack uses [browserslist-rs](https://github.com/browserslist/browserslist-rs), which does not yet implement every Browserslist feature. The following queries are currently unsupported:

- custom usage queries, such as `> 0.5% in my stats`
- coverage queries, such as `cover 99.5% in my stats`

## Disable target

Set `target` to `false` only when you need to replace target inference with custom settings. This disables all target-derived defaults.

The following is a minimal configuration that uses the CommonJS chunk format:

```js title="rspack.config.mjs"
export default {
  target: false,
  output: {
    chunkFormat: 'commonjs',
  },
};
```

A configuration containing only `target: false` will fail because Rspack cannot infer [`output.chunkFormat`](/config/output.md#outputchunkformat). Set `output.chunkFormat` explicitly, then configure other environment-dependent options, such as `output.environment`, chunk loading, resolution conditions, and externals presets, as needed.

## Related options

- [`output.environment`](/config/output.md#outputenvironment) overrides target-derived runtime syntax capabilities.
- [`output.chunkFormat`](/config/output.md#outputchunkformat) and [`output.chunkLoading`](/config/output.md#outputchunkloading) override how chunks are emitted and loaded.
- [`externalsPresets`](/config/externals.md#externalspresets) controls which platform built-ins are treated as external.
- [`resolve.conditionNames`](/config/resolve.md#resolveconditionnames) controls which conditions in the `exports` field of `package.json` are used during resolution.
- Plugin authors can read the resolved target from [`compiler.target`](/api/javascript-api/compiler.md#target).


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/target/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/watch.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Watch

Rspack can watch files and recompile whenever they change.

## watch

- **Type:** `boolean`
- **Default:** `false`

Turn on watch mode. This means that after the initial build, Rspack will continue to watch for changes in any of the resolved files.

```js title="rspack.config.mjs"
export default {
  watch: true,
};
```

:::tip
`watch` is enabled by default when using `@rspack/dev-server`.
:::

## watchOptions

- **Type:** `object`

A set of options used to customize watch mode.

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    ignored: /node_modules/,
    poll: true,
  },
};
```

### watchOptions.aggregateTimeout

- **Type:** `number`
- **Default:** `5`

Add a delay before rebuilding once the first file changed. This allows Rspack to aggregate any other changes made during this time period into one rebuild. Pass a value in milliseconds:

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    aggregateTimeout: 600,
  },
};
```

### watchOptions.ignored

- **Type:** `RegExp | string | string[] | ((entry: string) => boolean)`
- **Default:** `/[\\/](?:\.git|node_modules)[\\/]/`

Use `watchOptions.ignored` to exclude matching files and directories from watch mode. Ignoring directories that do not need to be watched can reduce CPU and memory usage.

By default, `.git` and `node_modules` directories are ignored, so changes inside them do not trigger rebuilds.

To watch files in `node_modules`, override the default value and ignore only the `.git` directory:

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    ignored: /[\\/]\.git[\\/]/,
  },
};
```

You can also use a glob pattern:

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    ignored: '**/.git',
  },
};
```

To ignore multiple glob patterns, pass an array:

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    ignored: ['**/files/**/*.js', '**/.git', '**/node_modules'],
  },
};
```

You can also specify one or more absolute paths. Because strings are interpreted as glob patterns, normalize path separators to forward slashes for consistent behavior across platforms:

```js title="rspack.config.mjs"
import path from 'node:path';

const ignoredDir = path
  .resolve(import.meta.dirname, 'ignored-dir')
  .replaceAll(path.sep, '/');

export default {
  watchOptions: {
    ignored: [ignoredDir],
  },
};
```

The glob syntax used by `watchOptions.ignored` is based on [glob-to-regexp](https://github.com/fitzgen/glob-to-regexp). See its documentation for details about the supported pattern syntax.

Finally, `ignored` can be a function that is asked about every entry and returns `true` to exclude it:

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    ignored: (entry) => entry.includes('.git'),
  },
};
```

Unlike the other forms, the function receives the entry with the platform path separators, and it has to exclude the entries below an excluded directory itself.

### watchOptions.poll

- **Type:** `number | boolean`
- **Default:** `false`

Whether to watch by polling.

When set to `true`, the default polling interval is 5007 milliseconds. This matches the default polling interval used by Node.js `fs.watchFile()`.

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    poll: true,
  },
};
```

You can also set a custom polling interval. Note that shorter intervals can significantly increase CPU usage and file system I/O:

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    poll: 1000, // Check for changes every second
  },
};
```

### watchOptions.followSymlinks

- **Type:** `boolean`
- **Default:** `false`

Follow symbolic links while looking for a file. This is usually not needed as Rspack already resolves symlinks with [resolve.symlinks](/config/resolve.md#resolvesymlinks).

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    followSymlinks: true,
  },
};
```

### watchOptions.stdin

- **Type:** `boolean`

Stop watching when stdin stream has ended.

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    stdin: true,
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/watch) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/other-options.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Other options

These are the remaining configuration options supported by rspack.

## amd


[Added in v1.3.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.3.0)

- **Type:** `false | Record<string, any>`
- **Default:** `false`

:::info
Unlike webpack, where the default value of the `amd` option is `{}` (meaning AMD module dependency analysis is enabled by default), Rspack sets the default value of the `amd` option to `false`. This means AMD module dependency analysis is disabled by default in Rspack. This change was made because the usage of AMD modules is gradually decreasing. If your application requires it, you can enable this option by yourself.
:::

Enable this option to support dependency analysis for AMD modules, which is helpful for compatibility with some older libraries written according to the AMD specification.

```js title="rspack.config.mjs"
export default {
  amd: {}, // enable parsing AMD module dependencies
};
```

In addition, you can set the values of `require.amd` or `define.amd` through this configuration:

```js title="rspack.config.mjs"
export default {
  amd: {
    jQuery: true, // `require.amd` and `define.amd` are set to `{ jQuery: true }`.
  },
};
```

## bail


- Type: `boolean`
- Default:`false`


Fail out on the first error instead of tolerating it. By default Rspack will log these errors in red in the terminal, as well as the browser console when using HMR, but continue bundling.
To enable it:

```js title="rspack.config.mjs"
export default {
  bail: true,
};
```

This will force Rspack to exit its bundling process.

## dependencies


- Type: `string[]`
- Default:`undefined`


A list of [name](#name) defining all sibling configurations it depends on. Dependent configurations need to be compiled first.

In watch mode dependencies will invalidate the compiler when:

1. the dependency has changed
2. a dependency is currently compiling or invalid

Remember that current configuration will not compile until its dependencies are done.

```js title="rspack.config.mjs"
export default [
  {
    name: 'client',
    target: 'web',
  },
  {
    name: 'server',
    target: 'node',
    dependencies: ['client'],
  },
];
```

## ignoreWarnings

- **Type:**

```ts
type IgnoreWarnings = (
  | RegExp
  | {
      file?: RegExp;
      message?: RegExp;
      module?: RegExp;
    }
  | ((warning: WebpackError, compilation: Compilation) => boolean)
)[];
```

- **Default:** `undefined`

Tells Rspack to suppress specific compilation warnings by matching their message, module, or file, or by using a custom function.

Use a RegExp to match the warning message:

```js title="rspack.config.mjs"
export default {
  ignoreWarnings: [/warning from compiler/, /other warning/],
};
```

Use an object to match the warning via `message`, `file`, or `module`:

```js title="rspack.config.mjs"
export default {
  ignoreWarnings: [
    { message: /warning from compiler/ },
    { file: /node_modules/ },
  ],
};
```

Use a function for full control. Return `true` to ignore the warning:

```js title="rspack.config.mjs"
export default {
  ignoreWarnings: [
    (warning, compilation) => {
      return /warning from compiler/.test(warning.message || '');
    },
  ],
};
```

## name


- Type: `string`
- Default:`undefined`


Name of the configuration. Used when loading multiple configurations.

```js title="rspack.config.mjs"
export default {
  name: 'admin-app',
};
```

## loader


- Type: `Record<string, any>`
- Default:`undefined`


Expose custom values into the [loader context](/api/loader-api/context.md).

For example, you can define a new variable in the loader context:

```js title="rspack.config.mjs"
export default {
  loader: {
    answer: 42,
  },
};
```

Then use `this.answer` to get its value in the loader:

```js title="custom-loader.mjs"
export default function (source) {
  console.log(this.answer); // will log `42` here
  return source;
}
```

:::tip
You can override properties in the loader context because Rspack copies all properties defined on the loader to the loader context.
:::


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/other-options/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /config/deprecated-options.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Deprecated options

This page lists configuration options that have been deprecated in Rspack.

These options are kept for backward compatibility only and should not be used in new projects.

## experiments.css


Stability: Deprecated

- **Type:** `boolean`
- **Default:** `false`

:::warning Deprecated
This option is deprecated since Rspack 2.0. Users now need to manually add CSS rules to enable CSS support. In a future version, Rspack will automatically add CSS-related default rules.
:::

### Migration

To use CSS in Rspack 2.0, you need to manually add CSS rules to your configuration:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        type: 'css/auto',
      },
    ],
  },
};
```

### Legacy usage (deprecated)

```js title="rspack.config.mjs"
export default {
  experiments: {
    css: true,
  },
};
```

## experiments.incremental


Stability: Deprecated

This option has been moved to top-level [`incremental`](/config/incremental.md).

## rules\[].loaders

An array to pass the loader package name and its options.

:::warning
This option has been deprecated. Use [rules\[\].use](/config/module-rules.md#rulesuse) instead.
:::



---
url: /plugins/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Rspack plugins

Browse Rspack's built-in plugins by function below.

To learn how to use plugins, see the [plugin guide](/guide/features/plugin.md).

## Output and assets

- [BannerPlugin](/plugins/banner-plugin.md): Adds a banner to the beginning or end of generated chunks.
- [CopyRspackPlugin](/plugins/copy-rspack-plugin.md): Copies files or directories into the build output.
- [CssExtractRspackPlugin](/plugins/css-extract-rspack-plugin.md): Extracts CSS into standalone files as a replacement for `mini-css-extract-plugin`.
- [HtmlRspackPlugin](/plugins/html-rspack-plugin.md): Generates HTML files and injects the build's scripts and styles.
- [SubresourceIntegrityPlugin](/plugins/subresource-integrity-plugin.md): Generates integrity hashes for emitted assets and adds them to HTML and chunk-loading tags.

## Build optimization

- [CompactHashedChunkIdsPlugin](/plugins/compact-hashed-chunk-ids-plugin.md): Assigns compact, stable hash ids to chunks.
- [CompactHashedModuleIdsPlugin](/plugins/compact-hashed-module-ids-plugin.md): Assigns compact, stable hash ids to modules.
- [CssChunkingPlugin](/plugins/css-chunking-plugin.md): Splits CSS into chunks while preserving required stylesheet ordering.
- [DeterministicModuleIdsPlugin](/plugins/deterministic-module-ids-plugin.md): Assigns short numeric module ids that remain stable between builds.
- [DllPlugin](/plugins/dll-plugin.md): Creates a prebuilt DLL bundle and its manifest.
- [DllReferencePlugin](/plugins/dll-reference-plugin.md): References a DLL manifest to reuse prebuilt dependencies.
- [LightningCssMinimizerRspackPlugin](/plugins/lightning-css-minimizer-rspack-plugin.md): Minifies CSS assets with Lightning CSS.
- [LimitChunkCountPlugin](/plugins/limit-chunk-count-plugin.md): Merges chunks to keep their total count below a configured limit.
- [RuntimeChunkPlugin](/plugins/runtime-chunk-plugin.md): Controls how Rspack creates runtime chunks.
- [SplitChunksPlugin](/plugins/split-chunks-plugin.md): Splits shared or asynchronous code into chunks for better loading and caching.
- [SwcJsMinimizerRspackPlugin](/plugins/swc-js-minimizer-rspack-plugin.md): Minifies JavaScript assets with SWC.

## Modules and dependencies

- [ContextReplacementPlugin](/plugins/context-replacement-plugin.md): Narrows or replaces the modules available to dynamic `require` and `import()` contexts.
- [DefinePlugin](/plugins/define-plugin.md): Replaces variables with constant values or expressions at compile time.
- [EntryPlugin](/plugins/entry-plugin.md): Adds an entry module and entry chunk during compilation.
- [EnvironmentPlugin](/plugins/environment-plugin.md): Defines selected `process.env` values through `DefinePlugin`.
- [ExternalsPlugin](/plugins/externals-plugin.md): Leaves selected dependencies out of the bundle so they can be provided externally.
- [IgnorePlugin](/plugins/ignore-plugin.md): Prevents matching `import` or `require` requests from producing modules.
- [JavascriptModulesPlugin](/plugins/javascript-modules-plugin.md): Handles JavaScript module bundling and exposes compilation hooks for customizing rendering and chunk hashes.
- [ModuleFederationPlugin](/plugins/module-federation-plugin.md): Enables Module Federation 1.5 in Rspack.
- [ModuleFederationPluginV1](/plugins/module-federation-plugin-v1.md): Provides webpack-compatible Module Federation 1.0 behavior.
- [NormalModuleReplacementPlugin](/plugins/normal-module-replacement-plugin.md): Replaces matching module requests with another resource.
- [ProvidePlugin](/plugins/provide-plugin.md): Automatically imports modules when configured identifiers are used.
- [VirtualModulesPlugin](/plugins/virtual-modules-plugin.md): Creates, updates, and deletes in-memory modules that behave like files.

## Development and debugging

- [CaseSensitivePlugin](/plugins/case-sensitive-plugin.md): Warns when module request casing conflicts with paths on the file system.
- [CircularCheckRspackPlugin](/plugins/circular-check-rspack-plugin.md): Reports circular imports found in the module graph.
- [EvalSourceMapDevToolPlugin](/plugins/eval-source-map-dev-tool-plugin.md): Provides fine-grained source map generation using eval-based mappings.
- [HotModuleReplacementPlugin](/plugins/hot-module-replacement-plugin.md): Enables hot module replacement during development.
- [NoEmitOnErrorsPlugin](/plugins/no-emit-on-errors-plugin.md): Prevents assets from being emitted when compilation errors occur.
- [ProgressPlugin](/plugins/progress-plugin.md): Reports and customizes compilation progress.
- [SourceMapDevToolPlugin](/plugins/source-map-dev-tool-plugin.md): Provides fine-grained control over source map generation.

## Reference

- [Low-level plugins](/plugins/low-level-plugins.md): Catalogs publicly exposed building blocks for target presets, runtime templates, child compilers, and higher-level plugins.
- [Community plugin compatibility](/plugins/community-plugin-compatibility.md): Lists compatibility results for common webpack community plugins.
- [webpack plugin compatibility](/plugins/webpack-built-in-plugin-support.md): Summarizes Rspack's compatibility with webpack built-in plugins and selected internal plugins.

## Community plugins

Rspack strives to maintain compatibility with the webpack plugin ecosystem to leverage the excellent features that have been accumulated and validated by the community.

Please refer to [Community plugin compatibility](/plugins/community-plugin-compatibility.md) to access a list of webpack plugins that have passed our compatibility tests.

You can also check out the community Rspack plugins at [awesome-rstack](https://github.com/rstackjs/awesome-rstack).

Welcome to add the plugins you developed to this repository.

## Deprecated

- [CircularDependencyRspackPlugin](/plugins/circular-dependency-rspack-plugin.md): Detects circular dependencies and is deprecated in favor of `CircularCheckRspackPlugin`.



---
url: /plugins/banner-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# BannerPlugin

`BannerPlugin` inserts custom content at the beginning or end of generated chunk files. By default, it wraps the content in a comment and prepends it to every chunk file.

## Examples

Add a comment to the beginning of every generated chunk file:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.BannerPlugin('Built with Rspack')],
};
```

The generated chunk begins with this comment:

```js title="dist/main.js"
/*! Built with Rspack */
// ...
```

## Options

`BannerPlugin` accepts a banner string, function, or options object. The examples below reuse the `rspack` import above.

### banner

- **Type:**

  ```ts
  type BannerFunction = (args: {
    hash: string;
    chunk: Chunk;
    filename: string;
  }) => string;

  type BannerContent = string | BannerFunction;
  ```

- **Required:** Yes, when using an options object

The `banner` option supports:

- **String:** Pass a string to specify the banner content directly. By default, Rspack wraps the string in a comment. You can set it through the `banner` option or pass it directly to `BannerPlugin`.

  ```js
  new rspack.BannerPlugin({
    banner: 'Built with Rspack',
  });
  ```

- **Function:** Pass a function to generate banner content for each selected chunk file. Rspack calls it with the compilation `hash`, current `chunk`, and emitted `filename`. The returned string is wrapped in a comment by default. You can set the function through the `banner` option or pass it directly to `BannerPlugin`.

  ```js
  new rspack.BannerPlugin({
    banner: ({ filename }) => `Built file: ${filename}`,
  });
  ```

### entryOnly

- **Type:** `boolean`
- **Default:** `undefined`

If `true`, the banner is only added to files that belong to initial chunks. Files for asynchronously loaded chunks are skipped. When omitted, the banner can be added to both initial and async chunk files.

```js
new rspack.BannerPlugin({
  banner: 'Entry bundle',
  entryOnly: true,
});
```

### footer

- **Type:** `boolean`
- **Default:** `undefined`

If `true`, appends the banner to each selected chunk file instead of prepending it. When omitted, the banner is added at the beginning.

```js
new rspack.BannerPlugin({
  banner: 'End of bundle',
  footer: true,
});
```

### raw

- **Type:** `boolean`
- **Default:** `undefined`

If `true`, emits the banner without wrapping it in a comment. Ensure that the raw content is valid for every selected output file.

```js
new rspack.BannerPlugin({
  banner: '/* Build: production */',
  raw: true,
});
```

### stage

- **Type:** `number`
- **Default:** `Compilation.PROCESS_ASSETS_STAGE_ADDITIONS` (`-100`)

Controls the [`processAssets`](/api/plugin-api/compilation-hooks.md#processassets) stage at which the banner is added. Lower stage values run earlier. Change this only when the banner must run before or after another asset-processing plugin.

```js
new rspack.BannerPlugin({
  banner: 'Optimized bundle',
  stage: rspack.Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE,
});
```

### test

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

`test` selects the chunk files that receive the banner. The banner is added only when a chunk's emitted filename matches `test`.

Matching is performed against the emitted filename, not a module source path. Strings match the beginning of the filename, regular expressions can match any part, and arrays match when any item does.

If omitted, `test` does not filter chunk files.

```js
new rspack.BannerPlugin({
  banner: 'JavaScript bundle',
  test: /\.js$/,
});
```

### include

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

`include` limits the banner to specific chunk files. The banner is added only when a chunk's emitted filename matches `include`.

Matching is performed against the emitted filename, not a module source path. Strings match the beginning of the filename, regular expressions can match any part, and arrays match when any item does.

If `test` is also set, the filename must match both `test` and `include`.

```js
new rspack.BannerPlugin({
  banner: 'Application bundle',
  include: [/^app/, /^admin/],
});
```

### exclude

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

`exclude` prevents the banner from being added to specific chunk files. The banner is skipped when a chunk's emitted filename matches `exclude`.

Matching is performed against the emitted filename, not a module source path. Strings match the beginning of the filename, regular expressions can match any part, and arrays match when any item does.

`exclude` is applied after `test` and `include`.

```js
new rspack.BannerPlugin({
  banner: 'Application bundle',
  exclude: [/^runtime/, /^vendor/],
});
```



---
url: /plugins/copy-rspack-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# CopyRspackPlugin


Rspack only

Copies individual files or entire directories, which already exist, to the build directory.

## Examples

- Copy a single file. If the file does not exist, the plugin will throw an error.

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

export default {
  entry: './src/index.js',
  plugins: [
    new rspack.CopyRspackPlugin({
      // `./src/file.txt` -> `./dist/file.txt`
      patterns: [{ from: 'src/file.txt' }],
    }),
  ],
};
```

- `patterns` can be a string, or an array of objects.

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

export default {
  entry: './src/index.js',
  plugins: [
    new rspack.CopyRspackPlugin({
      // This is equivalent to `patterns: [{ from: 'src/file.txt' }]`
      patterns: 'src/file.txt',
    }),
  ],
};
```

- Copy a directory. If there are no files in the directory, the plugin will throw an error.

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

export default {
  entry: './src/index.js',
  plugins: [
    new rspack.CopyRspackPlugin({
      // `./dir/**/*` -> `./dist`
      // For example, `./dir/foo.txt` -> `./dist/foo.txt`
      patterns: [{ from: 'dir' }],
    }),
  ],
};
```

- Use glob pattern to match and copy files.

```ts title="rspack.config.mjs"
import { rspack } from '@rspack/core';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

export default {
  entry: './src/index.js',
  plugins: [
    new rspack.CopyRspackPlugin({
      // `./src/*.json` -> `./dist/*.json`
      // 例如 `./src/foo.json` -> `./dist/foo.json`
      patterns: [
        {
          from: '*.json',
          context: path.join(__dirname, 'src'),
        },
      ],
    }),
  ],
};
```

- Use `to` to specify the destination path.

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

export default {
  entry: './src/index.js',
  plugins: [
    new rspack.CopyRspackPlugin({
      // `./dir/**/*` -> `./dist/other-dir`
      // For example, `./dir/foo.txt` -> `./dist/other-dir/foo.txt`
      patterns: [{ from: 'dir', to: 'other-dir' }],
    }),
  ],
};
```

## Options

### from

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

The source path of the copy operation, which can be an absolute path, a relative path, or a glob pattern.

It can refer to a file or a directory. If a relative path is passed, it is relative to the [context](#context) option.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

export default {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        // relative path
        { from: 'relative/path/to/file.js' },
        { from: 'relative/path/to/dir' },
        // absolute path
        { from: path.resolve(__dirname, 'src', 'file.js') },
        { from: path.resolve(__dirname, 'src', 'dir') },
        // glob
        { from: 'dir/**/*' },
        // If absolute path is a `glob` we replace backslashes with forward slashes,
        // because only forward slashes can be used in the `glob`
        {
          from: path.posix.join(
            path.resolve(__dirname, 'src').replace(/\\/g, '/'),
            '*.txt',
          ),
        },
      ],
    }),
  ],
};
```

### to

- **Type:**

```ts
type To =
  | string
  | ((pathData: { context: string; absoluteFilename?: string }) => string);
```

- **Default:** [output.path](/config/output.md#outputpath)

The destination path of the copy operation, which can be an absolute path, a relative path, or a template string. If not specified, it is equal to Rspack's [output.path](/config/output.md#outputpath).

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: 'dir',
          to: 'relative/path/to/dest/',
        },
        {
          from: 'dir',
          to: '/absolute/path/to/dest/',
        },
        {
          from: 'dir',
          to: '[path][name].[contenthash][ext]',
        },
      ],
    }),
  ],
};
```

### context

- **Type:** `string`
- **Default:** [context](/config/context.md)

`context` is a path to be prepended to `from` and removed from the start of the result paths.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

export default {
  plugins: [
    new rspack.CopyRspackPlugin({
      // `./src/*.json` -> `./dist/*.json`
      patterns: [{ from: '*.json', context: path.join(__dirname, 'src') }],
    }),
  ],
};
```

`context` can be an absolute path or a relative path. If it is a relative path, then it will be converted to an absolute path based on Rspack's [context](/config/context.md).

`context` should be explicitly set only when `from` contains a glob. Otherwise, `context` is automatically set based on whether `from` is a file or a directory:

- If `from` is a file, then `context` is its directory. The result path will be the filename alone.
- If `from` is a directory, then `context` equals `from`. The result paths will be the paths of the directory's contents (including nested contents), relative to the directory.

### toType

- **Type:** `'dir' | 'file' | 'template'`
- **Default:** `undefined`

Specify the type of [to](#to), which can be a directory, a file, or a template name in Rspack. If not specified, it will be automatically inferred.

The automatic inference rules are as follows:

- `dir`: If `to` has no extension, or ends on `/`.
- `file`: If `to` is not a directory and is not a template.
- `template`: If `to` contains a template pattern.

Examples:

- `dir`:

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: 'path/to/file.txt',
          to: 'directory/with/extension.ext',
          toType: 'dir',
        },
      ],
    }),
  ],
};
```

- `file`:

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: 'path/to/file.txt',
          to: 'file/without/extension',
          toType: 'file',
        },
      ],
    }),
  ],
};
```

- `template`:

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: 'src/',
          to: 'dest/[name].[contenthash][ext]',
          toType: 'template',
        },
      ],
    }),
  ],
};
```

### noErrorOnMissing

- **Type:** `boolean`
- **Default:** `false`

Whether to ignore the error if there are missing files or directories.

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: path.resolve(__dirname, 'missing-file.txt'),
          noErrorOnMissing: true,
        },
      ],
    }),
  ],
};
```

### force

- **Type:** `boolean`
- **Default:** `false`

Whether to overwrite the asset if it already exists.

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [{ from: 'file.txt', force: true }],
    }),
  ],
};
```

### priority

- **Type:** `number`
- **Default:** `0`

Allows to specify the priority of copying files with the same destination name.

When [force](#force) is set to `true`, if a matching file is found, the one with higher priority will overwrite the one with lower priority.

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        // Copied first
        {
          from: 'dir-1/file.txt',
          to: 'newfile.txt',
          priority: 5,
        },
        // Copied second and will overwrite "dir-1/file.txt"
        {
          from: 'dir-2/file.txt',
          to: 'newfile.txt',
          force: true,
          priority: 10,
        },
      ],
    }),
  ],
};
```

### globOptions

- **Type:**

```ts
type GlobOptions = {
  // Whether the match is case sensitive
  // @default true
  caseSensitiveMatch?: boolean;
  // Whether to match files starting with `.`
  // @default true
  dot?: boolean;
  // An array of strings in glob format, which can be used to ignore specific paths
  // @default undefined
  ignore?: string[];
};
```

- **Default:** `undefined`

Set the glob options for the copy operation.

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: 'public/**/*',
          globOptions: {
            dot: false,
            caseSensitiveMatch: false,
            ignore: ['**/file.*', '**/ignored-directory/**'],
          },
        },
      ],
    }),
  ],
};
```

### transform

- **Type:**

```ts
type transform =
  | {
      transformer: (
        input: Buffer,
        absoluteFilename: string,
      ) => string | Buffer | Promise<string> | Promise<Buffer>;
    }
  | ((
      input: Buffer,
      absoluteFilename: string,
    ) => string | Buffer | Promise<string> | Promise<Buffer>);
```

- **Default:** `undefined`

Allows to modify the file contents.

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: 'src/*.png',
          // The `content` argument is a [`Buffer`](https://nodejs.org/api/buffer.html) object,
          // it could be converted to a string to be processed using `content.toString()`.
          // The `absoluteFilename` argument is a string, it is absolute path from where the file is being copied.
          transform(content, absoluteFilename) {
            return optimize(content);
          },
        },
      ],
    }),
  ],
};
```

### copyPermissions

- **Type:** `boolean`
- **Default:** `false`

Whether to copy the file permissions from the source to the destination.

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: 'src/executable.sh',
          copyPermissions: true, // Preserves the executable permission
        },
      ],
    }),
  ],
};
```

This is particularly useful when copying executable files, scripts, or any files where permissions are important. When set to `true`, the plugin will attempt to set the same permissions on the destination file as the source file has.

### info

- **Type:**

```ts
type Info = {
  immutable?: boolean;
  // Whether to skip minification for the copied files.
  // @default false
  minimized?: boolean;
  chunkHash?: string[];
  contentHash?: string[];
  development?: boolean;
  hotModuleReplacement?: boolean;
  related?: {
    sourceMap?: string;
  };
  version?: string;
};
```

- **Default:** `undefined`

Allows to add some assets info to the copied files, which may affect some behaviors in the build process.

For example, by default, the copied JS and CSS files will be minified by Rspack's [minimizer](/config/optimization.md#optimizationminimizer), if you want to skip minification for copied files, you can set `info.minimized` to `true`.

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.CopyRspackPlugin({
      patterns: [
        {
          from: 'src/file.js',
          info: { minimized: true },
        },
      ],
    }),
  ],
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/plugins/copy-webpack-plugin/#root) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /plugins/css-extract-rspack-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# CssExtractRspackPlugin


Rspack only

`CssExtractRspackPlugin` works with [css-loader](https://github.com/webpack/css-loader) to extract CSS imported by JavaScript modules into separate files. In Rspack, use it as an alternative to [mini-css-extract-plugin](https://github.com/webpack/mini-css-extract-plugin), or whenever your project needs css-loader features.

By default, CSS in entry chunks is emitted as `[name].css`. CSS loaded through dynamic `import()` is handled by runtime code injected by the plugin.

If your project does not need css-loader, prefer Rspack's [built-in CSS support](/guide/languages/css.md) to avoid the extra loader and plugin processing.

:::warning
`CssExtractRspackPlugin.loader` cannot be used with Rspack's built-in CSS module types: `css`, `css/auto`, `css/global`, or `css/module`. The default module type is `javascript/auto`, so `type` can normally be omitted. If a module uses one of the built-in CSS types, the loader skips it and emits a warning; the plugin does not extract its CSS.
:::

## Examples

### Basic usage

Register the plugin and place `CssExtractRspackPlugin.loader` before `css-loader` in the CSS rule:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  entry: './src/index.js',
  plugins: [new rspack.CssExtractRspackPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
      },
    ],
  },
};
```

If the `main` entry imports CSS, the default output includes:

```text
dist/
├── main.js
└── main.css
```

### With the HTML plugin

`CssExtractRspackPlugin` emits CSS imported by an entry, but does not add a link for it to HTML. Register [HtmlRspackPlugin](/plugins/html-rspack-plugin.md) alongside it to generate `index.html` and inject the corresponding stylesheet `<link>` tags:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  entry: './src/index.js',
  plugins: [new rspack.HtmlRspackPlugin(), new rspack.CssExtractRspackPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
      },
    ],
  },
};
```

The configuration above generates `dist/index.html` with a link to `main.css`:

```html
<link href="main.css" rel="stylesheet" />
```

### Split CSS

`CssExtractRspackPlugin` represents extracted styles as modules of type `css/mini-extract`. Use [`splitChunks.cacheGroups.{cacheGroup}.type`](/plugins/split-chunks-plugin.md#splitchunkscachegroupscachegrouptype) to select only CSS extracted by this plugin, without selecting JavaScript modules or modules handled by Rspack's built-in CSS support.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.CssExtractRspackPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
      },
    ],
  },
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        extractedCss: {
          type: 'css/mini-extract',
          name: 'styles',
          chunks: 'all',
          enforce: true,
        },
      },
    },
  },
};
```

Here, `extractedCss` selects only modules whose type is `css/mini-extract`. For details about `enforce`, see [`splitChunks.cacheGroups.{cacheGroup}.enforce`](/plugins/split-chunks-plugin.md#splitchunkscachegroupscachegroupenforce).

## Options

Pass these options to `new rspack.CssExtractRspackPlugin()`.

### filename

- **Type:**

  ```ts
  type CssFilenameFunction = (
    pathData: PathData,
    assetInfo?: AssetInfo,
  ) => string;

  type CssFilename = string | CssFilenameFunction;
  ```

- **Default:** `'[name].css'`

Sets the filename of extracted CSS assets for chunks loaded with an entry. The value supports the placeholders documented for [`output.filename`](/config/output.md#outputfilename). When omitted or set to an empty string, Rspack uses `[name].css`. CSS assets for on-demand chunks use [`chunkFilename`](#chunkfilename).

- **String:** Uses a non-empty value as the filename template for every CSS chunk loaded with an entry.

  ```js
  new rspack.CssExtractRspackPlugin({
    filename: 'css/[name].[contenthash].css',
  });
  ```

- **Function:** For each CSS chunk loaded with an entry, Rspack calls the function with its `PathData` and optional `AssetInfo`, then uses the returned string as the filename.

  ```js
  new rspack.CssExtractRspackPlugin({
    filename: ({ chunk }) => `css/${chunk?.name ?? 'styles'}.css`,
  });
  ```

When `filename` is a function and `chunkFilename` is omitted, on-demand CSS chunks use `[id].css`; Rspack does not reuse the function for them.

### chunkFilename

- **Type:**

  ```ts
  type CssChunkFilenameFunction = (
    pathData: PathData,
    assetInfo?: AssetInfo,
  ) => string;

  type CssChunkFilename = string | CssChunkFilenameFunction;
  ```

- **Default:** Derived from `filename`

Sets the filename of extracted CSS assets for on-demand chunks, including chunks created by dynamic `import()`. An explicitly configured non-empty string or function overrides the value derived from `filename`. The value supports the placeholders documented for [`output.chunkFilename`](/config/output.md#outputchunkfilename).

When omitted, Rspack derives the value as follows:

- If a string `filename` contains `[name]`, `[id]`, `[chunkhash]`, or `[contenthash]`, Rspack reuses it.

- If a string `filename` contains none of those placeholders, Rspack adds `[id].` before its basename. For example, `css/styles.css` produces `css/[id].styles.css` for async chunks.

- If `filename` is a function, Rspack uses `[id].css`.

- **String:** Uses a non-empty value as the filename template for every on-demand CSS chunk.

  ```js
  new rspack.CssExtractRspackPlugin({
    chunkFilename: 'css/[id].[contenthash].chunk.css',
  });
  ```

- **Function:** Rspack calls the function for each on-demand CSS chunk with its `PathData` and optional `AssetInfo`, then uses the returned string as the filename.

  ```js
  new rspack.CssExtractRspackPlugin({
    chunkFilename: ({ chunk }) =>
      `css/${chunk?.name ?? chunk?.id ?? 'chunk'}.chunk.css`,
  });
  ```

### ignoreOrder

- **Type:** `boolean`
- **Default:** `false`

Controls whether Rspack reports CSS order conflicts. By default, Rspack warns when different chunk groups require incompatible CSS orders, then emits the CSS using a fallback order.

Set `ignoreOrder` to `true` to suppress these warnings. This does not change the order Rspack chooses and does not resolve order-dependent styling conflicts.

```js
new rspack.CssExtractRspackPlugin({
  ignoreOrder: true,
});
```

### insert

- **Type:**

  ```ts
  type InsertFunction = (linkTag: HTMLLinkElement) => void;

  type Insert = string | InsertFunction;
  ```

- **Default:** `undefined`

Sets the insertion position of stylesheet `<link>` elements created by the plugin runtime for async CSS chunks and HMR updates. It does not affect stylesheet links already present in HTML.

When omitted, the runtime appends a new async stylesheet to `document.head`. During a hot update, it inserts the replacement after the previous stylesheet.

- **String:** Treats the value as a selector passed to `document.querySelector()` and inserts the stylesheet immediately after the first matching element. The selector must match an element at runtime.

  ```js
  new rspack.CssExtractRspackPlugin({
    insert: '#css-anchor',
  });
  ```

- **Function:** Serializes the function into the generated runtime and calls it in the browser with the new `<link>` element. The function must insert the element itself and cannot use variables from the Rspack configuration's scope.

  ```js
  new rspack.CssExtractRspackPlugin({
    insert: (linkTag) => {
      document.head.appendChild(linkTag);
    },
  });
  ```

The `insert` option has no effect when [`runtime`](#runtime) is `false`.

### attributes

- **Type:** `Record<string, string>`
- **Default:** `undefined`

Adds custom attributes to stylesheet `<link>` elements created by the plugin runtime. These elements are used when loading async CSS chunks and applying HMR updates; stylesheet links already present in HTML are not affected. When omitted, the runtime adds no custom attributes.

```js
new rspack.CssExtractRspackPlugin({
  attributes: {
    'data-source': 'rspack',
  },
});
```

Use [`linkType`](#linktype) to control the `type` attribute. When both options set `type`, a string `linkType` takes precedence. The `attributes` option has no effect when [`runtime`](#runtime) is `false`.

### linkType

- **Type:** `string | false`
- **Default:** `'text/css'`

Sets the `type` attribute on stylesheet `<link>` elements created by the plugin runtime. These elements are used when loading async CSS chunks and applying HMR updates; stylesheet links already present in HTML are not affected.

When omitted, the runtime sets the attribute to `text/css`.

- **String:** Sets the `type` attribute to the provided value.

  ```js
  new rspack.CssExtractRspackPlugin({
    linkType: 'text/css',
  });
  ```

- **`false`:** Disables the plugin's default `type` assignment. The attribute is omitted unless `attributes` supplies a custom `type` value.

  ```js
  new rspack.CssExtractRspackPlugin({
    linkType: false,
  });
  ```

The `linkType` option has no effect when [`runtime`](#runtime) is `false`.

### runtime

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

Controls whether the plugin injects code that loads CSS for async chunks at runtime. Setting it to `false` still emits extracted CSS assets, but your application must load CSS for on-demand chunks itself.

When omitted, the plugin includes the CSS-loading runtime.

When disabled, [`insert`](#insert), [`attributes`](#attributes), and [`linkType`](#linktype) cannot affect async CSS loading because the plugin does not create those `<link>` elements.

```js
new rspack.CssExtractRspackPlugin({
  runtime: false,
});
```

### pathinfo

- **Type:** `boolean`
- **Default:** `true` when [`output.pathinfo`](/config/output.md#outputpathinfo) is enabled, otherwise `false`

Controls whether the plugin adds a comment containing the readable module path before each extracted module. These comments make CSS assets easier to inspect, but increase their size and can expose source paths.

An explicit `pathinfo` value takes precedence over `output.pathinfo`. When omitted, the option inherits the value of `output.pathinfo`.

```js
new rspack.CssExtractRspackPlugin({
  pathinfo: true,
});
```

### enforceRelative

- **Type:** `boolean`
- **Default:** `false`

When the effective loader [`publicPath`](#publicpath) is `'auto'`, Rspack calculates asset URLs relative to the emitted CSS file. If the calculated prefix is empty, this option controls whether the URL starts with `./`. The default produces `url(assets/icon.svg)`; setting it to `true` produces `url(./assets/icon.svg)`.

An explicitly configured loader `publicPath` other than `'auto'` takes precedence, so `enforceRelative` has no effect in that case.

```js
new rspack.CssExtractRspackPlugin({
  enforceRelative: true,
});
```

## Loader options

Set these options on `CssExtractRspackPlugin.loader` in [`module.rules`](/config/module.md#modulerules).

### publicPath

- **Type:**

  ```ts
  type PublicPathFunction = (resourcePath: string, context: string) => string;

  type PublicPath = string | PublicPathFunction;
  ```

- **Default:** [`output.publicPath`](/config/output.md#outputpublicpath)

Sets the public path used for assets referenced in CSS, such as images and fonts. It does not affect the URL of the emitted CSS file itself.

An explicit loader `publicPath` takes precedence over `output.publicPath` for the CSS resource being processed.

When omitted, the loader uses `output.publicPath`.

- **String:** Uses the same public path for every matching CSS resource.

  ```js
  const cssRule = {
    test: /\.css$/i,
    use: [
      {
        loader: rspack.CssExtractRspackPlugin.loader,
        options: {
          publicPath: '/assets/',
        },
      },
      'css-loader',
    ],
  };
  ```

- **Function:** Calls the function at build time with the absolute CSS `resourcePath` and the compiler root `context`. The returned string becomes the public path for that resource.

  ```js
  const cssRule = {
    test: /\.css$/i,
    use: [
      {
        loader: rspack.CssExtractRspackPlugin.loader,
        options: {
          publicPath: (resourcePath, context) =>
            resourcePath.startsWith(context) ? '/assets/' : '/external-assets/',
        },
      },
      'css-loader',
    ],
  };
  ```

### emit

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

Controls whether CSS from the processed resource is included in extracted CSS assets. Setting it to `false` still processes the resource and preserves any CSS Modules exports in JavaScript, but omits its CSS from emitted files.

When omitted, the resource's CSS is included in an emitted CSS asset.

```js
const cssRule = {
  test: /\.css$/i,
  use: [
    {
      loader: rspack.CssExtractRspackPlugin.loader,
      options: {
        emit: false,
      },
    },
    'css-loader',
  ],
};
```

### esModule

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

Controls whether the JavaScript module generated by `CssExtractRspackPlugin.loader` uses ES module or CommonJS syntax. Setting it to `false` uses CommonJS. For consistent output, set css-loader's `esModule` option to the same value.

When omitted, `CssExtractRspackPlugin.loader` uses ES module syntax.

When css-loader generates named CSS Modules exports, those exports remain ES modules. In that case, use [`defaultExport`](#defaultexport) to control whether the loader also generates a default export.

```js
const cssRule = {
  test: /\.css$/i,
  use: [
    {
      loader: rspack.CssExtractRspackPlugin.loader,
      options: {
        esModule: false,
      },
    },
    {
      loader: 'css-loader',
      options: {
        esModule: false,
      },
    },
  ],
};
```

### layer

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

Assigns the processed CSS resource to the specified Rspack module layer. This is a module-graph layer, not a CSS cascade `@layer`. Use it with options such as [`splitChunks.cacheGroups.{cacheGroup}.layer`](/plugins/split-chunks-plugin.md#splitchunkscachegroupscachegrouplayer) to select extracted CSS by layer.

When omitted, this loader does not assign an explicit module layer.

```js
const cssRule = {
  test: /\.css$/i,
  use: [
    {
      loader: rspack.CssExtractRspackPlugin.loader,
      options: {
        layer: 'theme',
      },
    },
    'css-loader',
  ],
};
```

### defaultExport

- **Type:** `boolean`
- **Default:** `false`

When css-loader generates named CSS Modules exports, this option controls whether `CssExtractRspackPlugin.loader` also generates a default object containing all local class names. The named exports are always preserved.

This option has no effect when css-loader does not generate named exports. When omitted, only the named exports are generated in that mode.

```js
const cssRule = {
  test: /\.css$/i,
  use: [
    {
      loader: rspack.CssExtractRspackPlugin.loader,
      options: {
        defaultExport: true,
      },
    },
    {
      loader: 'css-loader',
      options: {
        modules: {
          namedExport: true,
        },
      },
    },
  ],
};
```



---
url: /plugins/html-rspack-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# HtmlRspackPlugin


Rspack only

`rspack.HtmlRspackPlugin` generates HTML files for Rspack builds and injects the JavaScript and CSS files required by their entry points. It can also set the document title, add a favicon, and generate `<base>` and `<meta>` tags.

- [Examples](#examples): Explore common use cases.
- [Options](#options): Review types, defaults, and examples.
- [Template syntax](#template-syntax): See supported interpolation and control statements.
- [Hooks](#hooks): Modify asset URLs, tags, and HTML.

For help choosing between the built-in plugin and the JavaScript `html-rspack-plugin`, see the [HTML guide](/guide/languages/html.md#choose-a-plugin).

## Examples

### Default output

By default, the plugin emits `index.html` with the assets required by every entry point.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  entry: './src/index.js',
  plugins: [new rspack.HtmlRspackPlugin()],
};
```

With the built-in template, the generated `dist/index.html` is equivalent to:

```html
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>rspack</title>
    <script defer src="main.js"></script>
  </head>
  <body></body>
</html>
```

By default, the plugin injects scripts with `defer` into `<head>`. If an entry also produces CSS, the corresponding `<link>` tags are inserted into `<head>`. With multiple entry points, the HTML includes assets from all of them.

### Generate multiple HTML files

To generate a separate HTML file for each entry point, register multiple `rspack.HtmlRspackPlugin` instances:

- Use `filename` to name each HTML file.
- Use `chunks` to select the entry-point assets included in each HTML file.

The following configuration emits `foo.html` and `bar.html`. Each file contains the assets required by its matching entry point, including runtime and shared assets.

```js title="rspack.config.mjs"
export default {
  entry: {
    foo: './foo.js',
    bar: './bar.js',
  },
  plugins: [
    new rspack.HtmlRspackPlugin({
      filename: 'foo.html',
      chunks: ['foo'],
    }),
    new rspack.HtmlRspackPlugin({
      filename: 'bar.html',
      chunks: ['bar'],
    }),
  ],
};
```

### Module scripts

When [`output.module`](/config/output.md#outputmodule) is enabled and `scriptLoading` is not set, the plugin emits `<script type="module">` instead of `<script defer>`:

```js title="rspack.config.mjs"
export default {
  output: {
    module: true,
  },
  plugins: [new rspack.HtmlRspackPlugin()],
};
```

```html
<script src="main.js" type="module"></script>
```

### Production minification

In production mode (`mode: 'production'`), the plugin minifies the generated HTML when `minify` is not set. In other modes, HTML is minified only when `minify` is enabled explicitly.

```js title="rspack.config.mjs"
export default {
  mode: 'production',
  plugins: [new rspack.HtmlRspackPlugin()],
};
```

### Use a template file

If `src/index.ejs` exists in the Rspack [`context`](/config/context.md), the plugin uses it as the template automatically. Otherwise, it uses the built-in template.

To customize the HTML structure, you can also use `template` to specify an HTML file. The plugin injects the required JavaScript, CSS, and favicon tags into it.

```html title="index.html"
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title><%= htmlRspackPlugin.options.title %></title>
  </head>
  <body></body>
</html>
```

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.HtmlRspackPlugin({
      title: 'My HTML Template',
      template: 'index.html',
    }),
  ],
};
```

### Use template string

You can also provide the HTML template directly through `templateContent`:

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.HtmlRspackPlugin({
      title: 'My HTML Template',
      templateContent: `
        <!DOCTYPE html>
        <html>
          <head>
            <title><%= htmlRspackPlugin.options.title %></title>
          </head>
          <body></body>
        </html>
      `,
    }),
  ],
};
```

### Use template function

For dynamically generated template content, use a function in either of these forms:

- Pass the function directly to `templateContent`:

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.HtmlRspackPlugin({
      title: 'My HTML Template',
      templateContent: ({ htmlRspackPlugin }) => `
        <!DOCTYPE html>
        <html>
          <head>
            <title>${htmlRspackPlugin.options.title}</title>
          </head>
          <body></body>
        </html>
      `,
    }),
  ],
};
```

- Specify a `.js` or `.cjs` file in `template`:

```js title="template.js"
module.exports = ({ htmlRspackPlugin }) => `
  <!DOCTYPE html>
  <html>
    <head>
      <title>${htmlRspackPlugin.options.title}</title>
    </head>
    <body></body>
  </html>
`;
```

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.HtmlRspackPlugin({
      title: 'My HTML Template',
      template: 'template.js',
    }),
  ],
};
```

### Template parameters

Use `templateParameters` to customize the values passed when rendering an HTML template. Templates receive the following serializable parameters by default:

- `htmlRspackPlugin`: Data exposed by the plugin
  - `htmlRspackPlugin.options`: Normalized plugin options
  - `htmlRspackPlugin.tags`: Generated tags prepared for insertion
    - `htmlRspackPlugin.tags.headTags`: List of `<base>`, `<meta>`, `<title>`, `<link>`, and `<script>` tags for injection in `<head>`
    - `htmlRspackPlugin.tags.bodyTags`: List of `<script>` tags for injection in `<body>`
  - `htmlRspackPlugin.files`: Asset URLs selected for the current HTML file
    - `htmlRspackPlugin.files.js`: Selected JavaScript asset URLs
    - `htmlRspackPlugin.files.css`: Selected CSS asset URLs
    - `htmlRspackPlugin.files.favicon`: Generated favicon URL when `favicon` is configured
    - `htmlRspackPlugin.files.publicPath`: Effective public path used for asset URLs
- `rspackConfig`: Selected Rspack settings
  - `rspackConfig.mode`: Current build mode
  - `rspackConfig.output.publicPath`: Effective public path for the current HTML file, including a [`publicPath`](#publicpath) override
  - `rspackConfig.output.crossOriginLoading`: Configured cross-origin loading value

When a JavaScript function renders the template, it can also access the Rspack `compilation` object. That object is not passed when `templateParameters` is `false` or a function.

In a built-in template, use EJS-style interpolation to read these parameters:

```js title="rspack.config.mjs"
export default {
  mode: 'development',
  plugins: [
    new rspack.HtmlRspackPlugin({
      title: 'My application',
      templateContent: `
        <!doctype html>
        <html>
          <head></head>
          <body>
            <h1><%- htmlRspackPlugin.options.title %></h1>
            <p>Mode: <%- rspackConfig.mode %></p>
          </body>
        </html>
      `,
    }),
  ],
};
```

In a JavaScript template function, the parameters are passed as an ordinary JavaScript object:

```js title="rspack.config.mjs"
export default {
  plugins: [
    new rspack.HtmlRspackPlugin({
      templateContent: ({ htmlRspackPlugin }) => `
        <!doctype html>
        <html>
          <head></head>
          <body>
            <p>Scripts: ${htmlRspackPlugin.files.js.join(', ')}</p>
          </body>
        </html>
      `,
    }),
  ],
};
```

In templates rendered by the built-in engine, call `toHtml()` to convert a tag or tag list to HTML. In JavaScript template functions, tags and tag lists provide `toString()` and can be interpolated directly.

:::warning
If the template inserts `htmlRspackPlugin.tags` manually, set `inject` to `false`; otherwise, the plugin inserts those tags twice.
:::

:::info Differences
Compared with HtmlWebpackPlugin:

- Template paths do not support loader syntax such as `loader!./template.html`
- The `compilation` object is only available when [using a template function](#use-template-function), with the `templateParameters` restrictions described above

:::

## Options

Pass the following options to `new rspack.HtmlRspackPlugin()`. All examples reuse the `rspack` import from the first example.

### title

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

Sets the `<title>` of the generated HTML. When automatic injection is enabled, the plugin replaces an existing `<title>` in the template or adds one to `<head>`.

When omitted, a custom template keeps its own title. The built-in template uses `rspack`. Setting [`inject`](#inject) to `false` prevents `title` from being applied automatically, but the value remains available as `htmlRspackPlugin.options.title`.

```js
new rspack.HtmlRspackPlugin({
  title: 'My application',
});
```

Generated HTML fragment:

```html
<title>My application</title>
```

### filename

- **Type:**

  ```ts
  type HtmlFilenameFunction = (entry: string) => string;
  type HtmlFilename = string | HtmlFilenameFunction;
  ```

- **Default:** `'index.html'`

Sets the HTML asset path and filename relative to [`output.path`](/config/output.md#outputpath). When omitted, the plugin emits `index.html` in the output directory.

- **String:** Emits the HTML at the specified path. The value can include a subdirectory and filename placeholders such as `[name]` and `[contenthash]`. A `[name]` placeholder emits one HTML file for each statically configured entry.

  ```js
  new rspack.HtmlRspackPlugin({
    filename: 'pages/index.html',
  });
  ```

- **Function:** Calls the function once for each statically configured entry, passing its name as the argument. The return value becomes the corresponding HTML filename.

  ```js
  export default {
    entry: {
      app: './src/app.js',
      admin: './src/admin.js',
    },
    plugins: [
      new rspack.HtmlRspackPlugin({
        filename: (entry) => `pages/${entry}.html`,
      }),
    ],
  };
  ```

The `[name]` and function forms do not support a function-valued Rspack [`entry`](/config/entry.md). They only control HTML filenames; every generated file still receives the same entry assets selected by [`chunks`](#chunks) and [`excludeChunks`](#excludechunks). Register separate plugin instances when each page needs a different asset set.

### template

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

Sets the template file. Relative paths are resolved from the Rspack [`context`](/config/context.md). [`templateContent`](#templatecontent) takes precedence when both options are set.

When omitted, the plugin looks for `src/index.ejs` in `context` and falls back to its built-in HTML document if the file does not exist.

- **HTML file:** Reads the file as text, renders it with the built-in [template syntax](#template-syntax), and injects the generated tags.

  ```html title="index.html"
  <!doctype html>
  <html>
    <head>
      <title><%= htmlRspackPlugin.options.title %></title>
    </head>
    <body></body>
  </html>
  ```

  ```js
  new rspack.HtmlRspackPlugin({
    title: 'My application',
    template: './index.html',
  });
  ```

- **JavaScript module:** A path ending in `.js` or `.cjs` is loaded as a CommonJS module. Its exported function receives the template parameters and returns the HTML string, either directly or through a promise.

  ```js title="template.cjs"
  module.exports = ({ htmlRspackPlugin }) => `
    <!doctype html>
    <html>
      <head><title>${htmlRspackPlugin.options.title}</title></head>
      <body></body>
    </html>
  `;
  ```

  ```js
  new rspack.HtmlRspackPlugin({
    title: 'My application',
    template: './template.cjs',
  });
  ```

### templateContent

- **Type:**

  ```ts
  type TemplateRenderFunction = (
    params: Record<string, any>,
  ) => string | Promise<string>;

  type TemplateContent = string | TemplateRenderFunction;
  ```

- **Default:** `undefined`

Provides the template directly without reading a file. When set, it takes precedence over [`template`](#template) and the default template lookup.

- **String:** Renders the string with the built-in [template syntax](#template-syntax), then injects the generated tags.

  ```js
  new rspack.HtmlRspackPlugin({
    templateContent: `
      <!doctype html>
      <html>
        <head><title>My application</title></head>
        <body></body>
      </html>
    `,
  });
  ```

- **Function:** Calls the function with the final template parameters. The returned string becomes the HTML template result and is not processed as EJS. The function can be asynchronous.

  ```js
  new rspack.HtmlRspackPlugin({
    title: 'My application',
    templateContent: ({ htmlRspackPlugin }) => `
      <!doctype html>
      <html>
        <head><title>${htmlRspackPlugin.options.title}</title></head>
        <body></body>
      </html>
    `,
  });
  ```

When omitted, the plugin first uses [`template`](#template) if it is set. Otherwise, it looks for `src/index.ejs` and then falls back to the built-in document.

### templateParameters

- **Type:**

  ```ts
  type TemplateParamFunction = (
    params: Record<string, any>,
  ) => Record<string, any> | Promise<Record<string, any>>;

  type TemplateParameters =
    Record<string, string> | boolean | TemplateParamFunction;
  ```

- **Default:** `undefined`

Controls the parameters passed to an HTML template or template function. The built-in values are described in [Template parameters](#template-parameters).

- **Object:** Merges the object's string properties into the built-in parameters. Properties with the same name replace the built-in value.

  ```js
  new rspack.HtmlRspackPlugin({
    templateContent: '<main><%= environment %></main>',
    templateParameters: {
      environment: 'production',
    },
  });
  ```

- **Boolean:** `true` preserves the built-in parameters and is equivalent to omitting the option. `false` passes an empty object to the template.

  ```js
  new rspack.HtmlRspackPlugin({
    templateContent: () => '<main>Static page</main>',
    templateParameters: false,
  });
  ```

- **Function:** Calls the function with the serializable built-in parameters and uses its returned object as the complete final parameter object. Return the original properties when the template still needs them. The function can be asynchronous.

  ```js
  new rspack.HtmlRspackPlugin({
    templateContent: ({ buildName }) => `<main>${buildName}</main>`,
    templateParameters: (params) => ({
      ...params,
      buildName: 'documentation',
    }),
  });
  ```

The `compilation` parameter is available only to a JavaScript template function when `templateParameters` is omitted, `true`, or an object. It is not passed to string templates, a `templateParameters` function, or a template function when `templateParameters` is `false`.

### inject

- **Type:** `boolean | 'head' | 'body'`
- **Default:** `true`

Controls automatic insertion of the tags generated by the plugin. When injection is enabled, stylesheets, the title, `<base>`, `<meta>`, and favicon tags are inserted into `<head>`. The `'head'` and `'body'` values change only the placement of `<script>` tags.

- **`true`:** Inserts scripts into `<body>` when [`scriptLoading`](#scriptloading) is `'blocking'`; otherwise, inserts them into `<head>`. This is also the behavior when `inject` is omitted.

  ```js
  new rspack.HtmlRspackPlugin({
    inject: true,
  });
  ```

- **`'head'` or `'body'`:** Inserts scripts into the selected element, regardless of `scriptLoading`. Stylesheet and metadata tags remain in `<head>`.

  ```js
  new rspack.HtmlRspackPlugin({
    inject: 'body',
  });
  ```

- **`false`:** Disables automatic insertion of all generated tags, including scripts, stylesheets, title, `<base>`, `<meta>`, and favicon tags. Tags already present in the template are not removed.

  ```js
  new rspack.HtmlRspackPlugin({
    inject: false,
  });
  ```

With `false`, the generated tags remain available through `htmlRspackPlugin.tags`. A template rendered by the built-in engine can insert them with `toHtml()`; a JavaScript template function can interpolate them directly. A configured favicon is still emitted as an asset.

### publicPath

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

Sets the URL prefix for JavaScript, CSS, and favicon URLs in the generated HTML. The plugin adds a trailing slash when needed. This option takes precedence over [`output.publicPath`](/config/output.md#outputpublicpath).

When omitted, the plugin uses `output.publicPath`. An `auto` output public path is resolved relative to each HTML filename, so an HTML file in a subdirectory can reference assets with paths such as `../main.js`.

```js
new rspack.HtmlRspackPlugin({
  publicPath: '/assets/',
});
```

### base

- **Type:**

  ```ts
  type HtmlBase =
    | string
    | {
        href?: string;
        target?: '_self' | '_blank' | '_parent' | '_top';
      };
  ```

- **Default:** `undefined`

Creates a [`<base>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base) tag in `<head>`. When omitted, no base tag is generated. [`inject: false`](#inject) prevents the tag from being inserted automatically.

- **String:** Uses the string as the `href` attribute.

  ```js
  new rspack.HtmlRspackPlugin({
    base: 'https://example.com/app/',
  });
  ```

  Generated HTML fragment:

  ```html
  <base href="https://example.com/app/" />
  ```

- **Object:** Sets the optional `href` and `target` attributes. An object with neither attribute produces no tag.

  ```js
  new rspack.HtmlRspackPlugin({
    base: {
      href: 'https://example.com/app/',
      target: '_blank',
    },
  });
  ```

  Generated HTML fragment:

  ```html
  <base href="https://example.com/app/" target="_blank" />
  ```

### scriptLoading

- **Type:** `'blocking' | 'defer' | 'module' | 'systemjs-module'`
- **Default:** `'module'` when `output.module` is enabled, otherwise `'defer'`

Sets the attributes on generated `<script>` tags and determines their default injection position. An explicit [`inject: 'head'`](#inject) or `inject: 'body'` overrides that position. This option does not change the format of the emitted JavaScript.

- **`'blocking'`:** Adds no loading attribute. With the default `inject`, scripts are inserted into `<body>`.

  ```js
  new rspack.HtmlRspackPlugin({
    scriptLoading: 'blocking',
  });
  ```

  Generated HTML fragment:

  ```html
  <script src="main.js"></script>
  ```

- **`'defer'`:** Adds the boolean `defer` attribute. With the default `inject`, scripts are inserted into `<head>`.

  ```js
  new rspack.HtmlRspackPlugin({
    scriptLoading: 'defer',
  });
  ```

  Generated HTML fragment:

  ```html
  <script defer src="main.js"></script>
  ```

- **`'module'`:** Adds `type="module"`. Module scripts are deferred by browsers, and the default `inject` inserts them into `<head>`.

  ```js
  new rspack.HtmlRspackPlugin({
    scriptLoading: 'module',
  });
  ```

  Generated HTML fragment:

  ```html
  <script src="main.js" type="module"></script>
  ```

- **`'systemjs-module'`:** Adds `type="systemjs-module"`. The default `inject` inserts these scripts into `<head>`.

  ```js
  new rspack.HtmlRspackPlugin({
    scriptLoading: 'systemjs-module',
  });
  ```

  Generated HTML fragment:

  ```html
  <script src="main.js" type="systemjs-module"></script>
  ```

### chunks

- **Type:** `string[]`
- **Default:** `undefined`

Selects entry points whose JavaScript and CSS files are included in the HTML. Each value is compared with an entry point name using exact string equality; it does not match an arbitrary chunk ID, asset filename, or module path. Unknown names are ignored.

When omitted, every entry point is selected before [`excludeChunks`](#excludechunks) is applied. Selecting an entry point also includes the runtime and shared files required by that entry.

With the default [`chunksSortMode: 'auto'`](#chunkssortmode), `chunks` first limits the entry points and `excludeChunks` then removes matches. With `'manual'`, a provided `chunks` array instead becomes the final ordered entry list. If `chunks` is omitted, `excludeChunks` still filters the compilation's entry point order.

```js
export default {
  entry: {
    app: './src/app.js',
    admin: './src/admin.js',
  },
  plugins: [
    new rspack.HtmlRspackPlugin({
      chunks: ['app'],
    }),
  ],
};
```

### excludeChunks

- **Type:** `string[]`
- **Default:** `undefined`

Excludes entry points from the generated HTML. Each value is compared with an entry point name using exact string equality; it does not match asset filenames, module paths, or non-entry chunks. Unknown names have no effect.

In the default [`chunksSortMode: 'auto'`](#chunkssortmode), exclusions are applied after [`chunks`](#chunks), so an entry present in both arrays is excluded. With `'manual'`, a provided `chunks` array is the final ordered list and `excludeChunks` is not applied; when `chunks` is omitted, exclusions still apply to the compilation's entry point order. If `excludeChunks` is omitted, no selected entry point is excluded.

```js
export default {
  entry: {
    app: './src/app.js',
    admin: './src/admin.js',
  },
  plugins: [
    new rspack.HtmlRspackPlugin({
      excludeChunks: ['admin'],
    }),
  ],
};
```

### chunksSortMode

- **Type:** `'auto' | 'manual'`
- **Default:** `'auto'`

Controls the order in which selected entry points contribute their files to the generated tags.

- **`'auto'`:** Uses the compilation's entry point order after applying `chunks` and `excludeChunks`.

  ```js
  new rspack.HtmlRspackPlugin({
    chunksSortMode: 'auto',
  });
  ```

- **`'manual'`:** Uses the order of [`chunks`](#chunks), ignoring unknown entry names. When `chunks` is omitted, it uses the compilation's entry point order after applying [`excludeChunks`](#excludechunks). When `chunks` is present, `excludeChunks` is not applied.

  ```js
  new rspack.HtmlRspackPlugin({
    chunks: ['admin', 'app'],
    chunksSortMode: 'manual',
  });
  ```

### minify

- **Type:** `boolean`
- **Default:** `true` in production mode, otherwise `false`

Controls whether the generated HTML is minified after template rendering and tag injection. An explicit value overrides the mode-dependent default.

```js
new rspack.HtmlRspackPlugin({
  minify: false,
});
```

### favicon

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

Sets the path of a favicon file. Relative paths are resolved from the Rspack [`context`](/config/context.md). The plugin emits the file at the output root using its basename and generates a `<link rel="icon">` tag whose URL follows [`publicPath`](#publicpath).

When omitted, no favicon asset or tag is generated. With [`inject: false`](#inject), the asset is still emitted and exposed as `htmlRspackPlugin.files.favicon`, but the `<link>` tag is not inserted automatically.

```js
new rspack.HtmlRspackPlugin({
  favicon: './src/favicon.ico',
});
```

Generated HTML fragment:

```html
<link href="favicon.ico" rel="icon" />
```

### meta

- **Type:**

  ```ts
  type HtmlMeta = Record<string, string | Record<string, string>>;
  ```

- **Default:** `{}`

Creates additional `<meta>` tags in `<head>`. Each top-level key becomes the default `name` attribute. The built-in template's `<meta charset="utf-8">` is independent of this option. When the object is empty or the option is omitted, no additional meta tags are generated. [`inject: false`](#inject) prevents them from being inserted automatically.

- **String value:** Uses the top-level key as `name` and the string as `content`.

  ```js
  new rspack.HtmlRspackPlugin({
    meta: {
      viewport: 'width=device-width,initial-scale=1',
    },
  });
  ```

  Generated HTML fragment:

  ```html
  <meta content="width=device-width,initial-scale=1" name="viewport" />
  ```

- **Object value:** Adds every property as an attribute. A `name` property overrides the name derived from the top-level key.

  ```js
  new rspack.HtmlRspackPlugin({
    meta: {
      viewport: {
        name: 'viewport',
        content: 'width=device-width,initial-scale=1',
        'data-origin': 'rspack',
      },
    },
  });
  ```

  Generated HTML fragment:

  ```html
  <meta
    content="width=device-width,initial-scale=1"
    data-origin="rspack"
    name="viewport"
  />
  ```

### hash

- **Type:** `boolean`
- **Default:** `undefined`

If `true`, appends the Rspack compilation hash as a query string to generated JavaScript, CSS, and favicon URLs. This changes references in the HTML, not the emitted asset filenames. When omitted or `false`, the plugin leaves those URLs unchanged.

```js
new rspack.HtmlRspackPlugin({
  hash: true,
});
```

## Template syntax

The built-in template engine supports EJS-style interpolation and basic control flow, but it does not execute arbitrary JavaScript. The following examples show the commonly used forms.

#### Escaped output `<%-`

Escapes the content within the interpolation:

```html title="ejs"
<p>Hello, <%- name %>.</p>
<p>Hello, <%- 'the Most Honorable ' + name %>.</p>
```

```json title="locals"
{
  "name": "Rspack<y>"
}
```

```html title="html"
<p>Hello, Rspack&lt;y&gt;.</p>
<p>Hello, the Most Honorable Rspack&lt;y&gt;.</p>
```

#### Unescaped output `<%=`

Does not escape the content within the interpolation:

```html title="ejs"
<p>Hello, <%- myHtml %>.</p>
<p>Hello, <%= myHtml %>.</p>

<p>Hello, <%- myMaliciousHtml %>.</p>
<p>Hello, <%= myMaliciousHtml %>.</p>
```

```json title="locals"
{
  "myHtml": "<strong>Rspack</strong>",
  "myMaliciousHtml": "</p><script>document.write()</script><p>"
}
```

```html title="html"
<p>Hello, &lt;strong&gt;Rspack&lt;/strong&gt;.</p>
<p>Hello, <strong>Rspack</strong>.</p>

<p>Hello, &lt;/p&gt;&lt;script&gt;document.write()&lt;/script&gt;&lt;p&gt;.</p>
<p>Hello,</p>
<script>
  document.write();
</script>
<p>.</p>
```

#### Control statements

The following example combines `for in` iteration with an `if` condition:

```txt title="ejs"
<% for tag in htmlRspackPlugin.tags.headTags { %>
  <% if tag.tagName=="script" { %>
    <%= toHtml(tag) %>
  <% } %>
<% } %>
```

## Hooks

HtmlRspackPlugin exposes hooks for modifying generated tags and HTML. Call `rspack.HtmlRspackPlugin.getCompilationHooks` to access them:

Hook data exposes the original constructor options as `data.plugin.options`. Additional custom fields are preserved there for hook consumers but do not affect HTML generation by themselves.

```js title="rspack.config.mjs"
const HtmlModifyPlugin = {
  apply(compiler) {
    compiler.hooks.compilation.tap('HtmlModifyPlugin', (compilation) => {
      const hooks = rspack.HtmlRspackPlugin.getCompilationHooks(compilation);
      // hooks.beforeAssetTagGeneration.tapPromise()
      // hooks.alterAssetTags.tapPromise()
      // hooks.alterAssetTagGroups.tapPromise()
      // hooks.afterTemplateExecution.tapPromise()
      // hooks.beforeEmit.tapPromise()
      // hooks.afterEmit.tapPromise()
    });
  },
};

export default {
  plugins: [new rspack.HtmlRspackPlugin(), HtmlModifyPlugin],
};
```

### beforeAssetTagGeneration

This hook runs after the plugin collects asset URLs from the compilation and before it creates tags.

Modify `assets.js`, `assets.css`, or `assets.favicon` to add or replace URLs used to create tags. Values added by the hook are used as-is: the hook does not prepend `publicPath` or emit the referenced files.

- **Type:** `AsyncSeriesWaterfallHook<[BeforeAssetTagGenerationData]>`
- **Parameters:**
  ```ts
  type BeforeAssetTagGenerationData = {
    assets: {
      publicPath: string;
      js: Array<string>;
      css: Array<string>;
      favicon?: string;
      jsIntegrity?: Array<string | undefined | null>;
      cssIntegrity?: Array<string | undefined | null>;
    };
    outputName: string;
    plugin: {
      options: HtmlRspackPluginOptions;
    };
  };
  ```

:::warning
Only changes to `assets.js`, `assets.css`, and `assets.favicon` affect the tags generated automatically by the plugin. Other fields do not affect automatic tag generation, but templates can still read them through `htmlRspackPlugin.files`.
:::

The following code adds the URL `extra-script.js`, which produces a `<script defer src="extra-script.js"></script>` tag in the final HTML.

```js title="rspack.config.mjs"
const AddScriptPlugin = {
  apply(compiler) {
    compiler.hooks.compilation.tap('AddScriptPlugin', (compilation) => {
      const hooks = rspack.HtmlRspackPlugin.getCompilationHooks(compilation);
      hooks.beforeAssetTagGeneration.tapPromise(
        'AddScriptPlugin',
        async (data) => {
          data.assets.js.push('extra-script.js');
        },
      );
    });
  },
};

export default {
  plugins: [new rspack.HtmlRspackPlugin(), AddScriptPlugin],
};
```

### alterAssetTags

This hook runs after asset tags are created and before they are assigned to `<head>` or `<body>`.

Modify `assetTags` to add, remove, or update tags.

- **Type:** `AsyncSeriesWaterfallHook<[AlterAssetTagsData]>`
- **Parameters:**

  ```ts
  type HtmlTag = {
    tagName: string;
    attributes: Record<string, string | boolean | undefined | null>;
    voidTag: boolean;
    innerHTML?: string;
    asset?: string;
  };

  type AlterAssetTagsData = {
    assetTags: {
      scripts: Array<HtmlTag>;
      styles: Array<HtmlTag>;
      meta: Array<HtmlTag>;
    };
    publicPath: string;
    outputName: string;
    plugin: {
      options: HtmlRspackPluginOptions;
    };
  };
  ```

:::warning
Only changes to `assetTags` affect the generated HTML. Changes to other fields are ignored by this plugin.
:::

Attribute names are normalized to lowercase. Attribute values are handled as follows:

- **`true`:** Adds a valueless attribute, for example `<script defer specialattribute src="main.js"></script>`.
- **String:** Adds an attribute with that value, for example `<script defer specialattribute="some value" src="main.js"></script>`.
- **`false`, `undefined`, or `null`:** Removes the attribute.

The following code adds the `specialAttribute` attribute to every `<script>` tag:

```js title="rspack.config.mjs"
const AddAttributePlugin = {
  apply(compiler) {
    compiler.hooks.compilation.tap('AddAttributePlugin', (compilation) => {
      const hooks = rspack.HtmlRspackPlugin.getCompilationHooks(compilation);
      hooks.alterAssetTags.tapPromise('AddAttributePlugin', async (data) => {
        data.assetTags.scripts = data.assetTags.scripts.map((tag) => {
          if (tag.tagName === 'script') {
            tag.attributes.specialAttribute = true;
          }
          return tag;
        });
      });
    });
  },
};

export default {
  plugins: [new rspack.HtmlRspackPlugin(), AddAttributePlugin],
};
```

### alterAssetTagGroups

This hook runs after tags are grouped for `<head>` and `<body>`, but before the template is rendered.

Modify `headTags` and `bodyTags` to move or update the grouped tags.

- **Type:** `AsyncSeriesWaterfallHook<[AlterAssetTagGroupsData]>`
- **Parameters:**
  ```ts
  type AlterAssetTagGroupsData = {
    headTags: Array<HtmlTag>;
    bodyTags: Array<HtmlTag>;
    publicPath: string;
    outputName: string;
    plugin: {
      options: HtmlRspackPluginOptions;
    };
  };
  ```

:::warning
Only changes to `headTags` and `bodyTags` affect the generated HTML. Changes to other fields are ignored by this plugin.
:::

The following code moves all `<script>` tags from `<body>` to `<head>`:

```js title="rspack.config.mjs"
const MoveTagsPlugin = {
  apply(compiler) {
    compiler.hooks.compilation.tap('MoveTagsPlugin', (compilation) => {
      const hooks = rspack.HtmlRspackPlugin.getCompilationHooks(compilation);
      hooks.alterAssetTagGroups.tapPromise('MoveTagsPlugin', async (data) => {
        const scripts = data.bodyTags.filter((tag) => tag.tagName === 'script');
        data.headTags.push(...scripts);
        data.bodyTags = data.bodyTags.filter((tag) => tag.tagName !== 'script');
      });
    });
  },
};

export default {
  plugins: [
    new rspack.HtmlRspackPlugin({
      inject: 'body',
    }),
    MoveTagsPlugin,
  ],
};
```

### afterTemplateExecution

This hook runs after template rendering and before automatic tag injection.

Modify `html`, `headTags`, or `bodyTags` to change the rendered template or the tags that will be injected.

With a function-valued `templateContent` or a `.js`/`.cjs` `template`, `html` is the string returned by the template function. With a string or markup file template, it is the result produced by the built-in template engine.

- **Type:** `AsyncSeriesWaterfallHook<[AfterTemplateExecutionData]>`
- **Parameters:**
  ```ts
  type AfterTemplateExecutionData = {
    html: string;
    headTags: Array<HtmlTag>;
    bodyTags: Array<HtmlTag>;
    outputName: string;
    plugin: {
      options: HtmlRspackPluginOptions;
    };
  };
  ```

:::warning
Only changes to `html`, `headTags`, and `bodyTags` affect the generated HTML. Changes to other fields are ignored by this plugin.
:::

The following code adds `Injected by plugin` at the end of `<body>`. The tags are then injected after that text, producing `Injected by plugin<script defer src="main.js"></script></body>`:

```js title="rspack.config.mjs"
const InjectContentPlugin = {
  apply(compiler) {
    compiler.hooks.compilation.tap('InjectContentPlugin', (compilation) => {
      const hooks = rspack.HtmlRspackPlugin.getCompilationHooks(compilation);
      hooks.afterTemplateExecution.tapPromise(
        'InjectContentPlugin',
        async (data) => {
          data.html = data.html.replace('</body>', 'Injected by plugin</body>');
        },
      );
    });
  },
};

export default {
  plugins: [
    new rspack.HtmlRspackPlugin({
      inject: 'body',
    }),
    InjectContentPlugin,
  ],
};
```

### beforeEmit

This hook runs immediately before the HTML asset is emitted and is the final chance to modify its content.

- **Type:** `AsyncSeriesWaterfallHook<[BeforeEmitData]>`
- **Parameters:**
  ```ts
  type BeforeEmitData = {
    html: string;
    outputName: string;
    plugin: {
      options: HtmlRspackPluginOptions;
    };
  };
  ```

:::warning
Only changes to `html` affect the emitted asset. Changes to other fields are ignored by this plugin.
:::

The following code adds `Injected by plugin` at the end of `<body>`. The final sequence is `<script defer src="main.js"></script>Injected by plugin</body>`:

```js title="rspack.config.mjs"
const InjectContentPlugin = {
  apply(compiler) {
    compiler.hooks.compilation.tap('InjectContentPlugin', (compilation) => {
      const hooks = rspack.HtmlRspackPlugin.getCompilationHooks(compilation);
      hooks.beforeEmit.tapPromise('InjectContentPlugin', async (data) => {
        data.html = data.html.replace('</body>', 'Injected by plugin</body>');
      });
    });
  },
};

export default {
  plugins: [
    new rspack.HtmlRspackPlugin({
      inject: 'body',
    }),
    InjectContentPlugin,
  ],
};
```

### afterEmit

This hook runs after the HTML asset is emitted and is intended for notification only.

- **Type:** `AsyncSeriesWaterfallHook<[AfterEmitData]>`
- **Parameters:**
  ```ts
  type AfterEmitData = {
    outputName: string;
    plugin: {
      options: HtmlRspackPluginOptions;
    };
  };
  ```



---
url: /plugins/subresource-integrity-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# SubresourceIntegrityPlugin


[Added in v1.7.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.7.0)Rspack only

The `rspack.SubresourceIntegrityPlugin` is a plugin for enabling Subresource Integrity in Rspack.

> In versions 1.2.4 to 1.6.8, you can use `rspack.experiments.SubresourceIntegrityPlugin`.

## What is SRI

Subresource Integrity (SRI) is a security feature that enables browsers to verify that resources they fetch (for example, from a CDN) are delivered without unexpected manipulation. It works by allowing you to provide a cryptographic hash that a fetched resource must match.

For `<script>` tags, the result is to refuse to execute the code; for CSS links, the result is not to load the styles.

For more on subresource integrity, see [Subresource Integrity - MDN](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity).

## Features

### Support for HTML plugin

The plugin supports integration with [`HtmlRspackPlugin`](/plugins/html-rspack-plugin.md) and [`html-webpack-plugin`](https://github.com/jantimon/html-webpack-plugin). It will automatically set the `integrity` and `crossorigin` attributes for the injected tags.

### Support for code splitting

The plugin supports code splitting. When you use dynamic imports, the plugin will automatically set the `integrity` and `crossorigin` attributes for the generated chunk loading tags.

## Examples

You can use the plugin by importing it from `@rspack/core`:

```js title="rspack.config.mjs"
import { SubresourceIntegrityPlugin } from '@rspack/core';
```

Or:

```js title="rspack.config.cjs"
const { SubresourceIntegrityPlugin } = require('@rspack/core');
```

### Recommended Rspack configuration

The [output.crossOriginLoading](/config/output.md#outputcrossoriginloading) option is required for SRI to work:

```js title="rspack.config.mjs"
import { SubresourceIntegrityPlugin } from '@rspack/core';

export default {
  output: {
    crossOriginLoading: 'anonymous',
  },
  plugins: [new SubresourceIntegrityPlugin()],
};
```

### With HTML plugin

When the HTML plugin([`HtmlRspackPlugin`](/plugins/html-rspack-plugin.md) or [`html-webpack-plugin`](https://github.com/jantimon/html-webpack-plugin)) is used, the `integrity` and `crossorigin` attributes will be set automatically.

The SubresourceIntegrityPlugin will interact with [`HtmlRspackPlugin`](/plugins/html-rspack-plugin.md) by default:

```js title="rspack.config.mjs"
import { SubresourceIntegrityPlugin, HtmlRspackPlugin } from '@rspack/core';

export default {
  plugins: [new SubresourceIntegrityPlugin(), new HtmlRspackPlugin()],
};
```

If [`html-webpack-plugin`](https://github.com/jantimon/html-webpack-plugin) is used, the `htmlPlugin` option should be specified to the path of it:

```js title="rspack.config.mjs"
import HtmlWebpackPlugin from 'html-webpack-plugin';
import { SubresourceIntegrityPlugin } from '@rspack/core';

export default {
  plugins: [
    new SubresourceIntegrityPlugin({
      // the path to the html-webpack-plugin
      htmlPlugin: import.meta.resolve('html-webpack-plugin'),
    }),
    new HtmlWebpackPlugin(),
  ],
};
```

### With HTML plugin and `inject: false`

If you use the HTML plugin with `inject: false`, you need to set the `integrity` and `crossorigin` attributes in your template manually.

With [`HtmlRspackPlugin`](/plugins/html-rspack-plugin.md), the grammar of the template is a bit different with `.ejs`(see [here](/plugins/html-rspack-plugin.md#template-syntax)), you can inject them like this:

```ejs title="index.ejs"
<% for src in htmlRspackPlugin.files.js { %>
  <script src="<%= src %>"
    integrity="<%= htmlRspackPlugin.files.jsIntegrity[index] %>"
    crossorigin="<%= rspackConfig.output.crossOriginLoading %>"
  ></script>
<% } %>

<% for _ in htmlRspackPlugin.files.css { %>
  <link href="<%= htmlRspackPlugin.files.css[index] %>"
    integrity="<%= htmlRspackPlugin.files.cssIntegrity[index] %>"
    crossorigin="<%= rspackConfig.output.crossOriginLoading %>"
    rel="stylesheet"
  />
<% } %>
```

With [`html-webpack-plugin`](https://github.com/jantimon/html-webpack-plugin), you can inject them like this:

```ejs title="index.ejs"
<% for (let index in htmlWebpackPlugin.files.js) { %>
  <script
    src="<%= htmlWebpackPlugin.files.js[index] %>"
    integrity="<%= htmlWebpackPlugin.files.jsIntegrity[index] %>"
    crossorigin="<%= webpackConfig.output.crossOriginLoading %>"
  ></script>
<% } %>

<% for (let index in htmlWebpackPlugin.files.css) { %>
  <link
    rel="stylesheet"
    href="<%= htmlWebpackPlugin.files.css[index] %>"
    integrity="<%= htmlWebpackPlugin.files.cssIntegrity[index] %>"
    crossorigin="<%= webpackConfig.output.crossOriginLoading %>"
  />
<% } %>
```

### Without HTML plugin

The `integrity` can also be obtained from `stats.assets`. For example:

```js
compiler.hooks.done.tap('MyPlugin', (stats) => {
  const integrityValues = stats
    .toJson()
    .assets.map((asset) => [asset.name, asset.integrity]);
});
```

:::tip
Note that when you add the `integrity` attribute on your `link` and
`script` tags, you're also required to set the `crossorigin`
attribute. It is recommended to set this attribute to the same value
as the Rspack `output.crossOriginLoading` configuration option.
:::

## Options

### hashFuncNames

- **Type:** `Array<"sha256" | "sha384" | "sha512">`
- **Default:** `["sha384"]`

An array of strings, each specifying the name of a hash function to be
used for calculating integrity hash values. Only supports `sha256`, `sha384`, and `sha512` yet.

> See [SRI: Cryptographic hash functions](http://www.w3.org/TR/SRI/#cryptographic-hash-functions) for more details.

### enabled

- **Type:** `"auto" | boolean`

- **Default:** `"auto"`

- `auto` is the default value, which means the plugin is enabled when [Rspack mode](/config/mode.md) is `production` or `none`, and disabled when it is `development`.

- `true` means the plugin is enabled in any mode.

- `false` means the plugin is disabled in any mode.

### htmlPlugin

- **Type:** `string`
- **Default:** `"HtmlRspackPlugin"`

The path to the HTML plugin, defaults to `"HtmlRspackPlugin"` which means the native HTML plugin of Rspack. If you are using the `html-webpack-plugin`, you can set this option to the path of it. It is recommended to set the absolute path to make sure the plugin can be found.

## More information

You can find more information about Subresource Integrity in the following resources:

- [webpack-subresource-integrity](https://github.com/waysact/webpack-subresource-integrity/blob/main/webpack-subresource-integrity/README.md)
- [MDN: Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity)



---
url: /plugins/compact-hashed-chunk-ids-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# CompactHashedChunkIdsPlugin


[Added in v2.2.1](https://github.com/web-infra-dev/rspack/releases/tag/v2.2.1)Rspack only

`CompactHashedChunkIdsPlugin` hashes chunk contents and assigns the shortest available prefix of each encoded hash. Compared with `deterministic`, it produces more compact ids that preserve stability while reducing bundle size and improving runtime indexing performance. Every character uses `0-9a-z`, making chunk ids safe for case-insensitive file systems. An id is extended only when its shorter prefix is already used.

:::warning Deprecated alias
`CompatHashedChunkIdsPlugin` was available in Rspack 2.2.0. It is deprecated and was renamed to `CompactHashedChunkIdsPlugin` in Rspack 2.2.1. The old name remains available as a compatibility alias.
:::

`optimization.chunkIds: 'compact-hashed'` uses this plugin internally. Use the plugin directly when you need to customize the minimum encoded id length.

## Examples

```js title="rspack.config.mjs"
import rspack from '@rspack/core';

export default {
  optimization: {
    chunkIds: false,
  },
  plugins: [
    new rspack.ids.CompactHashedChunkIdsPlugin({
      minLength: 1,
    }),
  ],
};
```

## Options

### minLength

- **Type:** `number`
- **Default:** `1`
- **Range:** Integer from `1` to `13`

The minimum encoded id length. Rspack extends an id one character at a time when its hash prefix is already used. Increasing `minLength` expands the initial id space, reducing prefix collisions and making generated output and caching more stable. The tradeoff is that chunk ids become longer.



---
url: /plugins/compact-hashed-module-ids-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# CompactHashedModuleIdsPlugin


[Added in v2.2.1](https://github.com/web-infra-dev/rspack/releases/tag/v2.2.1)Rspack only

`CompactHashedModuleIdsPlugin` hashes module identifiers and assigns the shortest available prefix of each encoded hash. Compared with `deterministic`, it produces more compact ids that preserve stability while reducing bundle size and improving runtime indexing performance. The first character uses `a-zA-Z`, and subsequent characters use `a-zA-Z0-9`. An id is extended only when its shorter prefix is already used.

:::warning Deprecated alias
`CompatHashedModuleIdsPlugin` was available in Rspack 2.2.0. It is deprecated and was renamed to `CompactHashedModuleIdsPlugin` in Rspack 2.2.1. The old name remains available as a compatibility alias.
:::

:::warning
The generated module ids are case-sensitive and may contain uppercase letters. On case-insensitive file systems, avoid using `[id]` as the only distinguishing placeholder in [Asset module filenames](/config/output.md#outputassetmodulefilename) or [WebAssembly module filenames](/config/output.md#outputwebassemblymodulefilename). Prefer `[contenthash]`, or include it alongside `[id]`.
:::

[`optimization.moduleIds: 'compact-hashed'`](/config/optimization.md#optimizationmoduleids) uses this plugin internally. Use the plugin directly when you need to customize the minimum encoded id length.

## Examples

```js title="rspack.config.mjs"
import rspack from '@rspack/core';

export default {
  optimization: {
    moduleIds: false,
  },
  plugins: [
    new rspack.ids.CompactHashedModuleIdsPlugin({
      minLength: 1,
    }),
  ],
};
```

## Options

### minLength

- **Type:** `number`
- **Default:** `1`
- **Range:** Integer from `1` to `11`

The minimum encoded id length. Rspack extends an id one character at a time when its hash prefix is already used. Increasing `minLength` expands the initial id space, reducing prefix collisions and making generated output and caching more stable. The tradeoff is that module ids become longer.



---
url: /plugins/css-chunking-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# CssChunkingPlugin


[Added in v1.4.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.4.0)Rspack only

`CssChunkingPlugin` is a plugin specifically designed for CSS code splitting. It ensures that the loading order of styles matches the import order in your source code, avoiding UI issues caused by incorrect CSS order.

> This plugin is inspired by Next.js's [CSS Chunking](https://nextjs.org/docs/app/api-reference/config/next-config-js/cssChunking) feature, thanks to the Next.js team for their innovation.

## Examples

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.experiments.CssChunkingPlugin({
      // ...options
    }),
  ],
};
```

:::tip
After enabling CssChunkingPlugin, SplitChunksPlugin will no longer process CSS modules.
This means that options like `optimization.splitChunks` will no longer handle CSS modules, and all CSS module code splitting logic will be handled entirely by CssChunkingPlugin.
:::

## Options

### strict

- **Type:** `boolean`
- **Default:** `false`

Whether to strictly preserve the import order of CSS modules.

### minSize

The minimum size (in bytes) for a generated chunk.

### maxSize

The maximum size (in bytes) for a generated chunk. Chunks larger than maxSize will be split into smaller parts, each with a size of at least minSize.

## Mode comparison

### Normal mode (strict: false, default)

```js
new rspack.experiments.CssChunkingPlugin({
  strict: false,
});
```

- If CSS modules are imported in different orders throughout the project, they are considered to have no dependencies between them.
- Allow merging independent CSS modules into the same chunk to reduce the number of chunks.

### Strict mode (strict: true)

```js
new rspack.experiments.CssChunkingPlugin({
  strict: true,
});
```

- Strictly ensures that the execution order of CSS modules matches the import order in the source code.

### Example

`a.css` and `b.css` are imported in `foo.js` and `bar.js` with different sequences:

```js
// foo.js
import './a.css';
import './b.css';

// bar.js
import './b.css';
import './a.css';
```

Regular Mode (strict: false): Considers `a.css` and `b.css` to have no dependency relationship and doesn't enforce execution order, thus merging them into the same chunk.

Strict Mode (strict: true): Strictly maintains execution order consistent with import sequence, therefore packaging `a.css` and `b.css` into separate chunks

## Differences from SplitChunksPlugin

`SplitChunksPlugin` does not consider the import order of modules when splitting code.
For JavaScript modules, this is not an issue because execution order is determined at runtime via function calls.

However, for CSS modules, the execution order is entirely determined by their order in the output files and cannot be controlled at runtime. If the order changes, it may cause style issues.

For example, importing the following CSS modules:

```js
import './a.css';
import './b.css';
import './c.css';
```

`SplitChunksPlugin` may split them into the following chunks to satisfy `maxSize` or other constraints:

```
chunk-1: b.css
chunk-2: a.css, c.css  // may be split due to large size
```

This results in the execution order being b.css → a.css → c.css, which violates the original import order and may cause style errors.

`CssChunkingPlugin` first splits all CSS modules, then determines which can be merged based on the import order in the source code. Modules that cannot be merged are split into separate chunks to ensure style correctness.

:::tip
Because CssChunkingPlugin prioritizes preserving style execution order, it may split more chunks than SplitChunksPlugin.
:::



---
url: /plugins/deterministic-module-ids-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# DeterministicModuleIdsPlugin

`DeterministicModuleIdsPlugin` assigns short numeric ids to modules based on their module identifiers. The ids are stable between compilations, which makes the plugin useful for long-term caching.

`optimization.moduleIds: 'deterministic'` uses this plugin internally. Use the plugin directly when you need to customize the deterministic id generation behavior.

## Examples

```js title="rspack.config.mjs"
import rspack from '@rspack/core';

export default {
  optimization: {
    moduleIds: false,
  },
  plugins: [
    new rspack.ids.DeterministicModuleIdsPlugin({
      maxLength: 4,
    }),
  ],
};
```

## Options

### context

- **Type:** `string`
- **Default:** `compiler.context`

The context used to create relative module identifiers before ids are generated.

### test

- **Type:** `(module: Module) => boolean`
- **Default:** `undefined`

Selects which modules should receive deterministic ids from this plugin. When omitted, all modules that need ids are included.

```js title="rspack.config.mjs"
import rspack from '@rspack/core';

export default {
  optimization: {
    moduleIds: false,
  },
  plugins: [
    new rspack.ids.DeterministicModuleIdsPlugin({
      test: (module) => module.type.startsWith('css'),
    }),
  ],
};
```

### maxLength

- **Type:** `number`
- **Default:** `3`

The maximum id length in digits used as the starting id space. The generated numeric id space starts at `10 ** maxLength`.

### salt

- **Type:** `number`
- **Default:** `0`

The hash salt used when generating ids. Change this value to try a different hash starting value in the same id space.

### fixedLength

- **Type:** `boolean`
- **Default:** `false`

When enabled, Rspack does not increase the id length to find a larger id space.

### failOnConflict

- **Type:** `boolean`
- **Default:** `false`

When enabled, Rspack reports an error if deterministic id assignment produces conflicts. By default, Rspack resolves conflicts by retrying with a larger id space.

## Usage with optimization.moduleIds

For the common long-term caching setup, prefer the built-in optimization option:

```js title="rspack.config.mjs"
export default {
  optimization: {
    moduleIds: 'deterministic',
  },
};
```

Use `DeterministicModuleIdsPlugin` directly only when you need the options above.


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/optimization/#optimizationmoduleids) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /plugins/dll-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# DllPlugin

The `DllPlugin` is used in a separate rspack configuration exclusively to create a dll-only-bundle.

## Examples

```js
new rspack.DllPlugin({
  path: path.resolve(__dirname, 'manifest.json'),
  name: '[name]_dll_lib',
});
```

The Plugin will create a `manifest.json` which is written to the given path.
It contains mappings from require and import requests to module ids.

The `manifest.json` is used by the [DllReferencePlugin](/plugins/dll-reference-plugin.md)

Combine this plugin with `output.library` options to expose the dll function.

## Options

```ts
type DllPluginOptions = {
  context?: string;
  entryOnly?: boolean;
  format?: boolean;
  name?: string;
  path: string;
  type?: string;
};
```

### context

- **Type:** `string`
- **Default:** The Rspack compiler context

Sets the context used for requests in the manifest file.

### entryOnly

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

If `true`, only entry modules are exposed.

### format

- **Type:** `boolean`
- **Default:** `false`

Controls whether the generated manifest JSON is formatted for readability.

### name

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

Sets the name of the exposed DLL function. Configure it to match the DLL bundle's `output.library` name.

### path

- **Type:** `string`

Sets the absolute output path of the manifest JSON file. This option is required.

### type

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

Sets the external type of the DLL bundle. Configure it to match `output.library.type`.


This page is adapted from [webpack documentation](https://webpack.js.org/plugins/dll-plugin/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /plugins/dll-reference-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# DllReferencePlugin

The `DllReferencePlugin` is used to reference the dll-only-bundle to require pre-built dependencies.

## Examples

### Basic example

```js
new rspack.DllReferencePlugin({
  // Manifest should be generated by DllPlugin
  manifest: require('../lib/manifest.json'),

  name: '[name]_dll_lib',
});
```

Application require dependencies will reference to pre-built using `DllPlugin`.

### With scope

The content of the dll is accessible under a module prefix when set scope.

```js
new rspack.DllReferencePlugin({
  // Manifest should be generated by DllPlugin
  manifest: require('../lib/manifest.json'),

  name: '[name]_dll_lib',

  scope: 'xyz',
});
```

Access via `require('xzy/abc')`, you can require `abc` from another pre-built lib.

## Options

- **Types:**

```ts
type DllReferencePluginOptionsContent = {
  /**
   * Module info.
   */
  [k: string]: {
    /**
     * Meta information about the module.
     */
    buildMeta?: {
      [k: string]: any;
    };
    /**
     * Information about the provided exports of the module.
     */
    exports?: string[] | true;
    /**
     * Module ID.
     */
    id?: string | number;
  };
};

type DllReferencePluginOptionsManifest = {
  /**
   * The mappings from module specifier to module info.
   */
  content: DllReferencePluginOptionsContent;
  /**
   * The name where the dll is exposed (external name).
   */
  name?: string;
  /**
   * The type how the dll is exposed (external type).
   */
  type?: DllReferencePluginOptionsSourceType;
};

/**
 * The type how the dll is exposed (external type).
 */
type DllReferencePluginOptionsSourceType =
  | 'var'
  | 'assign'
  | 'this'
  | 'window'
  | 'global'
  | 'commonjs'
  | 'commonjs2'
  | 'commonjs-module'
  | 'amd'
  | 'amd-require'
  | 'umd'
  | 'umd2'
  | 'jsonp'
  | 'system';

type DllReferencePluginOptions =
  | {
      /**
       * Context of requests in the manifest (or content property) as absolute path.
       */
      context?: string;
      /**
       * Extensions used to resolve modules in the dll bundle (only used when using 'scope').
       */
      extensions?: string[];
      /**
       * An object containing content and name or a string to the absolute path of the JSON manifest to be loaded upon compilation.
       */
      manifest: string | DllReferencePluginOptionsManifest;
      /**
       * The name where the dll is exposed (external name, defaults to manifest.name).
       */
      name?: string;
      /**
       * Prefix which is used for accessing the content of the dll.
       */
      scope?: string;
      /**
       * How the dll is exposed (libraryTarget, defaults to manifest.type).
       */
      sourceType?: DllReferencePluginOptionsSourceType;
      /**
       * The way how the export of the dll bundle is used.
       */
      type?: 'require' | 'object';
    }
  | {
      /**
       * The mappings from module specifier to module info.
       */
      content: DllReferencePluginOptionsContent;
      /**
       * Context of requests in the manifest (or content property) as absolute path.
       */
      context?: string;
      /**
       * Extensions used to resolve modules in the dll bundle (only used when using 'scope').
       */
      extensions?: string[];
      /**
       * The name where the dll is exposed (external name).
       */
      name: string;
      /**
       * Prefix which is used for accessing the content of the dll.
       */
      scope?: string;
      /**
       * How the dll is exposed (libraryTarget).
       */
      sourceType?: DllReferencePluginOptionsSourceType;
      /**
       * The way how the export of the dll bundle is used.
       */
      type?: 'require' | 'object';
    };
```

### content

- **Type:** `DllReferencePluginOptionsContent`
- **Default:** `undefined`

Provides the mappings from module requests to module metadata directly. When this form is used instead of `manifest`, `name` is required.

### context

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

Sets the absolute context used to match module requests against keys in `manifest` or `content`. When using a manifest generated with a custom `DllPlugin.context`, set this option to the same path.

### extensions

- **Type:** `string[]`
- **Default:** `['', '.js', '.json', '.wasm']`

Sets the extensions used to resolve modules in the DLL bundle when `scope` is configured.

### manifest

- **Type:** `string | DllReferencePluginOptionsManifest`
- **Default:** `undefined`

Provides either a manifest object or the absolute path to a JSON manifest generated by `DllPlugin`. Use this option instead of `content`.

### name

- **Type:** `string`
- **Default:** `manifest.name`

Sets the external name under which the DLL is exposed. It is required when `content` is provided directly.

### scope

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

Sets the module prefix used to access content from the DLL.

### sourceType

- **Type:** `DllReferencePluginOptionsSourceType`
- **Default:** `manifest.type`, or `'var'` when no type is provided

Sets how the DLL is exposed, corresponding to its library type.

### type

- **Type:** `'require' | 'object'`
- **Default:** `'require'`

Controls how exports from the DLL bundle are consumed.

This plugin references a dll manifest file to map dependency names to module ids, then require them as needed.


This page is adapted from [webpack documentation](https://webpack.js.org/plugins/dll-plugin/#dllreferenceplugin) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /plugins/lightning-css-minimizer-rspack-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# LightningCssMinimizerRspackPlugin


Rspack only

This plugin uses [lightningcss](https://lightningcss.dev/) to minify CSS assets. See [optimization.minimizer](/config/optimization.md#optimizationminimizer).

## Examples

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  optimization: {
    minimizer: [new rspack.LightningCssMinimizerRspackPlugin()],
  },
};
```

## Options

### include

- **Type:** `string | RegExp | (string | RegExp)[]`
- **Default:** `undefined`

Use this to specify which files should be minified, it matches the path of the output files.

### exclude

- **Type:** `string | RegExp | (string | RegExp)[]`
- **Default:** `undefined`

Use this to specify which files should be excluded from minification, it matches the path of the output files.

### test

- **Type:** `string | RegExp | (string | RegExp)[]`
- **Default:** `undefined`

Use this to provide a pattern that CSS files are matched against. If the output filename matches the given pattern, it will be minified, otherwise it won't be.

### removeUnusedLocalIdents

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

Whether to automatically remove the unused local idents of CSS Modules, including unused CSS class names, ids, and @keyframe names. The declarations of these will be removed.

For example, in the following CSS Modules, class names a and b are exported, but only class name a is used in the js file:

```css title=index.module.css
.a {
  color: red;
}

.b {
  color: blue;
}
```

```js title=index.js
import * as styles from './index.module.css';
document.body.className = styles.a;
```

At this point, the information that class name b is unused will be obtained via Rspack's tree shaking feature and provided to lightningcss. During minimization, the declaration for class name b will be removed from the CSS output, resulting in the following final output:


```css
.a{color: red}
```

### minimizerOptions

Configuration passed to Lightning CSS for minification.

Below are the configurations supported, `targets` configuration is plain browserslist query, for other detailed usage, please refer to [Lightning CSS documentation](https://lightningcss.dev/transpilation.html)

:::info

1. The `targets` option is resolved in the following priority order:

   - User-specified `targets` in plugin options (highest priority)
   - Targets derived from Rspack's [`target`](/config/target.md) configuration when using browserslist-related targets (e.g., `browserslist` or `browserslist:modern`), since Lightning CSS only supports browser-related targets, non-browser targets like `node` will not provide default targets for this plugin.
   - Falls back to `"fully supports es6"` if neither is available

   The fallback ensures that minification does not introduce advanced syntax that could cause browser incompatibility (minification might turn lower-level syntax into advanced syntax because it is shorter).

2. The `exclude` option is configured with all features by default. We usually do syntax degradation in [builtin:lightningcss-loader](/guide/features/builtin-lightningcss-loader.md) or other loaders, so this plugin excludes all features by default to avoid syntax downgrading during the minimize process.

We recommend and encourage users to configure their own `targets` to achieve the best minification results.
:::

```ts
type Targets = {
  android?: string;
  chrome?: string;
  edge?: string;
  firefox?: string;
  ie?: string;
  ios_saf?: string;
  opera?: string;
  safari?: string;
  samsung?: string;
};

type LightningCssMinimizerOptions = {
  errorRecovery?: boolean;
  targets?: string[] | string | Targets;
  include?: LightningcssFeatureOptions;
  exclude?: LightningcssFeatureOptions;
  drafts?: Drafts;
  nonStandard?: NonStandard;
  pseudoClasses?: PseudoClasses;
  unusedSymbols?: Set<String>;
};

type LightningcssFeatureOptions = {
  nesting?: boolean;
  notSelectorList?: boolean;
  dirSelector?: boolean;
  langSelectorList?: boolean;
  isSelector?: boolean;
  textDecorationThicknessPercent?: boolean;
  mediaIntervalSyntax?: boolean;
  mediaRangeSyntax?: boolean;
  customMediaQueries?: boolean;
  clampFunction?: boolean;
  colorFunction?: boolean;
  oklabColors?: boolean;
  labColors?: boolean;
  p3Colors?: boolean;
  hexAlphaColors?: boolean;
  spaceSeparatedColorNotation?: boolean;
  fontFamilySystemUi?: boolean;
  doublePositionGradients?: boolean;
  vendorPrefixes?: boolean;
  logicalProperties?: boolean;
  selectors?: boolean;
  mediaQueries?: boolean;
  color?: boolean;
};
```



---
url: /plugins/limit-chunk-count-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# LimitChunkCountPlugin

While writing your code, you may have already added many code split points to load stuff on demand. After compiling you might notice that some chunks are too small - creating larger HTTP overhead. `LimitChunkCountPlugin` can post-process your chunks by merging them.

## Examples

Limit the compilation to five chunks:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.optimize.LimitChunkCountPlugin({
      maxChunks: 5,
    }),
  ],
};
```

## Options

### maxChunks

- **Type:** `number`

Limit the maximum number of chunks using a value greater than or equal to `1`. Using `1` will prevent any additional chunks from being added as the entry/main chunk is also included in the count.

```js
new rspack.optimize.LimitChunkCountPlugin({
  maxChunks: 5,
});
```


This page is adapted from [webpack documentation](https://webpack.js.org/plugins/limit-chunk-count-plugin/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /plugins/runtime-chunk-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# RuntimeChunkPlugin

`RuntimeChunkPlugin` creates separate runtime chunks and controls how they are named. [`optimization.runtimeChunk`](/config/optimization.md#optimizationruntimechunk) applies this plugin internally.

## Examples

This configuration extracts the runtime used by two entry points into `runtime.js`:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  entry: {
    app: './src/app.js',
    admin: './src/admin.js',
  },
  output: {
    filename: '[name].js',
  },
  plugins: [
    new rspack.optimize.RuntimeChunkPlugin({
      name: 'runtime',
    }),
  ],
};
```

Rspack emits `app.js`, `admin.js`, and the shared `runtime.js`. Keeping the runtime separate allows entry bundles to be cached independently from runtime changes.

## Options

### name

Used to configure the name of the runtime chunk; it can be a string or a function that returns a string, where the function parameter is the name of the entry.

- **Type:** `string | ((entrypoint: { name: string }) => string)`

```js
new rspack.optimize.RuntimeChunkPlugin({
  name: ({ name }) => `runtime~${name}`,
});
```



---
url: /plugins/split-chunks-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# SplitChunksPlugin

SplitChunksPlugin is a built-in plugin that splits code into multiple [chunks](/misc/glossary.md#chunk) to optimize application loading performance and achieve better caching strategies and parallel loading.

SplitChunksPlugin can be configured through the [optimization.splitChunks](/config/optimization.md#optimizationsplitchunks) option, and you typically don't need to manually register this plugin.

## Default behavior

Rspack has a built-in configuration for `SplitChunksPlugin` that works well for most scenarios.

By default it only affects on-demand chunks, because changing initial chunks would affect the script tags the HTML file should include to run the project.

Rspack ships with two default cache groups:

- `default`: extract modules shared by at least 2 chunks.
- `defaultVendors`: extract modules from `node_modules`.

Rspack will automatically split chunks based on these conditions:

- New chunk can be shared OR modules are from the node\_modules folder
- New chunk would be bigger than 20kb (before min+gz)
- Maximum number of parallel requests when loading chunks on demand would be lower or equal to 30
- Maximum number of parallel requests at initial page load would be lower or equal to 30

When trying to fulfill the last two conditions, bigger chunks are preferred.

## Examples

The default value is `chunks: 'async'`, but for most production applications it is recommended to start with:

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      chunks: 'all',
    },
  },
};
```

while keeping the default cache groups. This usually deduplicates both initial and async chunks without changing JavaScript execution semantics. Rspack's runtime still loads only the chunks reachable from the current entry or runtime.

## Options

Rspack provides a set of options for developers that want more control over this functionality.

:::warning
The default configuration was chosen to fit web performance best practices, but the optimal strategy for your project might differ. If you're changing the configuration, you should measure the effect of your changes to ensure there's a real benefit.
:::

### optimization.splitChunks

This configuration object represents the default behavior of the `SplitChunksPlugin`.

```js title="rspack.config.mjs"
export default {
  //...
  optimization: {
    splitChunks: {
      chunks: 'async',
      minChunks: 1,
      minSize: 20000,
      maxAsyncRequests: 30,
      maxInitialRequests: 30,
      cacheGroups: {
        defaultVendors: {
          test: /[\\/]node_modules[\\/]/,
          priority: -10,
          reuseExistingChunk: true,
        },
        default: {
          minChunks: 2,
          priority: -20,
          reuseExistingChunk: true,
        },
      },
    },
  },
};
```

:::warning

When files paths are processed by Rspack, they always contain `/` on UNIX systems and `\` on Windows. That's why using `[\\/]` in `{cacheGroup}.test` fields is necessary to represent a path separator. `/` or `\` in `{cacheGroup}.test` will cause issues when used cross-platform.

:::

:::warning

Passing an entry name to `{cacheGroup}.test` and using a name of an existing chunk for `{cacheGroup}.name` is no longer allowed.

:::

### splitChunks.cacheGroups

Cache groups can inherit and/or override any options from `splitChunks.{cacheGroup}.*`; but `test`, `priority` and `reuseExistingChunk` can only be configured on cache group level. To disable any of the default cache groups, set them to `false`.

```js title="rspack.config.mjs"
export default {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        default: false,
      },
    },
  },
};
```

### splitChunks.chunks

#### splitChunks.cacheGroups.\{cacheGroup}.chunks

- **Type:**

```ts
type OptimizationSplitChunksChunks =
  'initial' | 'async' | 'all' | RegExp | ((chunk: Chunk) => boolean);
```

- **Default:** `'async'`

This option controls which chunks should be selected for code splitting. When a string is provided, the possible values are `all`, `async` and `initial`.

- `all`: Split all types of chunks, including [initial chunks](/misc/glossary.md#initial-chunk) and [async chunks](/misc/glossary.md#async-chunk).
- `initial`: Only split initial chunks.
- `async`: Only split async chunks.

Generally, setting it to `all` can help reduce duplicate modules being bundled, as it means chunks can be shared between initial chunks and async chunks.

For most production applications, `chunks: 'all'` is the recommended starting point. What often hurts the result is not `chunks: 'all'` itself, but broad manual cache groups combined with a fixed [`name`](#splitchunksname).

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      // include all types of chunks
      chunks: 'all',
    },
  },
};
```

:::tip

Before Rspack v1.6.2, projects using [Module Federation](/guide/advanced/module-federation.md) with exposes could not enable `chunks: 'all'`, as it would break remote module splitting.

Starting from v1.6.2, Module Federation works seamlessly with `chunks: 'all'`.

:::

The `chunks` option can be set to a regular expression, which is a shorthand for `(chunk) => typeof chunk.name === "string" && regex.test(chunk.name)`.

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      // equivalent to `chunks: (chunk) => typeof chunk.name === "string" && /foo/.test(chunk.name)`
      chunks: /foo/,
    },
  },
};
```

The `chunks` option can be set to a function for more fine-grained control. The function receives a `chunk` parameter, and returning `true` means the chunk participates in splitting (modules within it may be extracted into new chunks), while returning `false` means the chunk doesn't participate in splitting (remains as is).

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      chunks(chunk) {
        // exclude `foo` chunk
        return chunk.name !== 'foo';
      },
    },
  },
};
```

:::warning
Using the function type of `chunks` will significantly reduce build performance, as the function needs to be called for each module, resulting in huge cross-language communication overhead between Rust and JavaScript. Therefore, we do not recommend using the function type.
:::

You can configure `chunks` individually for each cacheGroup, for example:

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      cacheGroups: {
        groupA: {
          chunks: 'all',
        },
        groupB: {
          chunks: 'initial',
        },
        groupC: {
          chunks: 'async',
        },
      },
    },
  },
};
```

### splitChunks.maxAsyncRequests

- **Type:** `number`
- **Default:** `30`

Maximum number of parallel requests when on-demand loading.

### splitChunks.maxInitialRequests

- **Type:** `number`
- **Default:** `30`

Maximum number of parallel requests at an entry point.

### splitChunks.enforceSizeThreshold

#### splitChunks.cacheGroups.\{cacheGroup}.enforceSizeThreshold

- **Type:** `number | Record<string, number>`
- **Default:** `50000` in production and `30000` in others

Set a size threshold that lets Rspack continue splitting once a candidate chunk is large enough.

When a candidate reaches this threshold, Rspack ignores request-limit checks such as [`splitChunks.maxAsyncRequests`](#splitchunksmaxasyncrequests) and [`splitChunks.maxInitialRequests`](#splitchunksmaxinitialrequests).

Compared with [`splitChunks.cacheGroups.{cacheGroup}.enforce`](#splitchunkscachegroupscachegroupenforce), this is more targeted: only sufficiently large candidates are forced to keep splitting, while smaller ones still follow the normal heuristics.

When configured with a `number`, the same threshold is applied to all size types defined in [`splitChunks.defaultSizeTypes`](#splitchunksdefaultsizetypes). The object form lets you set different thresholds per size type.

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      enforceSizeThreshold: 80 * 1000,
      cacheGroups: {
        vendors: {
          test: /[\\/]node_modules[\\/]/,
          enforceSizeThreshold: 120 * 1000,
        },
      },
    },
  },
};
```

### splitChunks.minChunks

#### splitChunks.cacheGroups.\{cacheGroup}.minChunks

- **Type:** `number`
- **Default:** `1`

The minimum times must a module be shared among chunks before splitting.

### splitChunks.hidePathInfo

- **Type:** `boolean`
- **Default:** defaults to `true` if `options.mode` is `'production'`, otherwise defaults to `false`

Prevents exposing path info when creating names for parts splitted by maxSize.

### splitChunks.minSize

#### splitChunks.cacheGroups.\{cacheGroup}.minSize

- **Type:** `number | Record<string, number>`
- **Default:** `20000` in production and `10000` in others

When using the `number` type of configuration, the same `minSize` will be configured for all module types defined in [`splitChunks.defaultSizeTypes`](/plugins/split-chunks-plugin.md#splitchunksdefaultsizetypes).

```js title="rspack.config.mjs"
export default {
  //...
  optimization: {
    splitChunks: {
      minSize: 100 * 1000,
    },
  },
};
```

When configured with the object form, different `minSize` can be set for different types of module types defined in `splitChunks.defaultSizeTypes`.

```js title="rspack.config.mjs"
export default {
  //...
  optimization: {
    splitChunks: {
      minSize: {
        javascript: 100 * 1000,
        css: 300 * 1000,
      },
    },
  },
};
```

For example, the above configuration means that the minimum size of javascript modules in the split chunks needs to be at least 100KB, and the minimum size of css modules needs to be at least 300KB.

### splitChunks.minSizeReduction

#### splitChunks.cacheGroups.\{cacheGroup}.minSizeReduction

- **Type:** `number | Record<string, number>`
- **Default:** `0`

If there are several small modules in the build output, developers may not want to generate separate chunks for them even if their total size exceeds the `minSize` threshold. In this case, you can use the `minSizeReduction` parameter to set the minimum size reduction threshold required for module splitting.

The calculation rule for this parameter is: splitting will only occur when the total size reduction across all parent chunks after splitting the module is not less than the specified value.

Assuming the following scenario, suppose there is a 40KB module that is referenced by 2 chunks, and we set `minSizeReduction: 100`. If we were to split this module, each parent chunk would be reduced by 40KB, resulting in a total reduction of `40KB × 2 = 80KB`. As this is less than 100KB, the split will not be triggered.

If a module still appears duplicated after lowering `minSize`, check `minSizeReduction` before assuming splitChunks is not working.

```js title="rspack.config.mjs"
export default {
  //...
  optimization: {
    splitChunks: {
      minSizeReduction: 100 * 1000,
    },
  },
};
```

### splitChunks.maxSize

`number | Record<string, number> = 0`

Using `maxSize` (either globally `optimization.splitChunks.maxSize` per cache group `optimization.splitChunks.cacheGroups[x].maxSize` or for the fallback cache group `optimization.splitChunks.fallbackCacheGroup.maxSize`) tells Rspack to try to split chunks bigger than `maxSize` bytes into smaller parts. Parts will be at least `minSize` (next to `maxSize`) in size.
The algorithm is deterministic and changes to the modules will only have local effects. So that it is usable when using long term caching and doesn't require records. `maxSize` is only a hint and could be violated when modules are bigger than `maxSize` or splitting would violate `minSize`.

Rspack groups modules for `maxSize` using deterministic path-derived keys, so modules with similar paths tend to stay together. In practice, prefer `maxSize` when the problem is "this shared chunk is too large". It is usually a better fit than forcing a broad fixed [`name`](#splitchunksname).

When the chunk has a name already, each part will get a new name derived from that name. Depending on the value of `optimization.splitChunks.hidePathInfo` it will add a key derived from the first module name or a hash of it.

`maxSize` option is intended to be used with HTTP/2 and long term caching. It increases the request count for better caching. It could also be used to decrease the file size for faster rebuilding.

:::tip

`maxSize` takes higher priority than `maxInitialRequest/maxAsyncRequests`. Actual priority is `maxInitialRequest/maxAsyncRequests < maxSize < minSize`.

:::

:::tip

Setting the value for `maxSize` sets the value for both `maxAsyncSize` and `maxInitialSize`.

:::

### splitChunks.maxAsyncSize

`number | Record<string, number>`

Like `maxSize`, `maxAsyncSize` can be applied globally (`splitChunks.maxAsyncSize`), to cacheGroups (`splitChunks.cacheGroups.{cacheGroup}.maxAsyncSize`), or to the fallback cache group (`splitChunks.fallbackCacheGroup.maxAsyncSize`).

The difference between `maxAsyncSize` and `maxSize` is that `maxAsyncSize` will only affect on-demand loading chunks.

### splitChunks.maxInitialSize

`number | Record<string, number>`

Like `maxSize`, `maxInitialSize` can be applied globally (`splitChunks.maxInitialSize`), to cacheGroups (`splitChunks.cacheGroups.{cacheGroup}.maxInitialSize`), or to the fallback cache group (`splitChunks.fallbackCacheGroup.maxInitialSize`).

The difference between `maxInitialSize` and `maxSize` is that `maxInitialSize` will only affect initial load chunks.

### splitChunks.fallbackCacheGroup

- **Type:**

```ts
type FallbackCacheGroup = {
  chunks?: 'initial' | 'async' | 'all' | RegExp | ((chunk: Chunk) => boolean);
  minSize?: number;
  maxSize?: number;
  maxAsyncSize?: number;
  maxInitialSize?: number;
  automaticNameDelimiter?: string;
};
```

Configures options for modules that are not selected by any cache group. The fallback cache group uses the same sizing behavior as the corresponding global `splitChunks` options, but only for the remaining modules after cache group matching.

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      fallbackCacheGroup: {
        minSize: 10_000,
        maxSize: 50_000,
      },
    },
  },
};
```

### splitChunks.automaticNameDelimiter

- **Type:** `string`
- **Default:** `-`

By default Rspack will generate names using origin and name of the chunk (e.g. vendors-main.js).

This option lets you specify the delimiter to use for the generated names.

### splitChunks.name

#### splitChunks.cacheGroups.\{cacheGroup}.name

- **Type:**

```ts
type SplitChunksName = false | string | SplitChunksNameFunction;

type SplitChunksNameFunction = (
  module: Module,
  chunks: Chunk[],
  cacheGroupKey: string,
) => string | undefined;
```

- **Default:** `false`

Also available for each cacheGroup: `splitChunks.cacheGroups.{cacheGroup}.name`.

The name of the split chunk. Providing `false` will keep the same name of the chunks so it doesn't change names unnecessarily. It is the recommended value for production builds.

Providing a string allows you to use a custom name. Specifying a string will merge all common modules and vendors into a single chunk. This might lead to bigger initial downloads and slow down page loads.

When `name` is a function, Rspack calls it with these parameters:

- `module`: the module that is being considered for the split chunk. You can use methods such as `module.identifier()` to derive a stable name from its request or resource path.
- `chunks`: the chunks that currently contain this module and were selected by the cache group. Each item is a `Chunk` object, so common properties such as `chunk.name` are available.
- `cacheGroupKey`: the key of the cache group that matched the module, for example `vendors` for `cacheGroups.vendors`.

The function should return the split chunk name. Return `undefined` to let Rspack fall back to automatic naming for that module group.

For example, you can name vendor chunks by the cache group key and by the selected chunk names:

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendors: {
          test: /[\\/]node_modules[\\/]/,
          name(module, chunks, cacheGroupKey) {
            const chunkNames = chunks
              .map((chunk) => chunk.name)
              .filter(Boolean)
              .sort()
              .join('~');

            return `${cacheGroupKey}-${chunkNames || 'shared'}`;
          },
        },
      },
    },
  },
};
```

You can also derive a chunk name from the package that provided the matched module:

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        npmPackage: {
          test: /[\\/]node_modules[\\/]/,
          name(module, chunks, cacheGroupKey) {
            const identifier = module.identifier();
            const match = identifier.match(
              /[\\/]node_modules[\\/]((?:@[^\\/]+[\\/])?[^\\/]+)/,
            );
            const packageName = match
              ? match[1].replace(/[\\/]/g, '-')
              : 'misc';

            return `${cacheGroupKey}-${packageName}`;
          },
        },
      },
    },
  },
};
```

`name` is not only a filename customization. It also changes grouping behavior: when different chunk combinations hit the same cache group and resolve to the same name, Rspack will merge them into the same named split chunk candidate. This can improve cache hit rate, but it can also force a page to fetch modules from unrelated dependency chains.

If your goal is only to hint chunk identity or filenames, prefer [`splitChunks.cacheGroups.{cacheGroup}.idHint`](#splitchunkscachegroupscachegroupidhint) and leave `name` unset.

If the `splitChunks.name` matches an [entry point](/config/entry.md) name, the entry point will be removed.

:::info

`splitChunks.cacheGroups.{cacheGroup}.name` can be used to move modules into a chunk that is a parent of the source chunk. For example, use `name: "entry-name"` to move modules into the `entry-name` chunk. You can also use on demand named chunks, but you must be careful that the selected modules are only used under this chunk.

:::

### splitChunks.filename

#### splitChunks.cacheGroups.\{cacheGroup}.filename

- **Type:** `string | function`

Allows to override the filename when and only when it's an initial chunk. All placeholders available in output.filename are also available here.

```js title="rspack.config.mjs"
export default {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        defaultVendors: {
          filename: 'vendors-[name].js',
          // or
          filename: (pathData, assetInfo) => {
            return `${pathData.chunk.name}-bundle.js`;
          },
        },
      },
    },
  },
};
```

### splitChunks.usedExports

- **Type:** `boolean`
- **Default:** Value of [optimization.usedExports](/config/optimization.md#optimizationusedexports)

Enabling this configuration, the splitting of chunks will be grouped based on the usage of modules exports in different runtimes, ensuring the optimal loading size in each runtime.

For example, if there are three entry points named `foo`, `bar`, and `baz`, they all depend on the same module called `shared`. However, `foo` and `bar` depend on the export `value1` from `shared`, while `baz` depends on the export `value2` from `shared`.

```js title=foo.js
import { value1 } from 'shared';
value1;
```

```js title=bar.js
import { value1 } from 'shared';
value1;
```

```js title=baz.js
import { value2 } from 'shared';
value2;
```

In the default strategy, the `shared` module appears in 3 chunks. If it meets the [minSize for splitting](/plugins/split-chunks-plugin.md#splitchunksminsize), then the `shared` module should be extracted into a separate chunk.

```
chunk foo, chunk bar
      \
      chunk shared (exports value1 and value2)
      /
chunk baz
```

However, this would result in none of the three entry points having the optimal loaded size. Loading the `shared` module from the `foo` and `bar` entries would unnecessarily load the export `value2`, while loading from the `baz` entry would unnecessarily load the export `value1`.

When the `splitChunks.usedExports` optimization is enabled, it analyzes which exports of the `shared` module are used in different entries. It finds that the exports used in `foo` and `bar` are different from those in `baz`, resulting in the creation of two distinct chunks, one corresponding to the entries `foo` and `bar`, and the other corresponding to the entry `baz`.

```
chunk foo, chunk bar
        \
      chunk shared-1 (exports only value1)

chunk baz
        \
      chunk shared-2 (exports only value2)
```

This option only changes how splitChunks groups modules across runtimes. It does not replace tree shaking and does not decide whether unused exports are removed.

### splitChunks.defaultSizeTypes

- **Type:** `string[]`
- **Default:** `["javascript", "css", "unknown"]`

When calculating the size of chunks, only the sizes of javascript modules and built-in css modules are taken into account by default. For example, when configuring `minSize: 300`, both javascript modules and css modules need to meet the requirement in order to be split.

You can configure additional module types, for example, if you want WebAssembly modules to be split as well:

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      defaultSizeTypes: ['wasm', '...'],
    },
  },
};
```

### splitChunks.cacheGroups

Cache groups can inherit and/or override any options from `splitChunks.*`; but `test`, `priority` and `reuseExistingChunk` can only be configured on cache group level. To disable any of the default cache groups, set them to `false`.

```js title="rspack.config.mjs"
export default {
  //...
  optimization: {
    splitChunks: {
      cacheGroups: {
        default: false,
      },
    },
  },
};
```

#### splitChunks.cacheGroups.\{cacheGroup}.priority

- **Type:** `number`
- **Default:** `-20`

A module can belong to multiple cache groups. The optimization will prefer the cache group with a higher `priority`. The default groups have a negative priority to allow custom groups to take higher priority (default value is `0` for custom groups).

#### splitChunks.cacheGroups.\{cacheGroup}.test

- **Type:** `RegExp | string | (module: Module, { chunkGraph: ChunkGraph, moduleGraph: ModuleGraph }) => boolean`

Controls which modules are selected by this cache group. Omitting it selects all modules. It can match the absolute module resource path or chunk names. When a chunk name is matched, all modules in the chunk are selected.

:::warning
Using the function type of `test` will significantly reduce build performance, as the function needs to be called for each module, resulting in huge cross-language communication overhead between Rust and JavaScript. Therefore, we do not recommend using the function type.
:::

#### splitChunks.cacheGroups.\{cacheGroup}.enforce

- **Type:** `boolean`

Tells Rspack to ignore `splitChunks.minSize`, splitChunks`.minChunks`, `splitChunks.maxAsyncRequests` and `splitChunks.maxInitialRequests` options and always create chunks for this cache group.

#### splitChunks.cacheGroups.\{cacheGroup}.idHint

- **Type:** `string`

Sets the hint for chunk id. It will be added to chunk's filename.

#### splitChunks.cacheGroups.\{cacheGroup}.reuseExistingChunk

- **Type:** `boolean`
- **Default** `false`

Whether to reuse existing chunks when possible. If so, after splitting, the newly created chunk contains modules that are exactly the same as those in the original chunk, the original chunk will be reused, and no new chunk will be generated, which may affect the final filename of the chunk. For example:

```
chunk Foo: [ module A, module B ]
chunk Bar: [ module B ]

cacheGroup: {
  test: /B/,
  chunks: 'all'
}
```

In chunks Foo and Bar, the module B, due to the configuration of cacheGroup, will be split into a new chunk that only contains module B. This new chunk is identical in terms of the modules it contains with chunk Bar, so chunk Bar can be directly reused.

If the setting of reuseExistingChunk is set to `false`, then the module B in chunks Bar and Foo will be moved to a new chunk, and chunk Bar, since it no longer contains any modules, will be deleted as an empty chunk.

#### splitChunks.cacheGroups.\{cacheGroup}.type

- **Types:** `string | RegExp`

Allows to assign modules to a cache group by module type.

#### splitChunks.cacheGroups.\{cacheGroup}.layer

- **Type:** `string | RegExp | ((layer?: string) => boolean)`

Assigns modules to a cache group by module layer. This is useful when [entry](/config/entry.md#entrydescriptionlayer) or [rule](/config/module-rules.md#ruleslayer) layers are used to separate modern, legacy, server, or client code paths.

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      cacheGroups: {
        modern: {
          layer: 'modern',
          chunks: 'all',
        },
      },
    },
  },
};
```

## FAQ

### Why are modules still duplicated?

Common reasons include:

- the shared candidate is too small to satisfy [`splitChunks.minSize`](#splitchunksminsize)
- the split does not satisfy [`splitChunks.minSizeReduction`](#splitchunksminsizereduction)
- the candidate does not satisfy [`splitChunks.minChunks`](#splitchunksminchunks)
- [`splitChunks.maxAsyncRequests`](#splitchunksmaxasyncrequests) or [`splitChunks.maxInitialRequests`](#splitchunksmaxinitialrequests) rejects the split
- `chunks`, `test`, or custom cache groups do not actually select the same chunk combination

Very small duplicates are often intentional. Extracting them into an extra chunk can be worse than keeping them duplicated.

### Does splitChunks affect JavaScript execution order?

No. `splitChunks` changes chunk topology, but JavaScript loading and execution order are still guaranteed by the runtime dependency graph.

### Does splitChunks affect tree shaking?

No. Tree shaking decides what code is kept. `splitChunks` only decides how kept modules are partitioned into chunks.

### Can splitChunks affect CSS order?

Yes, potentially. This caveat is about extracted CSS, not JavaScript execution order.

In extracted CSS flows such as `mini-css-extract-plugin` or Rspack's [Built-in CSS support](/guide/languages/css.md#built-in-css-support), changing chunk groups with splitChunks can also change final CSS order. See [Deep dive into webpack CSS order issue](https://github.com/orgs/web-infra-dev/discussions/12) for background. If CSS order is the primary concern, also review [CssChunkingPlugin](/plugins/css-chunking-plugin.md).


This page is adapted from [webpack documentation](https://webpack.js.org/configuration/optimization/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /plugins/swc-js-minimizer-rspack-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# SwcJsMinimizerRspackPlugin


Rspack only

This plugin is used to minify JavaScript files using [SWC](https://swc.rs/).

## Examples

Use this plugin via [optimization.minimizer](/config/optimization.md#optimizationminimizer):

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  optimization: {
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin({
        // options
      }),
      new rspack.LightningCssMinimizerRspackPlugin(),
    ],
  },
};
```

:::tip
When `optimization.minimizer` is set, the default minimizers are disabled, so we need to add [LightningCssMinimizerRspackPlugin](/plugins/lightning-css-minimizer-rspack-plugin.md) to minify CSS files.
:::

## Options

### test

- **Type:** `string | RegExp | Array<string | RegExp>`
- **Default:** `\.[cm]?js(\?.*)?$`

Specify the files to be minimized. You can use regular expressions or file path strings, and only the files that match will be minimized.

For example, the build generates `/dist/foo.[hash].js` and some other JS files, we only minify `foo.js`:

```js
new rspack.SwcJsMinimizerRspackPlugin({
  test: /dist\/foo\.\w+\.js$/,
});
```

### include

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

Same as `test`, specify the files to be minimized.

```js
new rspack.SwcJsMinimizerRspackPlugin({
  include: /dist\/foo\.\w+\.js$/,
});
```

### exclude

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

Specify the files to be excluded. You can use regular expressions or file path strings, and the files that match will not be minimized.

For example, the build generates `/dist/foo.[hash].js` and some other JS files, we exclude the minimization of `foo.js`:

```js
new rspack.SwcJsMinimizerRspackPlugin({
  exclude: /dist\/foo\.\w+\.js$/,
});
```

### extractComments

- **Type:**

```ts
type ExtractCommentsOptions =
  | boolean
  | RegExp
  | {
      condition?: boolean | RegExp | undefined;
      banner?: string | boolean | undefined;
    };
```

- **Default:** `undefined`

Whether comments shall be extracted to a separate file. If the original file is named `foo.js`, then the comments will be stored to `foo.js.LICENSE.txt`.

#### Boolean form

If value is `true`, it is equivalent to `/@preserve|@lic|@cc_on|^\**!/` regexp condition and remove remaining comments.

```js
new rspack.SwcJsMinimizerRspackPlugin({
  extractComments: {
    condition: /@preserve|@lic|@cc_on|^\**!/,
  },
});
```

If value is `false`, all comments will be removed.

```js
new rspack.SwcJsMinimizerRspackPlugin({
  extractComments: false,
});
```

#### Regular expression form

If value is `RegExp`, all comments that match the given expression will be extracted to the separate file.

```js
new rspack.SwcJsMinimizerRspackPlugin({
  extractComments: /@preserve|@lic|@cc_on|^\**!/,
});
```

#### Object form

If value is `object`, it can use `condition` and `banner` to customize the extraction.

```js
new rspack.SwcJsMinimizerRspackPlugin({
  extractComments: {
    // add comments that match the condition will be extracted
    condition: /@preserve|@lic|@cc_on|^\**!/,
    // add banner to the top of the `*.LICENSE.txt` file
    // If `true`, use the default banner `/*! LICENSE: {relative} */`
    // If `false`, no banner will be added
    // If `string`, use the given banner
    banner: true,
  },
});
```

### minimizerOptions

- **Type:**

```ts
type MinimizerOptions = {
  minify?: boolean;
  module?: boolean;
  ecma?: 5 | 2015 | 2016 | string | number;
  mangle?: TerserMangleOptions | boolean;
  compress?: TerserCompressOptions | boolean;
  format?: JsFormatOptions & ToSnakeCaseProperties<JsFormatOptions>;
};
```

- **Default:**

```js
const defaultOptions = {
  minify: true,
  mangle: true,
  ecma: 5, // or derived from Rspack's target configuration
  compress: {
    passes: 2,
  }
  format: {
    comments: false,
  },
};
```

:::tip Default ecma from Rspack target
If `ecma` is not specified, `SwcJsMinimizerRspackPlugin` will automatically derive a default value from Rspack's [`target`](/config/target.md) configuration. Otherwise, it defaults to `5`.

This means you can rely on your Rspack `target` configuration without manually specifying the same ecma version in the plugin options.
:::

Similar to the `jsc.minify` option of SWC, please refer to [SWC - Minification](https://swc.rs/docs/configuration/minification) for all available options.

For example, disable `mangle` to avoid mangling variable names:

```js
new rspack.SwcJsMinimizerRspackPlugin({
  minimizerOptions: {
    mangle: false,
  },
});
```

For example, set a higher `passes` to run more compression passes. In some cases this may result in a smaller bundle size, but the more passes that are run, the more time it takes to compress.

```js
new rspack.SwcJsMinimizerRspackPlugin({
  minimizerOptions: {
    compress: {
      passes: 4,
    },
  },
});
```



---
url: /plugins/context-replacement-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# ContextReplacementPlugin

`ContextReplacementPlugin` changes which modules dynamic `require`, dynamic `import()`, and [`require.context()`](/api/runtime-api/module-methods.md#requirecontext) calls can load, and where Rspack looks for them.

Rspack represents these requests as [context modules](/misc/glossary.md#context-module). For example, `import('./locales/' + name + '.js')` creates a context module.

Use [`resourceRegExp`](#resourceregexp) to select the context modules to modify. `ContextReplacementPlugin` can replace their search directory, recursive behavior, request-matching regular expression, or request map. Omitted arguments keep the original values, and other context modules are unchanged.

The plugin also suppresses the `Critical dependency` warning for matched contexts.

## Examples

### Limit the modules in a context

Suppose `src/locales` contains `en.js`, `fr.js`, and `zh.js`, and the entry loads a locale dynamically:

```js title="src/index.js"
export const loadLocale = (name) => import(`./locales/${name}.js`);
```

The following configuration searches only the top level of `src/locales` and includes only the English and Chinese locale modules:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  entry: './src/index.js',
  plugins: [
    new rspack.ContextReplacementPlugin(
      /[/\\]locales$/,
      false,
      /^\.\/(en|zh)\.js$/,
    ),
  ],
};
```

The generated context map contains only these request keys:

```js title="dist/main.js (simplified)"
const localeRequestMap = {
  './en.js': 'module-id-for-en',
  './zh.js': 'module-id-for-zh',
};
```

## Options

The plugin accepts positional arguments, so their order matters.

### resourceRegExp

- **Type:** `RegExp`
- **Required:** Yes

Selects the context modules to modify. Before resolution, Rspack tests the expression against the context request, such as `./locales`. After resolution, it tests the same expression against the resolved context resource directory, which is normally an absolute path. At each matching phase, Rspack applies the replacement arguments supported by that phase. A context that does not match at either phase is unchanged.

Use a regular expression that accounts for both `/` and `\` when matching directory separators. If no other arguments are passed, Rspack keeps the inferred resource, recursive flag, and request regular expression, but still removes the critical dependency warning from a matched context.

```js
new rspack.ContextReplacementPlugin(/[/\\]locales$/);
```

### newContentResource

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

Replaces the resource directory from which a matched context resolves modules. When `resourceRegExp` matches before resolution, this value replaces the context request and is resolved as the new request. When `resourceRegExp` matches the resolved resource, an absolute value replaces that resource directly, while a relative value is resolved from the previous resource directory.

Pass `newContentResource` as the second argument. If it is omitted, Rspack keeps the inferred resource. When it is followed by [`newContentCreateContextMap`](#newcontentcreatecontextmap), the replacement resource is also the base directory for the map's compile-time requests.

```js
new rspack.ContextReplacementPlugin(
  /[/\\]src[/\\]locales$/,
  '../translated-locales',
);
```

For a context originally resolved to `src/locales`, this example changes the resource to the sibling directory `src/translated-locales`.

### newContentRecursive

- **Type:** `boolean`
- **Default:** `undefined`

Replaces the recursive flag used when Rspack discovers modules under the context resource. Set it to `true` to search subdirectories or `false` to search only the resource directory itself. If omitted, Rspack keeps the recursive behavior inferred from the original context.

This flag controls which directories Rspack scans before [`newContentRegExp`](#newcontentregexp) filters the generated request keys. It is not used with [`newContentCreateContextMap`](#newcontentcreatecontextmap), because an explicit map replaces directory scanning.

- **Without resource replacement:** Pass the boolean as the second argument.

  ```js
  new rspack.ContextReplacementPlugin(/[/\\]locales$/, false);
  ```

- **With resource replacement:** Pass the resource string second and the boolean third.

  ```js
  new rspack.ContextReplacementPlugin(
    /[/\\]src[/\\]locales$/,
    '../translated-locales',
    false,
  );
  ```

### newContentRegExp

- **Type:** `RegExp`
- **Default:** `undefined`

Replaces the regular expression used to select request keys while Rspack scans the context resource. It is tested against context-relative requests such as `./en.js`, not absolute file paths. This expression replaces the inferred expression; the two expressions are not combined. If omitted, Rspack keeps the inferred expression.

[`newContentRecursive`](#newcontentrecursive) first determines which directories are scanned, then `newContentRegExp` filters the request keys found in those directories. This argument is not used with [`newContentCreateContextMap`](#newcontentcreatecontextmap), because the map supplies the complete set of request keys.

- **Without resource or recursive replacement:** Pass the regular expression as the second argument.

  ```js
  new rspack.ContextReplacementPlugin(/[/\\]locales$/, /^\.\/(en|zh)\.js$/);
  ```

- **With recursive replacement only:** Pass the boolean second and the regular expression third.

  ```js
  new rspack.ContextReplacementPlugin(
    /[/\\]locales$/,
    false,
    /^\.\/(en|zh)\.js$/,
  );
  ```

- **With resource replacement:** Pass the resource string second, a boolean third, and the regular expression fourth. The boolean cannot be skipped.

  ```js
  new rspack.ContextReplacementPlugin(
    /[/\\]src[/\\]locales$/,
    '../translated-locales',
    false,
    /^\.\/(en|zh)\.js$/,
  );
  ```

### newContentCreateContextMap

- **Type:** `Record<string, string>`
- **Default:** `undefined`

Supplies the complete request map for a matched context. Each property key is a runtime request accepted by the context, and its value is the compile-time request resolved from `newContentResource`. Only keys in this map are available at runtime. Resource queries and fragments from the context are appended to the mapped compile-time requests.

Pass the map as the third argument after a `newContentResource` string. This form replaces automatic directory scanning, so it is an alternative to `newContentRecursive` and `newContentRegExp`. If the map is omitted, Rspack discovers modules using the current resource, recursive flag, and request regular expression.

Rspack installs the map after resolving the context. Therefore, `resourceRegExp` must match the resource seen after resolution; matching only the pre-resolution request is not sufficient.

```js
new rspack.ContextReplacementPlugin(
  /[/\\]src[/\\]locales$/,
  '../translated-locales',
  {
    './en.js': './en.js',
    './default.js': './en.js',
  },
);
```

For a context originally resolved to `src/locales`, this example loads modules from `src/translated-locales`. At runtime, both `./en.js` and `./default.js` load the compile-time request `./en.js` from that replacement resource.


This page is adapted from [webpack documentation](https://webpack.js.org/plugins/context-replacement-plugin/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /plugins/define-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# DefinePlugin

The `DefinePlugin` replaces variables in your code with other values or expressions at compile time. This can be useful for allowing different behavior between development builds and production builds. If you perform logging in your development build but not in the production build you might use a global constant to determine whether logging takes place. That's where `DefinePlugin` shines, set it and forget it rules for development and production builds.

## Examples

### Basic use case

Each key passed into `DefinePlugin` is an identifier or multiple identifiers joined with `.`.

- If the value is a string it will be used as a code fragment.
- If the value isn't a string, it will be stringified (including functions).
- If the value is an object all keys are defined the same way.
- If you prefix `typeof` to the key, it's only defined for typeof calls.

The values will be inlined into the code allowing a minification pass to remove the redundant conditional.

```js
new rspack.DefinePlugin({
  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),
});
```

```js
console.log('Running App version ' + VERSION);
if (!BROWSER_SUPPORTS_HTML5) require('html5shiv');
```

:::warning
When defining values for `process` prefer `'process.env.NODE_ENV': JSON.stringify('production')` over `process: { env: { NODE_ENV: JSON.stringify('production') } }`. Using the latter will overwrite the `process` object which can break compatibility with some modules that expect other values on the process object to be defined.
:::

:::tip
Note that because the plugin does a direct text replacement, the value given to it must include **actual quotes** inside of the string itself. Typically, this is done either with alternate quotes, such as `'"production"'`, or by using `JSON.stringify('production')`.
:::

```js
if (!PRODUCTION) {
  console.log('Debug info');
}

if (PRODUCTION) {
  console.log('Production log');
}
```

After passing through Rspack with no minification results in:

```js
if (!true) {
  console.log('Debug info');
}
if (true) {
  console.log('Production log');
}
```

and then after a minification pass results in:

```js
console.log('Production log');
```

### Feature flags

Enable/disable features in production/development build using [feature flags](https://en.wikipedia.org/wiki/Feature_toggle).

```js
new rspack.DefinePlugin({
  NICE_FEATURE: JSON.stringify(true),
  EXPERIMENTAL_FEATURE: JSON.stringify(false),
});
```

### Service URLs

Use a different service URL in production/development builds:

```js
new rspack.DefinePlugin({
  SERVICE_URL: JSON.stringify('https://dev.example.com'),
});
```

## Options

- **Type:**

```ts
type CodeValue = RecursiveArrayOrRecord<CodeValuePrimitive>;
type CodeValuePrimitive =
  null | undefined | RegExp | Function | string | number | boolean | bigint;
type RecursiveArrayOrRecord<T> =
  | { [index: string]: RecursiveArrayOrRecord<T> }
  | Array<RecursiveArrayOrRecord<T>>
  | T;

type DefinePluginOptions = Record<string, CodeValue>;
```

Maps identifiers or property paths to the code fragments that replace them at compile time. Each key in the object is one definition, such as `DEBUG` or `process.env.NODE_ENV`.

## Use `JSON.stringify`

Use `JSON.stringify` when you want to inject a literal value rather than a code fragment.

Common cases include:

- Injecting string constants such as environment names, versions, or API endpoints.
- Injecting objects or arrays that should be read directly in application code.
- Injecting string values from environment variables such as `process.env.*`.

This is because string values passed to `DefinePlugin` are inserted directly as code and do not get quotes added automatically.

```js
new rspack.DefinePlugin({
  MODE: 'production',
  MODE_STRINGIFIED: JSON.stringify('production'),
});
```

```js
const mode = MODE;
const modeStringified = MODE_STRINGIFIED;

// Turns into
const mode = production;
const modeStringified = 'production';
```

In the example above, `MODE` is treated as the identifier `production` instead of the string `'production'`, which will usually cause a runtime error. `MODE_STRINGIFIED` is replaced with a valid string literal, making it the safer option.

If you need to inject an object or array, `JSON.stringify` is also recommended:

```js
new rspack.DefinePlugin({
  APP_INFO: JSON.stringify({
    name: 'demo',
    features: ['a', 'b'],
  }),
});
```

This makes `APP_INFO` a usable object literal in the generated code. By contrast, `APP_INFO: { ... }` would be treated by `DefinePlugin` as a nested definition config and processed recursively, rather than being injected as an object literal into application code.


This page is adapted from [webpack documentation](https://webpack.js.org/plugins/define-plugin/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /plugins/entry-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# EntryPlugin

Adds an entry chunk on compilation. The chunk is named `options.name` and contains only one module (plus dependencies). The module is resolved from `entry` in `context` (absolute path).

## Examples

Register an entry from a plugin:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.EntryPlugin(process.cwd(), './src/index.js', { name: 'main' }),
  ],
};
```

## Options

### context

The module is resolved from `entry` in `context` (absolute path).

- **Type:** `string`

### entry

The module path for the entry module.

- **Type:** `string`

### options

To adjust settings related to the entry module.

- **Type:**

```ts
type EntryOptions =
  | string
  | (Omit<EntryDescriptionNormalized, 'import'> & {
      /**
       * The name of the entry chunk.
       */
      name?: string;
    });
```

If `options` is a string, its value will be used as `name`.

Refer to [Entry description object](/config/entry.md#entry-description-object) for all available options.

## Global entry

When the plugin's `name` option is set to `undefined`, the entry is treated as a global entry. It's automatically injected into:

1. All regular entry chunks
2. All asynchronous entries (for example, worker chunks created with `new Worker()`)

This allows you to inject global runtime code, such as the dev server's HMR runtime or the initialization logic for module federation.

```js
new rspack.EntryPlugin(context, './global-runtime.js', { name: undefined });
```



---
url: /plugins/environment-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# EnvironmentPlugin

`EnvironmentPlugin` is shorthand for defining selected [`process.env`](https://nodejs.org/api/process.html#process_process_env) values with [`DefinePlugin`](/plugins/define-plugin.md). It reads environment variables when Rspack builds and replaces the corresponding `process.env.*` expressions in your bundled code.

## Examples

### Basic usage

Pass environment variable names as separate arguments or as an array. The following calls are equivalent:

```js
new rspack.EnvironmentPlugin('NODE_ENV', 'DEBUG');

new rspack.EnvironmentPlugin(['NODE_ENV', 'DEBUG']);
```

Both configurations create definitions equivalent to:

```js
new rspack.DefinePlugin({
  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
  'process.env.DEBUG': JSON.stringify(process.env.DEBUG),
});
```

If a requested variable is missing and has no default value, compilation fails with an `EnvVariableNotDefinedError`.

### Using default values

Pass an object to provide a default value for each variable. A default is used only when the corresponding key is `undefined` in `process.env` when the build starts.

```js
new rspack.EnvironmentPlugin({
  NODE_ENV: 'development',
  DEBUG: false,
});
```

`EnvironmentPlugin` serializes default values with `JSON.stringify` before passing them to `DefinePlugin`. As a result, JSON-compatible defaults preserve their types: the `false` default above is injected as a boolean rather than a string.

Use `undefined` for a variable that must be provided during the build. If it is missing, compilation fails. Use `null` to provide an optional variable with a `null` fallback.

For example, suppose `entry.js` contains:

```js
if (process.env.NODE_ENV === 'production') {
  console.log('Welcome to production');
}
if (process.env.DEBUG) {
  console.log('Debugging output');
}
```

If `NODE_ENV=production` is set for the build and `DEBUG` is unset, the replacements are equivalent to:

```js
if ('production' === 'production') {
  // process.env.NODE_ENV comes from the environment
  console.log('Welcome to production');
}
if (false) {
  // process.env.DEBUG uses the default value
  console.log('Debugging output');
}
```

If `DEBUG=false` is set and `NODE_ENV` is unset, the replacements are equivalent to:

```js
if ('development' === 'production') {
  // process.env.NODE_ENV uses the default value
  console.log('Welcome to production');
}
if ('false') {
  // process.env.DEBUG comes from the environment
  console.log('Debugging output');
}
```

:::tip
Environment variables read from `process.env` are always strings. Setting `DEBUG=false` injects the string `'false'`, not the boolean `false`.
:::

### Using Git metadata

Default values can also be computed while loading the Rspack configuration. This example exposes the version and author date of the current Git commit:

```js
import { execFileSync } from 'node:child_process';

function git(...args) {
  return execFileSync('git', args, { encoding: 'utf8' }).trim();
}

new rspack.EnvironmentPlugin({
  GIT_VERSION: git('describe', '--always'),
  GIT_AUTHOR_DATE: git('log', '-1', '--format=%aI'),
});
```

### Loading `.env` files

`EnvironmentPlugin` does not read `.env` files by itself. To load variables from a file, use a third-party plugin such as [`dotenv-webpack`](https://github.com/mrsteele/dotenv-webpack):

```text title=".env"
PUBLIC_API_ORIGIN=https://api.example.com
FEATURE_ENABLED=true
```

```js
import Dotenv from 'dotenv-webpack';

new Dotenv({
  path: './.env',
});
```

Only load values that are safe to embed in client-side code, because injected values can be read from the generated bundle.

## Options

- **Type:**

```ts
declare class EnvironmentPlugin {
  constructor(...keys: string[]);
  constructor(keys: string[]);
  constructor(defaultValues: Record<string, any>);
}
```

Use either string form when every selected variable is required. Use the object form to provide default values; assigning `undefined` still marks that variable as required.


This page is adapted from [webpack documentation](https://webpack.js.org/plugins/environment-plugin/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /plugins/externals-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# ExternalsPlugin

This plugin allows you to specify external dependencies that should not be bundled into the output files. This is particularly useful for libraries that are already available globally or managed by other scripts.
The [`externalsType`](/config/externals.md#externalstype) and [`externals`](/config/externals.md#externals) configurations leverage the plugin internally. Therefore, you can utilize the respective functionality directly through these configuration options without needing to use the plugin separately.

## Examples

Externalize React as a CommonJS dependency:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.ExternalsPlugin('commonjs', ['react'])],
};
```

## Options

### type

**Type:**

```ts
type ExternalsType =
  | 'var'
  | 'module'
  | 'assign'
  | 'this'
  | 'window'
  | 'self'
  | 'global'
  | 'commonjs'
  | 'commonjs2'
  | 'commonjs-module'
  | 'commonjs-static'
  | 'amd'
  | 'amd-require'
  | 'umd'
  | 'umd2'
  | 'jsonp'
  | 'system'
  | 'promise'
  | 'import'
  | 'module-import'
  | 'modern-module'
  | 'commonjs-import'
  | 'script'
  | 'node-commonjs';
```

Specifies the default type for the `externals`.

For more details, refer to [externalsType](/config/externals.md#externalstype).

### externals

**Type:**

```ts
type Externals = ExternalItem[] | ExternalItem;

type ExternalItem =
  | RegExp
  | string
  | (
      | ((
          data: ExternalItemFunctionData,
          callback: (err?: Error | null, result?: ExternalItemValue) => void,
        ) => void)
      | ((data: ExternalItemFunctionData) => Promise<ExternalItemValue>)
    );

type ExternalItemValue =
  | string[]
  | boolean
  | string
  | {
      [k: string]: any;
    };

type ExternalItemFunctionData = {
  context?: string;
  contextInfo?: ModuleFactoryCreateDataContextInfo;
  getResolve?: (
    options?: ResolveOptions,
  ) =>
    | ((
        context: string,
        request: string,
        callback: (err?: Error, result?: string) => void,
      ) => void)
    | ((context: string, request: string) => Promise<string>);
  request?: string;
};

type ModuleFactoryCreateDataContextInfo = {
  issuer: string;
  compiler: string;
};
```

**Prevent bundling** of certain `import`ed packages and instead retrieve these _external dependencies_ at runtime.

For more details, refer to [externals](/config/externals.md#externals).



---
url: /plugins/ignore-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# IgnorePlugin

This plugin ignores selected module references, so files referenced by matching `import` or `require` statements are not included in the bundle.

## How it works

Rspack examines each module reference before resolution. For a direct `import` or `require`, it checks the unresolved module specifier. For a dynamic lookup such as `require('./locale/' + name)`, it checks the context path extracted from the expression. Rspack ignores the module reference when the configured regular expression matches this value or the filter function returns `true`. Other module references are resolved and bundled normally.

`IgnorePlugin` does not replace an ignored module with an empty module. Instead, Rspack skips resolving it and does not generate the corresponding module. If the bundle executes the code generated for the matching `import` or `require`, that code throws an error whose `code` is `MODULE_NOT_FOUND` at runtime. Before using the plugin, make sure this code will not run in the target environment, or that the referencing code already handles a missing module.

Use [`resourceRegExp`](#resourceregexp) or [`checkResource`](#checkresource) to select module references to ignore. To limit a regular-expression rule by the referencing module's directory, combine [`contextRegExp`](#contextregexp) with [`resourceRegExp`](#resourceregexp).

## Common use cases

Use `IgnorePlugin` only when omitting the referenced module is safe. Common cases include:

- Removing groups of resources that a library discovers dynamically, such as Moment.js locale modules that the application does not use.
- Excluding optional or environment-specific modules when their code path will not run, or when the referencing code handles a missing module.
- Restricting an ignore rule to references from a particular package or directory, so the same module specifier can still resolve elsewhere.

## Examples

### Ignore a specific import

The following configuration ignores every module reference whose unresolved module specifier is exactly `./optional-feature`, regardless of the referencing module's directory:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  entry: './src/index.js',
  plugins: [
    new rspack.IgnorePlugin({
      resourceRegExp: /^\.\/optional-feature$/,
    }),
  ],
};
```

For example, the entry contains this static import:

```js title="src/index.js"
import './optional-feature';
```

Because `contextRegExp` is omitted, the rule applies to module references from every directory. Other module specifiers are resolved normally.

Rspack does not generate a module for `./optional-feature` or replace it with an empty module. The generated JavaScript does not retain the original `import` syntax. Instead, Rspack emits a missing-module expression at the corresponding position. When the entry evaluates this expression, it throws an error whose `code` is `MODULE_NOT_FOUND`:

```js title="dist/main.js (simplified)"
Object(
  (function __rspack_missing_module() {
    const error = new Error("Cannot find module './optional-feature'");
    error.code = 'MODULE_NOT_FOUND';
    throw error;
  })(),
);
```

This example deliberately demonstrates the runtime failure caused by executing an ignored static import.

### Ignore Moment.js locales

Moment.js loads locales dynamically with `require('./locale/' + name)`. Rspack extracts `./locale` as the context path for this expression. To ignore the lookup only when the referencing module is in a directory ending in `moment`, configure both `resourceRegExp` and `contextRegExp`:

```js
new rspack.IgnorePlugin({
  resourceRegExp: /^\.\/locale$/,
  contextRegExp: /moment$/,
});
```

The entry can import Moment.js normally:

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

console.log(moment().format());
```

Rspack tests `resourceRegExp` against the extracted context path `./locale`, not the resolved path `moment/locale`. Because both regular expressions match, the emitted bundle keeps Moment.js itself but contains no modules from `moment/locale`:

```js title="dist/main.js (simplified)"
// Moment.js core is included in the bundle.
// No moment/locale/*.js modules are included.
```

## Options

### resourceRegExp

- **Type:** `RegExp`
- **Default:** `undefined`

Rspack tests `resourceRegExp` before resolution. For a direct module reference, the tested value is the unresolved module specifier. For a dynamic module lookup, it is the context path extracted from the expression. For example, `import './optional-feature'` is tested as `./optional-feature`, while `require('./locale/' + name)` is tested as `./locale`. Neither value is a resolved absolute path.

When the expression matches and `contextRegExp` is omitted, Rspack does not generate the referenced module, regardless of the referencing module's directory. When `contextRegExp` is set, both expressions must match. If `resourceRegExp` is omitted, provide `checkResource`; omitting both is not valid according to the public options type.

```js
new rspack.IgnorePlugin({
  resourceRegExp: /^\.\/optional-feature$/,
});
```

### contextRegExp

- **Type:** `RegExp`
- **Default:** `undefined`

Tests the referencing module's directory (`context`), normally an absolute path. Rspack evaluates this expression only after `resourceRegExp` matches, and skips module generation only when both expressions match.

If omitted, a `resourceRegExp` match applies regardless of the referencing module's directory. `contextRegExp` has no effect without `resourceRegExp`; use the `context` parameter of `checkResource` when using the function form.

```js
new rspack.IgnorePlugin({
  resourceRegExp: /^\.\/optional-feature$/,
  contextRegExp: /[/\\]legacy$/,
});
```

### checkResource

- **Type:**

  ```ts
  (resource: string, context: string) => boolean;
  ```

- **Default:** `undefined`

Runs before Rspack resolves each module reference. `resource` is the same value tested by `resourceRegExp`: the unresolved module specifier for a direct reference, or the extracted context path for a dynamic lookup. `context` is the referencing module's directory. Return `true` to stop resolution and module generation. Return `false` to continue processing.

This is the function-based alternative to `resourceRegExp` and `contextRegExp`. If it is omitted, provide `resourceRegExp`. To restrict a function match by the referencing module's directory, test `context` inside the function.

Rspack evaluates `checkResource` before the regular expression options. If both forms are supplied, returning `true` takes priority and stops resolution and module generation immediately. Returning `false` lets Rspack evaluate `resourceRegExp` and `contextRegExp` next. Normal resolution continues only when neither form ignores the module reference.

```js
new rspack.IgnorePlugin({
  checkResource(resource, context) {
    return resource === './optional-feature' && /[/\\]legacy$/.test(context);
  },
});
```



---
url: /plugins/javascript-modules-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# JavascriptModulesPlugin

Handles the bundling of JavaScript, usually used to access the [hooks of the JavascriptModulesPlugin](/api/plugin-api/javascript-modules-plugin-hooks.md):

## Examples

```js title="rspack.config.mjs"
class MyJsMinimizerPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap(MyJsMinimizerPlugin.name, (compilation) => {
      // Access the chunkHash hooks of JavascriptModulesPlugin
      const hooks =
        compiler.rspack.javascript.JavascriptModulesPlugin.getCompilationHooks(
          compilation,
        );
      // Since the JS chunk has been optimized and its content has changed, the chunk hash for the JS chunk needs to be updated
      hooks.chunkHash.tap(MyJsMinimizerPlugin.name, (chunk, hash) => {
        hash.update(`minimized by ${MyJsMinimizerPlugin.name}`);
      });
      // Optimize the JS chunk
      compilation.hooks.processAssets.tap(
        MyJsMinimizerPlugin.name,
        (assets) => {
          optimize(assets);
        },
      );
    });
  }
}

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

## Static methods

### `getChunkFilenameTemplate`


[Added in v2.2.2](https://github.com/web-infra-dev/rspack/releases/tag/v2.2.2)

```ts
function getChunkFilenameTemplate(
  chunk: Chunk,
  outputOptions: Output,
): Filename | undefined;
```

Returns the filename template that is used to render the JavaScript file of the
given chunk, resolved in this order:

1. `chunk.filenameTemplate`, if the chunk carries its own template (for example
   a chunk produced by a `splitChunks` cache group with `filename` set).
2. [`output.filename`](/config/output.md#outputfilename), if the chunk can be initial.
3. [`output.chunkFilename`](/config/output.md#outputchunkfilename) otherwise.

```js
class MyPlugin {
  apply(compiler) {
    const { JavascriptModulesPlugin } = compiler.rspack.javascript;
    compiler.hooks.compilation.tap('MyPlugin', (compilation) => {
      compilation.hooks.afterSeal.tap('MyPlugin', () => {
        for (const chunk of compilation.chunks) {
          const template = JavascriptModulesPlugin.getChunkFilenameTemplate(
            chunk,
            compilation.outputOptions,
          );
          const filename = compilation.getPath(template, { chunk });
          console.log(filename);
        }
      });
    });
  }
}
```

:::info Difference from webpack
Hot update chunks are not currently supported because they are not yet exposed to the JavaScript side.
:::



---
url: /plugins/module-federation-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# ModuleFederationPlugin

`ModuleFederationPlugin` enables Module Federation in Rspack.

This plugin implements the Module Federation 1.5 specification. If you want to learn more about the core concepts, usage, and best practices of Module Federation, please refer to the [Module Federation Guide](/guide/advanced/module-federation.md).

## Install dependencies

This plugin depends on the runtime package [@module-federation/runtime-tools](https://www.npmjs.com/package/@module-federation/runtime-tools), which provides runtime support for Module Federation. Please install it first:


```sh [npm]
npm add @module-federation/runtime-tools
```

```sh [yarn]
yarn add @module-federation/runtime-tools
```

```sh [pnpm]
pnpm add @module-federation/runtime-tools
```

```sh [bun]
bun add @module-federation/runtime-tools
```

```sh [deno]
deno add npm:@module-federation/runtime-tools
```

## Examples

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  output: {
    // set uniqueName explicitly to make HMR works
    uniqueName: 'app',
  },
  plugins: [
    new rspack.container.ModuleFederationPlugin({
      name: 'app',
    }),
  ],
};
```

## Options

### implementation

- Type: `string`

Provide a path as the implementation for Module Federation 1.5 runtime, which defaults to [@module-federation/runtime-tools](https://github.com/module-federation/universe/tree/main/packages/runtime-tools).

### runtimePlugins

- Type:
  ```ts
  type RuntimePlugins =
    string[] | [plugin: string, options: Record<string, unknown>][];
  ```

Provide the plugins required to run Module Federation 1.5, which can extend its behavior and capabilities. Use an array of module paths, or an array of `[modulePath, options]` tuples when a plugin needs options.

### name

- Type: `string`

Define the unique name exposed to other containers in the current build. This name will exist as a global variable for the remote container.

### filename

- Type: `string`

Specify the filename of the remote container entry file. Other containers will load the exposed modules through this file.

### runtime

- Type: `string | false`

Define the runtime chunk for remote container entry.

### library

- Type: [`LibraryOptions`](/config/output.md#outputlibrary)

Define the output format of remote container entry. The default libraryType is "var".

### shareScope

- Type: `string | string[]`

Define the namespace for shared dependencies in the current container. By configuring share scopes between different containers, the sharing behavior of modules can be controlled, including determining which modules are shared between different containers. The default share scope is `"default"`.

### shareStrategy

- Type: `'version-first' | 'loaded-first'`

Control the loading strategy of shared dependencies:

- `'version-first'`: Version takes precedence. After setting, all _remotes_ entry files will be automatically loaded and **register** the corresponding shared dependencies to ensure that all shared dependency versions can be obtained. This strategy is recommended when there are strict version requirements.

- `'loaded-first'`: reuse first. After setting, the _remotes_ entry file will not be automatically loaded (it will only be loaded when needed), and registered shared dependencies will be reused first. This strategy is recommended when there are no strict requirements on the version and performance is required.

### remoteType

- Type: [`ExternalsType`](/config/externals.md#externalstype)

Defines how to load remote containers, defaulting to `"script"`, which loads via the `<script />` tag.

### remotes

- Type:
  ```ts
  type Remotes = (RemotesItem | RemotesObject)[] | RemotesObject;
  type RemotesItem = string;
  type RemotesItems = RemotesItem[];
  type ShareScope = string | string[];
  interface RemotesObject {
    [k: string]: RemotesConfig | RemotesItem | RemotesItems;
  }
  interface RemotesConfig {
    external: RemotesItem | RemotesItems;
    shareScope?: ShareScope;
  }
  ```

Definition of the modules and their addresses that will be loaded remotely. The key is the name of the remote container, the value is the global variable name exposed by the remote container and the URL of the remote container entry. You can also specify shareScope to control whether the remote container shares dependencies.

### exposes

- Type:
  ```ts
  type Exposes = (ExposesItem | ExposesObject)[] | ExposesObject;
  type ExposesItem = string;
  type ExposesItems = ExposesItem[];
  interface ExposesObject {
    [k: string]: ExposesConfig | ExposesItem | ExposesItems;
  }
  interface ExposesConfig {
    import: ExposesItem | ExposesItems;
    name?: string;
  }
  ```

Define how local modules can be referenced by remote containers. The key is the name of the module when referenced as a remote module in the remote container, and the value is the module path relative to the current folder. You can provide a name to specify the name of the exposed local module.

### shared

- Type:
  ```ts
  type Shared = (SharedItem | SharedObject)[] | SharedObject;
  type SharedItem = string;
  type ShareScope = string | string[];
  interface TreeShakingConfig {
    usedExports?: string[];
    mode?: 'server-calc' | 'runtime-infer';
    filename?: string;
  }
  interface SharedObject {
    [k: string]: SharedConfig | SharedItem;
  }
  interface SharedConfig {
    import?: false | SharedItem;
    eager?: boolean;
    packageName?: string;
    requiredVersion?: false | string;
    shareKey?: string;
    shareScope?: ShareScope;
    singleton?: boolean;
    strictVersion?: boolean;
    version?: false | string;
    treeShaking?: TreeShakingConfig;
  }
  ```

Specify which dependencies should be shared dependencies. This allows multiple micro-frontends to share the same instance of a dependency library to avoid loading the same code repeatedly. It can be an object dictionary where the keys are the names of the shared modules and the values are configuration or version strings. It can also be an array where the array items are the shared package names or configurations.

The SharedConfig can include the following sub-options:

- import: Module that should be placed in the share scope of the shared module. If the shared module cannot be found in the share scope of the shared module or the version is invalid, this provided module can be used as a fallback module.
- eager: If set to `true`, the shared module will be loaded in the initial chunk instead of being dynamically loaded when used. This means that the shared module will be loaded together with the main entry point regardless of whether it has been used. This can eliminate the delay caused by dynamic loading, but it will increase the size of the initial package. Also, please note that when this configuration is enabled, all provided modules and fallback modules will always be downloaded.
- packageName: Used to determine the package name and required version from `package.json`. Configuration is only necessary when the package name cannot be automatically determined based on the request.
- requiredVersion: Accepts semantic version number. For example, `"^1.2.3"`. Used to set the version range of shared modules. If the module version of the remote container does not meet this range, the module will not be loaded.
- shareKey: Use this key to search for the requested shared module in the share scope of the shared module. The default is the name of the shared module.
- shareScope: Define the share scope of the shared module. This allows different builds to use their own share scope independently without conflict. The default share scope is `"default"`.
- singleton: Ensure that shared modules are only loaded once between different versions, following the singleton pattern. This is necessary for libraries designed to run as singletons, such as React, as it can prevent various issues caused by instantiating multiple library instances.
- strictVersion: Used to strengthen `requiredVersion`. If set to `true`, the shared module must match the version specified in requiredVersion exactly, otherwise an error will be reported and the module will not be loaded. If set to `false`, it can tolerate imprecise matching.
- version: Explicitly set the version of the shared module. By default, the version in `package.json` will be used.
- treeShaking: Configure the treeshaking behavior of shared dependencies. By enabling treeshaking for shared dependencies, the size of shared dependencies can be reduced. Only effective when using Rspack as the build tool.
  - usedExports: Manually **add** export members used by shared dependencies.
  - mode: Configure the loading strategy for treeshaking.
    - `runtime-infer`: Infer based on the consumer's `usedExports`. If the provider's `usedExports` match the consumer's `usedExports`, the provider's `shared` will be used; otherwise, the consumer's own `shared` will be used. If neither condition is met, the full version is used.
    - `server-calc`: Decide whether to load shared dependencies based on the snapshot sent by the server.
  - filename: Customize the filename of the generated shared fallback entry.

### manifest


[Added in v1.6.1](https://github.com/web-infra-dev/rspack/releases/tag/v1.6.1)

- Type:
  ```ts
  type Manifest = boolean | ManifestConfig;
  interface ManifestConfig {
    filePath?: string;
    disableAssetsAnalyze?: boolean;
    fileName?: string;
  }
  ```

Used to control whether to generate a manifest and the corresponding generation configuration.

When enabled, the plugin emits both `mf-manifest.json` and `mf-stats.json` (you can customize the base name through `fileName`) on every build and writes them into the build output so other tooling can read them during the `processAssets` hook or from the final artifacts.

- `mf-stats.json`: Contains full build statistics, including the asset lists for exposes/shared/remotes, `metaData` (plugin version, build info, `remoteEntry`, etc.), and extra asset analysis data, making it suitable for later aggregation or diagnostics.
- `mf-manifest.json`: A runtime manifest distilled from the stats file. The structure stays stable and can be consumed by Module Federation clients when loading remote modules. The exposes/shared/remotes sections describe what is publicly exposed.

`ManifestConfig` provides the following options:

- `filePath`: Target directory for the manifest files. Applies to both manifest and stats outputs.
- `fileName`: Manifest file name. When set, the stats file automatically appends a `-stats` suffix (for example, `fileName: 'mf.json'` produces `mf.json` and `mf-stats.json`). All files are emitted into the directory defined by `filePath` (if provided).
- `disableAssetsAnalyze`: Disables asset analysis. When `true`, the manifest omits the `shared` and `exposes` fields, and the `remotes` entries will not include asset information.

### injectTreeShakingUsedExports


[Added in v2.0.0](https://github.com/web-infra-dev/rspack/releases/tag/v2.0.0)

Whether to inject the exports used by shared into the bundler runtime.

- Type: `boolean`
- Required: No
- Default: `true`

This option is used to control whether to inject the actual used export information of shared modules into the bundler runtime for more precise dependency management and optimization.

If you are using mode as 'server-calc', it is recommended to set this option to `false`.

### treeShakingSharedDir

Directory for outputting tree shaking shared fallback resources.

- Type: `string`
- Required: No
- Default: `'independent-packages'`

When shared dependency tree shaking is enabled, Module Federation splits unused shared module exports. This option specifies the output directory for these fallback resources.

### treeShakingSharedExcludePlugins

Configure additional plugin names to exclude during the shared dependency tree shaking/fallback build process.

- Type: `string[]`
- Required: No
- Default: `[]`

Rspack already excludes its Module Federation and tree-shaking helper plugins, as well as common HTML plugins. Use this option to add more plugin names to that exclusion list.

### treeShakingSharedPlugins

Allows users to explicitly specify which plugins should participate in the second treeshaking process for shared modules.

- Type: `string[]`
- Required: No
- Default: `undefined`

If `shared.treeShaking.mode` is set to 'server-calc', then in the deployment service, the shared dependencies that need tree shaking will be rebuilt. At this time, only shared dependencies are built, and the original project's build configuration will not be loaded.
If your project has special build configurations, such as setting externals, you can integrate these build configurations into an NPM Package, and then fill in the name and version of this plugin in `treeShakingSharedPlugins`, so that it can participate in the treeshaking process of shared modules in the second treeshaking process.

For example, a plugin `my-build-plugin` is provided, which sets `externals`:

```ts title='my-build-plugin'
class MyBuildPlugin {
  apply(compiler) {
    compiler.options.externals = {
      react: 'React',
    };
  }
}
export default MyBuildPlugin;
```

Publish this plugin version as `0.0.2`, then you only need to fill in the plugin name and version in `treeShakingSharedPlugins`:

```ts title='module-federation.config.ts'
export default {
  // ...
  treeShakingSharedPlugins: ['my-build-plugin@0.0.2'],
};
```

## FAQ

- Found non-downgraded syntax in the build output?

  If you need to be compatible with legacy browsers, please add [builtin:swc-loader](/guide/features/builtin-swc-loader.md) for syntax downgrade, and make sure it matches packages under `@module-federation` scope. Here is an example:

  ```js title="rspack.config.mjs"
  export default {
    module: {
      rules: [
        {
          include: [/@module-federation[\\/]/],
          use: {
            loader: 'builtin:swc-loader',
            options: {
              jsc: {
                target: 'es5',
              },
            },
          },
        },
      ],
    },
  };
  ```

- Multiple assets emit different content to the same filename mf-manifest.json

  Upgrade the `@module-federation` scoped npm package to `0.21.0` or above.



---
url: /plugins/module-federation-plugin-v1.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# ModuleFederationPluginV1

This plugin corresponds to Module Federation v1.0, which is the [ModuleFederationPlugin in webpack](https://webpack.js.org/plugins/module-federation-plugin/).

:::tip
Module Federation v1.0 is no longer being iterated. We recommend using Module Federation v1.5 or v2.0. See [Module Federation](/guide/advanced/module-federation.md).
:::

## Examples

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.container.ModuleFederationPluginV1({
      name: 'host',
    }),
  ],
};
```

## Options

- **Type:**

```ts
interface ModuleFederationPluginV1Options {
  name: string;
  filename?: string;
  exposes?: Exposes;
  remotes?: Remotes;
  shared?: Shared;
  runtime?: EntryRuntime;
  shareScope?: ShareScope;
  remoteType?: ExternalsType;
  library?: LibraryOptions;
  enhanced?: boolean;
}
```

The `name` option is required. For details about the shared fields, see [ModuleFederationPlugin options](/plugins/module-federation-plugin.md#options). Module Federation v1 does not support `implementation`, `runtimePlugins`, or `shareStrategy`.



---
url: /plugins/normal-module-replacement-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# NormalModuleReplacementPlugin

The `NormalModuleReplacementPlugin` allows you to replace resources that match `resourceRegExp` with `newResource`.

If `newResource` is relative, it is resolved relative to the previous resource.

If `newResource` is a function, it is expected to overwrite the request attribute of the supplied resource.

This can be useful for allowing different behaviour between builds.

:::tip
Note that the `resourceRegExp` is tested against the "request" on `beforeResolve` phase and the "resource" on `afterResolve` phase.

Also, please note that when using Windows, you have to accommodate for the different folder separator symbol. E.g. `/src\/environments\/environment\.ts/` won't work on Windows, you have to use `/src[\\/]environments[\\/]environment\.ts/` instead.
:::

## Examples

### Basic example

Replace a specific module when building for a production environment.

Say you have a configuration file `some/path/config.development.js` and a special version for production in `some/path/config.production.js`

Add the following plugin when building for production:

```js
new rspack.NormalModuleReplacementPlugin(
  /some\/path\/config\.development\.js/,
  './config.production.js',
);
```

### Advanced example

Conditional build depending on a specified environment.

Say you want a configuration with specific values for different build targets.

```js
export default function getRspackConfig(env) {
  const appTarget = env.APP_TARGET || 'VERSION_A';
  return {
    plugins: [
      new rspack.NormalModuleReplacementPlugin(
        /(.*)-APP_TARGET(\.*)/,
        function (resource) {
          resource.request = resource.request.replace(
            /-APP_TARGET/,
            `-${appTarget}`,
          );
        },
      ),
    ],
  };
}
```

Create the two configuration files:

```js title="app/config-VERSION_A.js"
export const config = {
  title: 'I am version A',
};
```

```js title="app/config-VERSION_B.js"
export const config = {
  title: 'I am version B',
};
```

Then import that configuration using the keyword you're looking for in the regexp:

```js
import { config } from './app/config-APP_TARGET';
console.log(config.title);
```

And now you get the right configuration imported depending on which target you're building for:

```bash
rspack --env APP_TARGET=VERSION_A
=> 'I am version A'

rspack --env APP_TARGET=VERSION_B
=> 'I am version B'
```

## Options

The plugin accepts two positional arguments.

### resourceRegExp

- **Type:** `RegExp`

Matches the module request during `beforeResolve` and the resolved resource during `afterResolve`.

### newResource

- **Type:** `string | ((data: ResolveData) => void)`

A replacement request or a function that updates the supplied resolve data. Relative replacement requests are resolved relative to the original resource.


This page is adapted from [webpack documentation](https://webpack.js.org/plugins/normal-module-replacement-plugin/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /plugins/provide-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# ProvidePlugin

Automatically load modules instead of having to `import` or `require` them everywhere.

## Examples

```js
new rspack.ProvidePlugin({
  identifier: 'module1',
  // ...
});
```

or

```js
new rspack.ProvidePlugin({
  identifier: ['module1', 'property1'],
  // ...
});
```

By default, module resolution path is current folder (`./**`) and `node_modules`.

It is also possible to specify full path:

```js
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

new rspack.ProvidePlugin({
  identifier: path.resolve(path.join(__dirname, 'src/module1')),
  // ...
});
```

Whenever the `identifier` is encountered as free variable in a module, the `module` is loaded automatically and the `identifier` is filled with the exports of the loaded `module` (or `property` in order to support named exports).

For importing the default export of an ES2015 module, you have to specify the default property of module.

### Using process in the browser

Enable `process` object support within a browser context.

```js
new rspack.ProvidePlugin({
  process: ['process/browser'],
});
```

the piece of code:

```js
console.log(process.version);
```

will be transformed behind the scenes to:

```js
import process from 'process/browser';
console.log(process.version);
```

### jQuery

To automatically load `jquery` we can point both variables it exposes to the corresponding node module:

```js
new rspack.ProvidePlugin({
  $: 'jquery',
  jQuery: 'jquery',
});
```

Then in any of our source code:

```js
// in a module
$('#item'); // <= works
jQuery('#item'); // <= also works
// $ is automatically set to the exports of module "jquery"
```

### Lodash map

```js
new rspack.ProvidePlugin({
  _map: ['lodash', 'map'],
});
```

### Vue.js

```js
new rspack.ProvidePlugin({
  Vue: ['vue/dist/vue.esm.js', 'default'],
});
```

## Options

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

Maps each identifier to the module that provides it.

- **String form:** Specifies the module specifier to load. The provided identifier is assigned the value returned by loading that module, such as a CommonJS module's `module.exports` or an ES module namespace object.
- **Array form:** The first item is the module specifier, and the remaining items form a property path into the value returned by loading that module. To provide the default export of an ES module, use `[moduleSpecifier, 'default']`.


This page is adapted from [webpack documentation](https://webpack.js.org/plugins/provide-plugin/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /plugins/virtual-modules-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# VirtualModulesPlugin


[Added in v1.5.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.5.0)Rspack only

`VirtualModulesPlugin` allows you to create, modify, and delete files in memory, and Rspack treats these virtual files as if they were real files existing in the file system.

This plugin is a Rust implementation of [webpack-virtual-modules](https://github.com/sysgears/webpack-virtual-modules), deeply integrated with Rspack to provide equivalent functionality with better performance.

## Examples

### Basic usage

When creating a `VirtualModulesPlugin` instance, you can directly configure virtual modules in the constructor:

```ts
import { rspack } from '@rspack/core';

new rspack.experiments.VirtualModulesPlugin({
  // ...modules
});
```

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.experiments.VirtualModulesPlugin({
      'src/generated/config.js': 'export default { version: "1.0.0" };',
      'src/generated/constants.js': `
        export const API_URL = "${process.env.API_URL || 'http://localhost:3000'}";
        export const DEBUG = ${process.env.NODE_ENV !== 'production'};
      `,
    }),
  ],
};
```

### Dynamic module creation

You can dynamically create or modify virtual modules using the `writeModule` method.

:::note
Because the plugin's virtual modules are managed on the Rust side,
the `writeModule` method becomes available only after the Rust compiler has been initialized.
For example, invoking `writeModule` within the `beforeCompile` or `compile` hooks
will throw the following error: `Error: Virtual file store has not been initialized.`
:::

- **Type:**

```ts
function writeModule(filePath: string, contents: string): void;
```

- **Parameters:**
  - `filePath`: The virtual file path relative to [compiler.context](/api/javascript-api/compiler.md#context)
  - `contents`: The content of the virtual file

- **Example:**

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

const virtualModulesPlugin = new rspack.experiments.VirtualModulesPlugin();

export default {
  plugins: [
    virtualModulesPlugin,
    {
      apply(compiler) {
        compiler.hooks.thisCompilation.tap('MyPlugin', () => {
          // Dynamically create virtual modules
          const moduleContent = generateSomeContent();
          virtualModulesPlugin.writeModule('src/dynamic.js', moduleContent);
        });
      },
    },
  ],
};
```

## Options

- **Type:** `Record<string, string>`
- **Default:** `{}`

The optional constructor argument maps each virtual file path to its contents. Paths are resolved relative to [compiler.context](/api/javascript-api/compiler.md#context).



---
url: /plugins/case-sensitive-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# CaseSensitivePlugin

Detect case sensitivity conflicts in referenced module names and emit warnings.

Different operating systems may handle case sensitivity in file systems differently. When code references module names that differ only in case, this can lead to unexpected errors during cross-platform compilation. This plugin helps to avoid such situations.

## Examples

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.CaseSensitivePlugin()],
};
```

The following example shows how `CaseSensitivePlugin` detects case conflicts.

Assume there is a `utils.js` file in the project:

```text
src/
  ├── a.js
  ├── b.js
  └── utils.js
```

When importing `utils.js` in `a.js` and `b.js`, if the case sensitivity in the import path is inconsistent, the plugin will emit a warning.

```js title="src/a.js"
import { helper } from './utils';
```

```js title="src/b.js"
import { helper } from './Utils';
```

The warning is as follows:

```bash
WARNING There are multiple modules with names that only differ in casing.
```

This warning indicates that there is a case sensitivity conflict in module names, ensuring that the same module is used with consistent case sensitivity in the project.

:::tip
`CaseSensitivePlugin` is based on module identifiers rather than the file system to determine case sensitivity differences.
:::

When the build output includes files whose names differ only in letter casing, the plugin will emit a warning to avoid potential conflicts on case-insensitive file systems.

```bash
WARNING Prevent writing to file that only differs in casing or query string from already written file.
This will lead to a race-condition and corrupted files on case-insensitive file systems.
  - main.js
  - MAIN.js
```



---
url: /plugins/circular-check-rspack-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# CircularCheckRspackPlugin


Rspack only

Reports circular import dependencies as compilation warnings by default. This is the recommended replacement for the deprecated [`CircularDependencyRspackPlugin`](/plugins/circular-dependency-rspack-plugin.md).

## Examples

Ignore specific warnings: when `CircularCheckRspackPlugin` reports warnings, you can use [`ignoreWarnings`](/config/other-options.md#ignorewarnings) to suppress specific circular dependency diagnostics.

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

export default {
  entry: './src/index.js',
  plugins: [new rspack.CircularCheckRspackPlugin()],
  ignoreWarnings: [
    {
      message: /Circular dependency detected:[\s\S]*src\/legacy\//,
    },
  ],
};
```

`ignoreWarnings` only suppresses warnings. If `failOnError` is `true`, use `exclude` or `onDetected` to control reporting instead.

## Options

### exclude

- **Type:** `RegExp`
- **Default:** `undefined`

If any path in a detected cycle matches `exclude`, that cycle will not be reported.

### include

- **Type:** `RegExp`
- **Default:** `undefined`

When `include` is provided, only cycles with at least one matching path will be reported.

### failOnError

- **Type:** `boolean`
- **Default:** `false`

When `true`, detected cycles will generate Error level diagnostics rather than Warnings.

We recommend using the default value with `ignoreWarnings` to ignore specific warnings.

### onDetected

- **Type:** `(args: { module: Module; paths: string[]; compilation: Compilation }) => void`
- **Default:** `undefined`

Called once for each detected circular dependency. Using this option disables the default behavior of adding diagnostics to the compilation.

`paths` contains the readable unique module identifiers in the detected cycle path.

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

export default {
  entry: './src/index.js',
  plugins: [
    new rspack.CircularCheckRspackPlugin({
      onDetected({ paths, compilation }) {
        compilation.warnings.push(
          new Error(`Circular dependency detected: ${paths.join(' -> ')}`),
        );
      },
    }),
  ],
};
```



---
url: /plugins/eval-source-map-dev-tool-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# EvalSourceMapDevToolPlugin

This plugin enables more fine grained control of source map generation. It is also enabled automatically by certain settings of the [`devtool`](/config/devtool.md) configuration option.

## Examples

### Basic use case

You can use the following code to replace the configuration option `devtool: eval-source-map` with an equivalent custom plugin configuration:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  devtool: false,
  plugins: [new rspack.EvalSourceMapDevToolPlugin({})],
};
```

### Exclude vendor maps

The following code would exclude source maps for any modules in the `vendor.js` bundle:

```js
new rspack.EvalSourceMapDevToolPlugin({
  exclude: ['vendor.js'],
});
```

## Options

### test

- **Type:** `string` `RegExp` `[string, RegExp]`

Include source maps for modules based on their extension (defaults to `.js`, `.mjs`, and `.css`).

### include

- **Type:** `string` `RegExp` `[string, RegExp]`

Include source maps for module paths that match the given value.

### exclude

- **Type:** `string` `RegExp` `[string, RegExp]`

Exclude modules that match the given value from source map generation.

### append

- **Type:** `string | function`

Appends the given value to the original asset. Usually the `#sourceMappingURL` comment. `[url]` is replaced with a URL to the source map file. `false` disables the appending.

### module

- **Type:** `boolean`

Indicates whether loaders should generate source maps (defaults to `true`).

### columns

- **Type:** `boolean`

Indicates whether column mappings should be used (defaults to `true`).


This page is adapted from [webpack documentation](https://webpack.js.org/plugins/eval-source-map-dev-tool-plugin/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /plugins/hot-module-replacement-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# HotModuleReplacementPlugin

Enables hot module replacement (HMR).

## Examples

Enabling HMR is straightforward and in most cases no options are necessary.

Note that HMR can not be used in production build. You can use `process.env.NODE_ENV` to determine if it is a development environment.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';
const isDev = process.env.NODE_ENV === 'development';

export default {
  plugins: [isDev && new rspack.HotModuleReplacementPlugin()],
};
```

## Runtime API

When you register the `HotModuleReplacementPlugin` plugin, Rspack will inject HMR related runtime APIs, such as `module.hot` and `import.meta.webpackHot`.

See [HMR API](/api/runtime-api/hmr.md) for more details.

## React Fast Refresh

To enable Fast Refresh in React projects, you also need to use the [@rspack/plugin-react-refresh](https://www.npmjs.com/package/@rspack/plugin-react-refresh) plugin.

See [React - Fast Refresh](/guide/integrations/react.md#fast-refresh) for more details.

## Preact Fast Refresh

To enable Fast Refresh in Preact projects, you also need to use the [@rspack/plugin-preact-refresh](https://www.npmjs.com/package/@rspack/plugin-preact-refresh) plugin.

See [Preact - Fast Refresh](/guide/integrations/preact.md#preact-refresh) for more details.



---
url: /plugins/no-emit-on-errors-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# NoEmitOnErrorsPlugin

`NoEmitOnErrorsPlugin` prevents Rspack from emitting assets when a compilation contains errors. Setting [`optimization.emitOnErrors`](/config/optimization.md#optimizationemitonerrors) to `false` applies this plugin internally.

## Examples

The following development configuration keeps the previous files in `dist` unchanged when the new compilation has an error:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  mode: 'development',
  entry: './src/index.js',
  plugins: [new rspack.NoEmitOnErrorsPlugin()],
};
```

For example, if `src/index.js` contains a syntax error, Rspack reports the error without writing assets from that compilation. The equivalent configuration is `optimization.emitOnErrors: false`.



---
url: /plugins/progress-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# ProgressPlugin

This plugin can be used to configure the progress bar.

Rspack uses [indicatif::ProgressBar](https://github.com/console-rs/indicatif) to draw the progress bar.

## Examples

Add a prefix to the progress bar:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.ProgressPlugin({ prefix: 'Building' })],
};
```

## Options

### Function form

- **Type:** `(percentage: number, message: string, info: ProgressPluginHandlerInfo) => void`
- **Default:** `undefined`

Pass a handler function directly to the `ProgressPlugin` constructor. It is called when hooks report progress with the following arguments:

- `percentage`: a number between 0 and 1 indicating the completion percentage of the compilation
- `message`: a short description of the currently-executing hook
- `info`: extra progress information
  - `builtModules`: number of built modules
  - `moduleIdentifier`: identifier of the active module (only provided during `build modules` updates)

```js
const handler = (percentage, message, info) => {
  // e.g. Output each progress message directly to the console:
  console.info(percentage, message, info.builtModules, info.moduleIdentifier);
};

new rspack.ProgressPlugin(handler);
```

### Object form

#### prefix

- **Type:** `string`
- **Default:** `''`

The text will be displayed before the progress bar.

#### profile

- **Type:** `boolean`
- **Default:** `false`

Tells `ProgressPlugin` to collect profile data for progress steps.

#### template

- **Type:** `string`
- **Default:** `● {prefix:.bold} {bar:25.green/white.dim} ({percent}%) {wide_msg:.dim}`

The template of progress bar.

Also see [indicatif::ProgressBar::with\_template](https://docs.rs/indicatif/latest/indicatif/style/struct.ProgressStyle.html#method.with_template).

#### tick

- **Type:** `string | string[] | undefined`
- **Default:** `undefined`

The tick string sequence for spinners, if it's string then it will be split into characters.

Also see [indicatif::ProgressBar::tick\_strings](https://docs.rs/indicatif/latest/indicatif/style/struct.ProgressStyle.html#method.tick_strings).

#### progressChars

- **Type:** `string`
- **Default:** `━━`

The progress characters `(filled, current, to do)`.

Also see [indicatif::ProgressBar::progress\_chars](https://docs.rs/indicatif/latest/indicatif/style/struct.ProgressStyle.html#method.progress_chars).



---
url: /plugins/source-map-dev-tool-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# SourceMapDevToolPlugin

This plugin enables more fine grained control of source map generation. It is also enabled automatically by certain settings of the [`devtool`](/config/devtool.md) configuration option.

## Examples

The following examples demonstrate some common use cases for this plugin.

### Basic use case

You can use the following code to replace the configuration option devtool: inline-source-map with an equivalent custom plugin configuration:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  devtool: false,
  plugins: [new rspack.SourceMapDevToolPlugin({})],
};
```

### Exclude vendor maps

The following code would exclude source maps for any modules in the vendor.js bundle:

```js
new rspack.SourceMapDevToolPlugin({
  filename: '[file].map[query]',
  exclude: ['vendor.js'],
});
```

### Host source maps externally

Set a URL for source maps. Useful for hosting them on a host that requires authorization.

```js
new rspack.SourceMapDevToolPlugin({
  append: '\n//# sourceMappingURL=https://example.com/sourcemap/[url]',
  filename: '[file].map[query]',
});
```

And for cases when source maps are stored in the upper level directory:

```
project
|- dist
  |- public
    |- bundle-[hash].js
  |- sourcemaps
    |- bundle-[hash].js.map
```

With the following config:

```js
new rspack.SourceMapDevToolPlugin({
  filename: 'sourcemaps/[file].map',
  publicPath: 'https://example.com/project/',
  fileContext: 'public',
});
```

Will produce the following URL:

```
https://example.com/project/sourcemaps/bundle-[hash].js.map
```

## Options

### test

- **Type:** `string` `RegExp` `[string, RegExp]`

Include source maps for modules based on their extension (defaults to `.js`, `.mjs`, and `.css`).

### include

- **Type:** `string` `RegExp` `[string, RegExp]`

Include source maps for module paths that match the given value.

### exclude

- **Type:** `string` `RegExp` `[string, RegExp]`

Exclude modules that match the given value from source map generation.

### filename

- **Type:** string

Defines the output filename of the SourceMap (will be inlined if no value is provided).

### append

- **Type:** `string` `function`

Appends the given value to the original asset. Usually the `#sourceMappingURL` comment. `[url]` is replaced with a URL to the source map file. Path parameters are supported: `[chunk]`, `[filename]` and `[contenthash]`. Setting append to false disables the appending.

### moduleFilenameTemplate

- **Type:** `string`

See [`output.devtoolModuleFilenameTemplate`](/config/output.md#outputdevtoolmodulefilenametemplate).

### fallbackModuleFilenameTemplate

- **Type:** `string`

See link above.

### namespace

- **Type:** `string`

See [`output.devtoolNamespace`](/config/output.md#outputdevtoolnamespace).

### module

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

Indicates whether loaders should generate source maps.

### columns

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

Indicates whether column mappings should be used.

### noSources

- **Type:** `boolean`
- **Default:** `false`

Prevents the source file content from being included in the source map.

### publicPath

- **Type:** `string`

Emits absolute URLs with public path prefix, e.g. `https://example.com/project/`.

### fileContext

- **Type:** `string`

Makes the `[file]` argument relative to this directory.

The `fileContext` option is useful when you want to store source maps in an upper level directory to avoid `../../` appearing in the absolute `[url]`.

### sourceRoot

- **Type:** `string`

Provide a custom value for the `sourceRoot` property in the SourceMap.

:::tip
Setting `module` and/or `columns` to `false` will yield less accurate source maps but will also improve compilation performance significantly.
:::

:::tip
If you want to use a custom configuration for this plugin in [development mode](/config/mode.md#development), make sure to disable the default one. I.e. set `devtool: false`.
:::


This page is adapted from [webpack documentation](https://webpack.js.org/plugins/source-map-dev-tool-plugin/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /plugins/low-level-plugins.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Low-level plugins

These plugins are publicly exposed low-level building blocks that Rspack primarily uses to implement target presets, runtime templates, child compilers, and higher-level plugins.

:::tip Usage guidance
For most application builds, prefer the corresponding high-level configuration. Direct use is mainly intended for custom compilers, child compilers, and advanced integrations.
:::

Categories of low-level plugins:

- [environment](#environment)
- [entry](#entry)
- [output](#output)
- [loader](#loader)
- [module federation](#module-federation)
- [experiments](#experiments)

## environment

Plugins affecting the compiler environment and runtime target.

### ElectronTargetPlugin \{#electron-target-plugin}

```js
new rspack.electron.ElectronTargetPlugin(context);
```

`ElectronTargetPlugin` keeps Electron built-in modules external so Electron can load them at runtime. Pass `'main'`, `'preload'`, or `'renderer'` to externalize the additional modules available in that process.

The [`externalsPresets.electron`](/config/externals.md#externalspresetselectron), [`externalsPresets.electronMain`](/config/externals.md#externalspresetselectronmain), [`externalsPresets.electronRenderer`](/config/externals.md#externalspresetselectronrenderer), and [`externalsPresets.electronPreload`](/config/externals.md#externalspresetselectronpreload) options apply this plugin internally.

For a regular Electron application, prefer the corresponding [target](/config/target.md):

```js title="rspack.config.mjs"
export default {
  target: 'electron-main',
  entry: './src/main.js',
};
```

When configuring a child compiler directly, apply the plugin to that compiler:

```js
new compiler.rspack.electron.ElectronTargetPlugin('main').apply(childCompiler);
```

### NodeEnvironmentPlugin

```js
new rspack.node.NodeEnvironmentPlugin(options);
```

`NodeEnvironmentPlugin` installs infrastructure logging, a cached Node.js input file system, the Node.js `fs` module as the output file system, and a watch file system on a compiler. The `rspack()` API applies it automatically to the root compiler.

When a custom compiler needs its own Node.js file-system environment, pass its normalized infrastructure logging options and apply the plugin directly:

```js
new compiler.rspack.node.NodeEnvironmentPlugin({
  infrastructureLogging: childCompiler.options.infrastructureLogging,
}).apply(childCompiler);
```

This plugin configures compiler I/O and logging; it does not set the JavaScript runtime target. Use `NodeTargetPlugin` when Node.js built-in modules should remain external.

### NodeTargetPlugin \{#node-target-plugin}

```js
new rspack.node.NodeTargetPlugin();
```

`NodeTargetPlugin` keeps Node.js built-in modules and requests using the `node:` scheme external so the Node.js runtime loads them instead of Rspack bundling them. The [`externalsPresets.node`](/config/externals.md#externalspresetsnode) option applies this plugin internally.

For a regular Node.js application, prefer the `node` target:

```js title="rspack.config.mjs"
export default {
  target: 'node',
  entry: './src/index.js',
};
```

When configuring a child compiler directly, apply the plugin to that compiler:

```js
new compiler.rspack.node.NodeTargetPlugin().apply(childCompiler);
```

## entry

Plugins that add entry chunks to the compilation.

### DynamicEntryPlugin

```js
new rspack.DynamicEntryPlugin(context, entry);
```

`DynamicEntryPlugin` calls an entry function during every `make` event and adds the returned entries to the compilation. This allows the entry list to change between watch rebuilds.

The direct API receives normalized entry descriptions, so each `import` value is an array:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

const context = process.cwd();

export default {
  context,
  entry: {},
  plugins: [
    new rspack.DynamicEntryPlugin(context, async () => ({
      main: {
        import: ['./src/index.js'],
      },
    })),
  ],
};
```

For a regular build, prefer an [`entry` function](/config/entry.md#entry), which Rspack normalizes and passes to this plugin automatically.

### EntryOptionPlugin

```js
new rspack.EntryOptionPlugin();
```

`EntryOptionPlugin` handles the `entryOption` compiler hook. It applies an `EntryPlugin` for each static entry request or a `DynamicEntryPlugin` for a function entry. Rspack applies it automatically to the root compiler.

The static `applyEntryOption` helper is useful when adding normalized entries to a child compiler:

```js
const childOptions = compiler.rspack.config.getNormalizedRspackOptions({
  entry: {
    child: './src/child.js',
  },
});

compiler.rspack.EntryOptionPlugin.applyEntryOption(
  childCompiler,
  compiler.context,
  childOptions.entry,
);
```

## output

Plugins affecting generated modules, chunks, and runtime loading.

### EnableChunkLoadingPlugin \{#enable-chunk-loading-plugin}

```js
new rspack.javascript.EnableChunkLoadingPlugin(type);
```

`EnableChunkLoadingPlugin` enables the runtime modules required by a chunk-loading type. Rspack normally applies it for the types collected in [`output.enabledChunkLoadingTypes`](/config/output.md#outputenabledchunkloadingtypes).

The supported built-in types are `'jsonp'`, `'import-scripts'`, `'require'`, `'async-node'`, and `'import'`.

Direct application is useful when a dynamic entry selects a type that Rspack cannot discover while normalizing the configuration:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  entry: () => ({
    main: {
      import: './src/index.js',
      chunkLoading: 'jsonp',
    },
  }),
  output: {
    chunkLoading: false,
  },
  plugins: [new rspack.javascript.EnableChunkLoadingPlugin('jsonp')],
};
```

For a custom chunk-loading implementation, call `EnableChunkLoadingPlugin.setEnabled(compiler, type)` after installing its runtime hooks. This method only registers the type; it does not implement chunk loading.

### EnableLibraryPlugin \{#enable-library-plugin}

```js
new rspack.library.EnableLibraryPlugin(type);
```

`EnableLibraryPlugin` registers a library output type with the compiler. Rspack normally applies it for the types collected in [`output.enabledLibraryTypes`](/config/output.md#outputenabledlibrarytypes).

The following dynamic entry selects the `'var'` library type and enables it explicitly because Rspack cannot inspect a function entry during configuration normalization:

```js title="src/index.js"
export const add = (a, b) => a + b;
```

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  entry: () => ({
    main: {
      import: './src/index.js',
      library: {
        name: 'MathLibrary',
        type: 'var',
      },
    },
  }),
  plugins: [new rspack.library.EnableLibraryPlugin('var')],
};
```

For a regular library build, prefer [`output.library`](/config/output.md#outputlibrary), which automatically enables its library type.

### EnableWasmLoadingPlugin \{#enable-wasm-loading-plugin}

```js
new rspack.wasm.EnableWasmLoadingPlugin(type);
```

`EnableWasmLoadingPlugin` enables the runtime modules required by a WebAssembly loading type. Rspack normally applies it for the types collected in [`output.enabledWasmLoadingTypes`](/config/output.md#outputenabledwasmloadingtypes).

The supported types are `'fetch'`, `'async-node'`, and `'universal'`.

The following example sets `output.wasmLoading` to `false` to disable automatic setup, then directly applies `EnableWasmLoadingPlugin` to install the `'fetch'` loading runtime:

```js title="src/index.js"
import { add } from './add.wasm';

console.log(add(1, 2));
```

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  target: 'web',
  entry: './src/index.js',
  experiments: {
    asyncWebAssembly: true,
  },
  output: {
    wasmLoading: false,
  },
  plugins: [new rspack.wasm.EnableWasmLoadingPlugin('fetch')],
};
```

For a regular build, prefer [`output.wasmLoading`](/config/output.md#outputwasmloading), which automatically enables the selected type.

### EvalDevToolModulePlugin

```js
new rspack.EvalDevToolModulePlugin(options);
```

`EvalDevToolModulePlugin` wraps each non-external JavaScript module in `eval` and appends a `sourceURL`, allowing browser developer tools to display the original module name. Setting `devtool: 'eval'` applies this plugin automatically.

The following configuration applies it directly and uses `dashboard` as the source URL namespace:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  mode: 'development',
  devtool: false,
  plugins: [
    new rspack.EvalDevToolModulePlugin({
      namespace: 'dashboard',
    }),
  ],
};
```

The `moduleFilenameTemplate` and `sourceUrlComment` options can customize the generated module URL and comment format.

### FetchCompileAsyncWasmPlugin

```js
new rspack.web.FetchCompileAsyncWasmPlugin();
```

`FetchCompileAsyncWasmPlugin` adds the browser runtime that fetches and compiles asynchronous WebAssembly modules. `EnableWasmLoadingPlugin('fetch')` applies this implementation internally.

This example disables automatic WebAssembly loading setup and installs the fetch implementation directly:

```js title="src/index.js"
import { add } from './add.wasm';

console.log(add(1, 2));
```

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  target: 'web',
  entry: './src/index.js',
  experiments: {
    asyncWebAssembly: true,
  },
  output: {
    wasmLoading: false,
  },
  plugins: [new rspack.web.FetchCompileAsyncWasmPlugin()],
};
```

For a regular web build, prefer `output.wasmLoading: 'fetch'`, which enables the same runtime automatically.

### JsonpTemplatePlugin \{#jsonp-template-plugin}

```js
new rspack.web.JsonpTemplatePlugin();
```

`JsonpTemplatePlugin` configures browser output for child compilers. It sets [`output.chunkLoading`](/config/output.md#outputchunkloading) to `'jsonp'`, applies the [`'array-push'` chunk format](/config/output.md#outputchunkformat), and enables the required JSONP chunk-loading runtime.

The following browser entry creates an asynchronous chunk:

```js title="src/browser-child.js"
document.querySelector('button').addEventListener('click', async () => {
  const { message } = await import('./message.js');
  console.log(message);
});
```

```js title="src/message.js"
export const message = 'Hello from the child compiler';
```

This configuration creates a child compiler and applies `JsonpTemplatePlugin` directly:

```js title="rspack.config.mjs"
export default {
  target: 'web',
  entry: {},
  plugins: [
    (compiler) => {
      compiler.hooks.make.tapAsync(
        'BrowserChildCompiler',
        (compilation, callback) => {
          const childCompiler = compilation.createChildCompiler(
            'browser-child',
            {
              filename: 'browser-child.js',
              chunkFilename: '[name].browser-child.js',
            },
            [
              new compiler.rspack.web.JsonpTemplatePlugin(),
              new compiler.rspack.EntryPlugin(
                compiler.context,
                './src/browser-child.js',
                { name: 'browser-child' },
              ),
            ],
          );

          childCompiler.runAsChild((error) => callback(error));
        },
      );
    },
  ],
};
```

`JsonpTemplatePlugin` makes the child compiler emit array-push chunks and load asynchronous chunks by adding `script` elements to the page.

For a regular web build, prefer `target: 'web'`. It selects the `'array-push'` chunk format and `'jsonp'` chunk loading through Rspack's target defaults. Setting `output.chunkLoading: 'jsonp'` only selects the loading implementation; it does not apply `JsonpTemplatePlugin` or choose the chunk format.

### NodeTemplatePlugin \{#node-template-plugin}

```js
new rspack.node.NodeTemplatePlugin(options);
```

`NodeTemplatePlugin` configures Node.js output for child compilers. It applies the [`'commonjs'` chunk format](/config/output.md#outputchunkformat), sets [`output.chunkLoading`](/config/output.md#outputchunkloading) to `'require'` by default, and enables the required chunk-loading runtime.

#### asyncChunkLoading

- Type: `boolean`
- Default: `false`

When `asyncChunkLoading` is `true`, the plugin uses `'async-node'` chunk loading instead of `'require'`.

The following Node.js entry creates an asynchronous chunk:

```js title="src/node-child.js"
async function main() {
  const { run } = await import('./task.js');
  run();
}

main();
```

```js title="src/task.js"
export function run() {
  console.log('Task completed');
}
```

This configuration creates a child compiler and applies `NodeTemplatePlugin` directly:

```js title="rspack.config.mjs"
export default {
  target: 'node',
  entry: {},
  plugins: [
    (compiler) => {
      compiler.hooks.make.tapAsync(
        'NodeChildCompiler',
        (compilation, callback) => {
          const childCompiler = compilation.createChildCompiler(
            'node-child',
            {
              filename: 'node-child.js',
              chunkFilename: '[name].node-child.js',
            },
            [
              new compiler.rspack.node.NodeTemplatePlugin(),
              new compiler.rspack.EntryPlugin(
                compiler.context,
                './src/node-child.js',
                { name: 'node-child' },
              ),
            ],
          );

          childCompiler.runAsChild((error) => callback(error));
        },
      );
    },
  ],
};
```

`NodeTemplatePlugin` makes the child compiler emit CommonJS chunks and load asynchronous chunks with `require`.

For a regular Node.js build, prefer `target: 'node'`. It selects the `'commonjs'` chunk format and `'require'` chunk loading through Rspack's target defaults. Setting `output.chunkLoading: 'require'` only selects the loading implementation; it does not apply `NodeTemplatePlugin` or choose the chunk format.

### WebWorkerTemplatePlugin \{#web-worker-template-plugin}

```js
new rspack.webworker.WebWorkerTemplatePlugin();
```

`WebWorkerTemplatePlugin` configures Web Worker output for child compilers. It sets [`output.chunkLoading`](/config/output.md#outputchunkloading) to `'import-scripts'`, applies the [`'array-push'` chunk format](/config/output.md#outputchunkformat), and enables the required `importScripts` chunk-loading runtime.

The following worker creates an asynchronous chunk:

```js title="src/worker-child.js"
self.onmessage = async ({ data }) => {
  const { double } = await import('./math.js');
  self.postMessage(double(data));
};
```

```js title="src/math.js"
export const double = (value) => value * 2;
```

This configuration creates a child compiler and applies `WebWorkerTemplatePlugin` directly:

```js title="rspack.config.mjs"
export default {
  target: 'webworker',
  entry: {},
  plugins: [
    (compiler) => {
      compiler.hooks.make.tapAsync(
        'WorkerChildCompiler',
        (compilation, callback) => {
          const childCompiler = compilation.createChildCompiler(
            'worker-child',
            {
              filename: 'worker-child.js',
              chunkFilename: '[name].worker-child.js',
            },
            [
              new compiler.rspack.webworker.WebWorkerTemplatePlugin(),
              new compiler.rspack.EntryPlugin(
                compiler.context,
                './src/worker-child.js',
                { name: 'worker-child' },
              ),
            ],
          );

          childCompiler.runAsChild((error) => callback(error));
        },
      );
    },
  ],
};
```

`WebWorkerTemplatePlugin` makes the child compiler emit array-push chunks and load asynchronous chunks with `importScripts`.

For a regular Web Worker build, prefer `target: 'webworker'`. It selects the `'array-push'` chunk format and `'import-scripts'` chunk loading through Rspack's target defaults. Setting `output.chunkLoading: 'import-scripts'` only selects the loading implementation; it does not apply `WebWorkerTemplatePlugin` or choose the chunk format.

## loader

Plugins that customize the context in which loaders execute.

### LoaderOptionsPlugin

```js
new rspack.LoaderOptionsPlugin(options);
```

`LoaderOptionsPlugin` copies custom option fields onto the loader context for resources matching `test`, `include`, and `exclude`. The matching fields themselves are used only as filters and are not copied.

This loader reads a custom `message` property from its context:

```js title="loaders/message-loader.cjs"
module.exports = function () {
  return `export default ${JSON.stringify(this.message)};`;
};
```

The plugin provides that property only while processing `.message` files:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  entry: './src/welcome.message',
  module: {
    rules: [
      {
        test: /\.message$/,
        use: './loaders/message-loader.cjs',
      },
    ],
  },
  plugins: [
    new rspack.LoaderOptionsPlugin({
      test: /\.message$/,
      message: 'Hello from the loader',
    }),
  ],
};
```

This plugin mainly supports loaders that read custom properties from `this`. New loaders should usually receive values through their own loader options.

### LoaderTargetPlugin

```js
new rspack.LoaderTargetPlugin(target);
```

`LoaderTargetPlugin` assigns `target` to `this.target` in every loader context. It is useful when a custom compiler needs loaders to observe a target that differs from the compiler's configured target.

The following loader replaces its input with the target it observes:

```js title="loaders/target-loader.cjs"
module.exports = function () {
  return `console.log(${JSON.stringify(this.target)});`;
};
```

Although the build target is `web`, this plugin makes the loader receive `'node'`:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  target: 'web',
  entry: './src/index.js',
  module: {
    rules: [
      {
        test: /index\.js$/,
        use: './loaders/target-loader.cjs',
      },
    ],
  },
  plugins: [new rspack.LoaderTargetPlugin('node')],
};
```

For a regular build, prefer the top-level [`target`](/config/target.md) option.

## module federation

These plugins implement the `exposes`, `remotes`, and `shared` parts of Module Federation. For regular application builds, prefer [`ModuleFederationPlugin`](/plugins/module-federation-plugin.md), which configures these low-level plugins together.

### ContainerPlugin

```js
new rspack.container.ContainerPlugin(options);
```

`ContainerPlugin` creates a container entry that exposes local modules through the Module Federation `get` and `init` interface. It is the low-level implementation of the `exposes` option.

This configuration emits `remoteEntry.js` and exposes `src/Button.js` as `./Button`:

```js title="rspack.config.mjs"
import { container } from '@rspack/core';

export default {
  entry: {},
  plugins: [
    new container.ContainerPlugin({
      name: 'catalog',
      filename: 'remoteEntry.js',
      exposes: {
        './Button': './src/Button.js',
      },
    }),
  ],
};
```

### ContainerReferencePlugin

```js
new rspack.container.ContainerReferencePlugin(options);
```

`ContainerReferencePlugin` registers remote containers as externals and adds the runtime needed to load modules from them. It is the low-level implementation of the `remotes` option.

With the following configuration, an import such as `import('catalog/Button')` loads `./Button` from the remote container:

```js title="rspack.config.mjs"
import { container } from '@rspack/core';

export default {
  entry: './src/index.js',
  plugins: [
    new container.ContainerReferencePlugin({
      remoteType: 'script',
      remotes: {
        catalog: 'catalog@http://localhost:3001/remoteEntry.js',
      },
    }),
  ],
};
```

### ConsumeSharedPlugin

```js
new rspack.sharing.ConsumeSharedPlugin(options);
```

`ConsumeSharedPlugin` resolves configured module requests from a share scope. It can enforce version and singleton requirements and use a local module as a fallback when no suitable provider is available.

This example consumes `react` as a singleton from the default share scope and falls back to the locally installed package without checking its version:

```js title="rspack.config.mjs"
import { sharing } from '@rspack/core';

export default {
  entry: './src/index.js',
  plugins: [
    new sharing.ConsumeSharedPlugin({
      consumes: {
        react: {
          import: 'react',
          requiredVersion: false,
          singleton: true,
        },
      },
    }),
  ],
};
```

### ProvideSharedPlugin

```js
new rspack.sharing.ProvideSharedPlugin(options);
```

`ProvideSharedPlugin` registers local modules and their versions in a share scope so other builds can consume them. It is the provider half of the `shared` option.

The shorthand form below provides the locally installed `react` package under the `react` share key and infers its version from the package metadata:

```js title="rspack.config.mjs"
import { sharing } from '@rspack/core';

export default {
  plugins: [
    new sharing.ProvideSharedPlugin({
      provides: ['react'],
    }),
  ],
};
```

### SharePlugin

```js
new rspack.sharing.SharePlugin(options);
```

`SharePlugin` applies both `ConsumeSharedPlugin` and `ProvideSharedPlugin` for the same `shared` configuration. It is the low-level equivalent of `ModuleFederationPlugin`'s `shared` option.

This example provides the local `react` package as a fallback and consumes a singleton instance from the default share scope:

```js title="rspack.config.mjs"
import { sharing } from '@rspack/core';

export default {
  plugins: [
    new sharing.SharePlugin({
      enhanced: false,
      shared: {
        react: {
          requiredVersion: false,
          singleton: true,
        },
      },
    }),
  ],
};
```

### TreeShakingSharedPlugin \{#tree-shaking-shared-plugin}

```js
new rspack.sharing.TreeShakingSharedPlugin(options);
```


Stability: Experimental

`TreeShakingSharedPlugin` creates independent builds and optimizes exports for Module Federation shared dependencies. `ModuleFederationPlugin` applies it automatically when at least one `shared` dependency enables `treeShaking`.

#### Options

- `mfConfig`: The `ModuleFederationPluginOptions` used to configure the shared dependencies and output.
- `secondary`: Whether to perform a second tree-shaking pass during the independent build. The default is `false`.
- `onBuildAssets`: A callback invoked with the generated shared fallback assets.

Direct application is mainly intended for deployment integrations that perform a secondary build. It must be combined with a sharing plugin so `TreeShakingSharedPlugin` can collect the shared modules to build:

```js title="src/index.js"
import { add } from 'lodash-es';

console.log(add(1, 2));
```

```js title="rspack.config.mjs"
import { sharing } from '@rspack/core';

const shared = {
  'lodash-es': { treeShaking: { mode: 'server-calc' } },
};

export default {
  entry: './src/index.js',
  plugins: [
    new sharing.SharePlugin({
      enhanced: true,
      shared,
    }),
    new sharing.TreeShakingSharedPlugin({
      secondary: true,
      mfConfig: {
        name: 'app',
        shared,
        library: { type: 'var', name: 'App' },
      },
    }),
  ],
};
```

The plugin creates an independent build only for shared dependencies that enable `treeShaking` and retain a local implementation. Direct use does not generate Module Federation stats or manifest files. When `ModuleFederationPlugin` applies it internally with manifest generation enabled, the plugin writes the generated fallback asset information into those files.

## experiments

### RemoveDuplicateModulesPlugin

```js
new rspack.experiments.RemoveDuplicateModulesPlugin();
```


Stability: Experimental

`RemoveDuplicateModulesPlugin` finds modules that occur in the same set of multiple chunks and moves them into one reusable or newly created shared chunk. Rspack uses it internally for `modern-module` library output.

In this example, both entries import the same `src/shared.js` module. Disabling `splitChunks` makes `RemoveDuplicateModulesPlugin` responsible for extracting that duplicated module:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  entry: {
    admin: './src/admin.js',
    store: './src/store.js',
  },
  optimization: {
    splitChunks: false,
  },
  plugins: [new rspack.experiments.RemoveDuplicateModulesPlugin()],
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/plugins/internal-plugins/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /plugins/community-plugin-compatibility.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Community plugin compatibility

This page lists the compatibility status of common community plugins in Rspack.

For webpack built-in plugins and selected internal plugins, see [webpack plugin compatibility](/plugins/webpack-built-in-plugin-support.md).

The table only covers common community plugins. For others, you can verify their functionality yourself, and you're welcome to add them to this page.


| Plugin | Support status | Notes |
| --- | --- | --- |
| [circular-dependency-plugin](https://github.com/aackerman/circular-dependency-plugin) | 🔵 Included | Use [CircularCheckRspackPlugin](/plugins/circular-check-rspack-plugin) instead |
| [copy-webpack-plugin](https://www.npmjs.com/package/copy-webpack-plugin) | 🔵 Included | Use [CopyRspackPlugin](/plugins/copy-rspack-plugin) instead |
| [mini-css-extract-plugin](https://webpack.js.org/plugins/mini-css-extract-plugin) | 🔵 Included | Use [CssExtractRspackPlugin](/plugins/css-extract-rspack-plugin) instead |
| [pnp-webpack-plugin](https://github.com/arcanis/pnp-webpack-plugin) | 🔵 Included | Use [resolve.pnp](/config/resolve#resolvepnp) instead |
| [tsconfig-paths-webpack-plugin](https://www.npmjs.com/package/tsconfig-paths-webpack-plugin) | 🔵 Included | Use [resolve.tsConfig](/config/resolve#resolvetsconfig) instead |
| [@loadable/webpack-plugin](https://www.npmjs.com/package/@loadable/webpack-plugin) | 🟢 Compatible |  |
| [@sentry/webpack-plugin](https://www.npmjs.com/package/@sentry/webpack-plugin) | 🟢 Compatible | Support for this plugin >= v1.20.1 |
| [@soda/friendly-errors-webpack-plugin](https://github.com/sodatea/friendly-errors-webpack-plugin) | 🟢 Compatible |  |
| [@vanilla-extract/webpack-plugin](https://github.com/vanilla-extract-css/vanilla-extract) | 🟢 Compatible |  |
| [assets-webpack-plugin](https://github.com/ztoben/assets-webpack-plugin) | 🟢 Compatible |  |
| [case-sensitive-paths-webpack-plugin](https://github.com/Urthen/case-sensitive-paths-webpack-plugin) | 🟢 Compatible | `useBeforeEmitHook` option not supported |
| [clean-webpack-plugin](https://github.com/johnagan/clean-webpack-plugin) | 🟢 Compatible |  |
| [compression-webpack-plugin](https://github.com/webpack/compression-webpack-plugin) | 🟢 Compatible |  |
| [css-minimizer-webpack-plugin](https://github.com/webpack/css-minimizer-webpack-plugin) | 🟢 Compatible | Rspack provides [LightningCssMinimizerRspackPlugin](/plugins/lightning-css-minimizer-rspack-plugin) to deliver better performance |
| [dotenv-webpack](https://www.npmjs.com/package/dotenv-webpack) | 🟢 Compatible |  |
| [error-overlay-webpack-plugin](https://github.com/gregberge/error-overlay-webpack-plugin) | 🟢 Compatible |  |
| [eslint-import-resolver-webpack](https://www.npmjs.com/package/eslint-import-resolver-webpack) | 🟢 Compatible |  |
| [filemanager-webpack-plugin](https://github.com/gregnb/filemanager-webpack-plugin) | 🟢 Compatible |  |
| [friendly-errors-webpack-plugin](https://www.npmjs.com/package/friendly-errors-webpack-plugin) | 🟢 Compatible |  |
| [html-minimizer-webpack-plugin](https://github.com/webpack/html-minimizer-webpack-plugin) | 🟢 Compatible |  |
| [html-webpack-plugin](https://www.npmjs.com/package/html-webpack-plugin) | 🟢 Compatible |  |
| [image-minimizer-webpack-plugin](https://www.npmjs.com/package/image-minimizer-webpack-plugin) | 🟢 Compatible |  |
| [json-minimizer-webpack-plugin](https://github.com/webpack/json-minimizer-webpack-plugin) | 🟢 Compatible |  |
| [license-webpack-plugin](https://www.npmjs.com/package/license-webpack-plugin) | 🟢 Compatible |  |
| [moment-locales-webpack-plugin](https://www.npmjs.com/package/moment-locales-webpack-plugin) | 🟢 Compatible |  |
| [monaco-editor-webpack-plugin](https://www.npmjs.com/package/monaco-editor-webpack-plugin) | 🟢 Compatible |  |
| [node-polyfill-webpack-plugin](https://www.npmjs.com/package/node-polyfill-webpack-plugin) | 🟢 Compatible |  |
| [serwist](https://github.com/serwist/serwist) | 🟢 Compatible |  |
| [stylelint-webpack-plugin](https://github.com/webpack/stylelint-webpack-plugin) | 🟢 Compatible |  |
| [terser-webpack-plugin](https://webpack.js.org/plugins/terser-webpack-plugin) | 🟢 Compatible | Rspack provides [SwcJsMinimizerRspackPlugin](/plugins/swc-js-minimizer-rspack-plugin) to deliver better performance |
| [webpack-bundle-analyzer](https://www.npmjs.com/package/webpack-bundle-analyzer) | 🟢 Compatible |  |
| [webpack-stats-plugin](https://www.npmjs.com/package/webpack-stats-plugin) | 🟢 Compatible |  |
| [webpackbar](https://www.npmjs.com/package/webpackbar) | 🟢 Compatible |  |
| [@nx/webpack](https://www.npmjs.com/package/@nx/webpack) | 🟢 Alternative | Use [@nx/rspack](https://www.npmjs.com/package/@nx/rspack) instead |
| [@pmmmwh/react-refresh-webpack-plugin](https://www.npmjs.com/package/@pmmmwh/react-refresh-webpack-plugin) | 🟢 Alternative | Use [@rspack/plugin-react-refresh](/guide/integrations/react#fast-refresh) instead |
| [eslint-webpack-plugin](https://github.com/webpack-contrib/eslint-webpack-plugin) | 🟢 Alternative | Use [eslint-rspack-plugin](https://github.com/rstackjs/eslint-rspack-plugin) instead |
| [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) | 🟢 Alternative | Use [ts-checker-rspack-plugin](https://github.com/rstackjs/ts-checker-rspack-plugin) instead |
| [html-webpack-tags-plugin](https://github.com/jharris4/html-webpack-tags-plugin) | 🟢 Alternative | Use [html-rspack-tags-plugin](https://github.com/rstackjs/html-rspack-tags-plugin) instead |
| [progress-bar-webpack-plugin](https://www.npmjs.com/package/progress-bar-webpack-plugin) | 🟢 Alternative | Use [webpackbar](https://www.npmjs.com/package/webpackbar) instead |
| [speed-measure-webpack-plugin](https://www.npmjs.com/package/speed-measure-webpack-plugin) | 🟢 Alternative | Use [Rsdoctor](/guide/diagnostics/use-rsdoctor) instead |
| [webpack-filter-warnings-plugin](https://github.com/mattlewis92/webpack-filter-warnings-plugin) | 🟢 Alternative | Use [ignoreWarnings](/config/other-options#ignorewarnings) instead |
| [webpack-manifest-plugin](https://github.com/shellscape/webpack-manifest-plugin) | 🟢 Alternative | Use [rspack-manifest-plugin](https://github.com/rstackjs/rspack-manifest-plugin) instead |
| [webpack-subresource-integrity](https://github.com/waysact/webpack-subresource-integrity) | 🟢 Alternative | Use [SubresourceIntegrityPlugin](/plugins/subresource-integrity-plugin) instead |
| [webpack-virtual-modules](https://github.com/sysgears/webpack-virtual-modules) | 🟢 Alternative | Use [VirtualModulesPlugin](/plugins/virtual-modules-plugin) instead |
| [workbox-webpack-plugin](https://www.npmjs.com/package/workbox-webpack-plugin) | 🟢 Alternative | Use [@aaroon/workbox-rspack-plugin](https://github.com/Clarkkkk/workbox-rspack-plugin) instead |
| [add-asset-html-webpack-plugin](https://github.com/SimenB/add-asset-html-webpack-plugin) | 🟡 Partially compatible | This plugin depends on html-webpack-plugin |
| [html-webpack-harddisk-plugin](https://github.com/jantimon/html-webpack-harddisk-plugin) | 🟡 Partially compatible | This plugin depends on html-webpack-plugin |
| [webpack-assets-manifest](https://github.com/webdeveric/webpack-assets-manifest) | 🟡 Partially compatible | Only supports basic usage |
| [@cypress/webpack-preprocessor](https://github.com/cypress-io/cypress) | 🔴 Incompatible | To be implemented |
| [@intlify/unplugin-vue-i18n](https://github.com/intlify/bundle-tools) | 🔴 Incompatible | To be implemented |
| [@ngtools/webpack](https://www.npmjs.com/package/@ngtools/webpack) | 🔴 Incompatible | To be implemented |
| [@storybook/react-docgen-typescript-plugin](https://github.com/hipstersmoothie/react-docgen-typescript-plugin) | 🔴 Incompatible | To be implemented |
| [critters-webpack-plugin](https://github.com/GoogleChromeLabs/critters) | 🔴 Incompatible | To be implemented |
| [git-revision-webpack-plugin](https://www.npmjs.com/package/git-revision-webpack-plugin) | 🔴 Incompatible | To be implemented |
| [last-call-webpack-plugin](https://github.com/NMFR/last-call-webpack-plugin) | 🔴 Incompatible | To be implemented |
| [webpack-remove-empty-scripts](https://github.com/webdiscus/webpack-remove-empty-scripts) | 🔴 Incompatible | To be implemented |


You can view examples of common plugins at [rstack-examples](https://github.com/rstackjs/rstack-examples).

Additionally, you can check out the community Rspack plugins at [awesome-rstack](https://github.com/rstackjs/awesome-rstack).



---
url: /plugins/webpack-built-in-plugin-support.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# webpack plugin compatibility

The table below shows Rspack compatibility with webpack [built-in plugin APIs](https://webpack.js.org/plugins/) and selected [internal plugins](https://webpack.js.org/plugins/internal-plugins/). Linked plugin names open the corresponding Rspack reference documentation.

Contributions for plugins or features that have not yet been implemented are welcome.


| Plugin | Support status | Notes |
| --- | --- | --- |
| APIPlugin | 🟢 Supported |  |
| [BannerPlugin](/plugins/banner-plugin) | 🟢 Supported |  |
| CommonJsPlugin | 🟢 Supported |  |
| ConstPlugin | 🟢 Supported |  |
| [ConsumeSharedPlugin](/plugins/low-level-plugins#consumesharedplugin) | 🟢 Supported |  |
| [ContainerPlugin](/plugins/low-level-plugins#containerplugin) | 🟢 Supported |  |
| [ContainerReferencePlugin](/plugins/low-level-plugins#containerreferenceplugin) | 🟢 Supported |  |
| [ContextReplacementPlugin](/plugins/context-replacement-plugin) | 🟢 Supported |  |
| [DeterministicModuleIdsPlugin](/plugins/deterministic-module-ids-plugin) | 🟢 Supported |  |
| [DllPlugin](/plugins/dll-plugin) | 🟢 Supported |  |
| [DllReferencePlugin](/plugins/dll-reference-plugin) | 🟢 Supported |  |
| [DynamicEntryPlugin](/plugins/low-level-plugins#dynamicentryplugin) | 🟢 Supported |  |
| [ElectronTargetPlugin](/plugins/low-level-plugins#electron-target-plugin) | 🟢 Supported |  |
| [EnableChunkLoadingPlugin](/plugins/low-level-plugins#enable-chunk-loading-plugin) | 🟢 Supported |  |
| [EnableLibraryPlugin](/plugins/low-level-plugins#enable-library-plugin) | 🟢 Supported |  |
| [EnableWasmLoadingPlugin](/plugins/low-level-plugins#enable-wasm-loading-plugin) | 🟢 Supported |  |
| [EntryOptionPlugin](/plugins/low-level-plugins#entryoptionplugin) | 🟢 Supported |  |
| [EntryPlugin](/plugins/entry-plugin) | 🟢 Supported |  |
| [EnvironmentPlugin](/plugins/environment-plugin) | 🟢 Supported |  |
| [EvalDevToolModulePlugin](/plugins/low-level-plugins#evaldevtoolmoduleplugin) | 🟢 Supported |  |
| [EvalSourceMapDevToolPlugin](/plugins/eval-source-map-dev-tool-plugin) | 🟢 Supported |  |
| [ExternalsPlugin](/plugins/externals-plugin) | 🟢 Supported |  |
| [FetchCompileAsyncWasmPlugin](/plugins/low-level-plugins#fetchcompileasyncwasmplugin) | 🟢 Supported |  |
| HashedModuleIdsPlugin | 🟢 Supported |  |
| [HotModuleReplacementPlugin](/plugins/hot-module-replacement-plugin) | 🟢 Supported |  |
| HttpUriPlugin | 🟢 Supported |  |
| [IgnorePlugin](/plugins/ignore-plugin) | 🟢 Supported |  |
| [JsonpTemplatePlugin](/plugins/low-level-plugins#jsonp-template-plugin) | 🟢 Supported |  |
| [LimitChunkCountPlugin](/plugins/limit-chunk-count-plugin) | 🟢 Supported |  |
| [LoaderOptionsPlugin](/plugins/low-level-plugins#loaderoptionsplugin) | 🟢 Supported |  |
| [LoaderTargetPlugin](/plugins/low-level-plugins#loadertargetplugin) | 🟢 Supported |  |
| MergeDuplicateChunksPlugin | 🟢 Supported |  |
| ModuleConcatenationPlugin | 🟢 Supported |  |
| [ModuleFederationPlugin](/plugins/module-federation-plugin) | 🟢 Supported |  |
| NaturalChunkIdsPlugin | 🟢 Supported |  |
| NaturalModuleIdsPlugin | 🟢 Supported |  |
| [NodeEnvironmentPlugin](/plugins/low-level-plugins#nodeenvironmentplugin) | 🟢 Supported |  |
| [NodeTargetPlugin](/plugins/low-level-plugins#node-target-plugin) | 🟢 Supported |  |
| [NodeTemplatePlugin](/plugins/low-level-plugins#node-template-plugin) | 🟢 Supported |  |
| [NoEmitOnErrorsPlugin](/plugins/no-emit-on-errors-plugin) | 🟢 Supported |  |
| [NormalModuleReplacementPlugin](/plugins/normal-module-replacement-plugin) | 🟢 Supported |  |
| OccurrenceChunkIdsPlugin | 🟢 Supported |  |
| [ProvidePlugin](/plugins/provide-plugin) | 🟢 Supported |  |
| [ProvideSharedPlugin](/plugins/low-level-plugins#providesharedplugin) | 🟢 Supported |  |
| RemoveEmptyChunksPlugin | 🟢 Supported |  |
| [RuntimeChunkPlugin](/plugins/runtime-chunk-plugin) | 🟢 Supported |  |
| [SharePlugin](/plugins/low-level-plugins#shareplugin) | 🟢 Supported |  |
| SideEffectsFlagPlugin | 🟢 Supported |  |
| [SourceMapDevToolPlugin](/plugins/source-map-dev-tool-plugin) | 🟢 Supported |  |
| [SplitChunksPlugin](/plugins/split-chunks-plugin) | 🟢 Supported |  |
| SyncModuleIdsPlugin | 🟢 Supported |  |
| [WebWorkerTemplatePlugin](/plugins/low-level-plugins#web-worker-template-plugin) | 🟢 Supported |  |
| AsyncWebAssemblyModulesPlugin | 🟡 Partially supported | Used internally, but not exposed through the JavaScript API |
| ChunkPrefetchPreloadPlugin | 🟡 Partially supported | Used internally, but not exposed through the JavaScript API |
| CssModulesPlugin | 🟡 Partially supported | Used internally, but not exposed through the JavaScript API |
| [DefinePlugin](/plugins/define-plugin) | 🟡 Partially supported | `rspack.DefinePlugin.runtimeValue` is not supported |
| DeterministicChunkIdsPlugin | 🟡 Partially supported | `context` and `maxLength` options are not supported |
| [JavascriptModulesPlugin](/plugins/javascript-modules-plugin) | 🟡 Partially supported | Static `getCompilationHooks()` does not expose all hooks |
| NamedChunkIdsPlugin | 🟡 Partially supported | `delimiter` and `context` options are not supported |
| NamedModuleIdsPlugin | 🟡 Partially supported | `context` is not supported |
| [ProgressPlugin](/plugins/progress-plugin) | 🟡 Partially supported | Only some options are supported |
| ReadFileCompileAsyncWasmPlugin | 🟡 Partially supported | Used internally, but not exposed through the JavaScript API |
| RealContentHashPlugin | 🟡 Partially supported | `hashFunction` and `hashDigest` options are not supported |
| SingleEntryPlugin | 🟡 Partially supported | Use `EntryPlugin` instead |
| AbstractLibraryPlugin | 🔴 Not supported | Not implemented |
| AggressiveMergingPlugin | 🔴 Not supported | Not implemented |
| AggressiveSplittingPlugin | 🔴 Not supported | Not implemented |
| AMDPlugin | 🔴 Not supported | Not implemented |
| AutomaticPrefetchPlugin | 🔴 Not supported | Not implemented |
| ChunkModuleIdRangePlugin | 🔴 Not supported | Not implemented |
| CleanPlugin | 🔴 Not supported | Not implemented |
| ContextExclusionPlugin | 🔴 Not supported | Not implemented |
| DelegatedPlugin | 🔴 Not supported | Not implemented |
| DotenvPlugin | 🔴 Not supported | Not implemented |
| FetchCompileWasmPlugin | 🔴 Not supported | Not implemented |
| FlagIncludedChunksPlugin | 🔴 Not supported | Not implemented |
| HtmlModulesPlugin | 🔴 Not supported | Not implemented |
| LibManifestPlugin | 🔴 Not supported | Not implemented |
| LibraryTemplatePlugin | 🔴 Not supported | Not implemented |
| ManifestPlugin | 🔴 Not supported | Not implemented |
| MemoryCachePlugin | 🔴 Not supported | Not implemented |
| MinChunkSizePlugin | 🔴 Not supported | Not implemented |
| NodeSourcePlugin | 🔴 Not supported | Not implemented |
| OccurrenceModuleIdsPlugin | 🔴 Not supported | Not implemented |
| PlatformPlugin | 🔴 Not supported | Not implemented |
| PrefetchPlugin | 🔴 Not supported | Not implemented |
| ProfilingPlugin | 🔴 Not supported | Not implemented |
| ReadFileCompileWasmPlugin | 🔴 Not supported | Not implemented |
| RecordIdsPlugin | 🔴 Not supported | Not implemented |
| RequireContextPlugin | 🔴 Not supported | Not implemented |
| RequireEnsurePlugin | 🔴 Not supported | Not implemented |
| RequireIncludePlugin | 🔴 Not supported | Not implemented |
| RequireJsStuffPlugin | 🔴 Not supported | Not implemented |
| VirtualUrlPlugin | 🔴 Not supported | Not implemented |
| WatchIgnorePlugin | 🔴 Not supported | Not implemented |




---
url: /plugins/circular-dependency-rspack-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# CircularDependencyRspackPlugin


[Added in v1.3.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.3.0)

Stability: Deprecated

Rspack only

:::warning Deprecated
`CircularDependencyRspackPlugin` is deprecated. Use [`CircularCheckRspackPlugin`](/plugins/circular-check-rspack-plugin.md), which has better performance and a more reasonable API design.
:::

Detects circular import dependencies between modules that will exist at runtime. Import cycles are often _not_ indicative of a bug when used by functions called at runtime, but may cause bugs or errors when the imports are used during initialization. This plugin does not distinguish between the two, but can be used to help identify and resolve cycles after a bug has been encountered.

## Comparison

This plugin is an adaptation of the original [`circular-dependency-plugin`](https://github.com/aackerman/circular-dependency-plugin) for Webpack and diverges in both behavior and features.

### Performance

Because `CircularDependencyRspackPlugin` is implemented in Rust, it is able to integrate directly with the module graph and avoid expensive copying and serialization. On top of that, this plugin operates using a single traversal of the module graph for each entrypoint to identify all cycles rather than checking each module individually. Combined, that means `CircularDependencyRspackPlugin` is able to run fast enough to be part of a hot reload development cycle without any noticeable impact on reload times, even for extremely large projects with hundreds of thousands of modules and imports.

### Features

`CircularDependencyRspackPlugin` aims to be compatible with the features of `circular-dependency-plugin`, with modifications to give finer control over cycle detection and behavior.

One notable difference between the two is the use of module _identifiers_ for cycle entries in Rspack rather than relative paths. Identifiers represent the entire unique name for a bundled module, including the set of loaders that processed it, the absolute module path, and any request parameters that were provided when importing. While matching on just the path of the module is still possible, identifiers allow for matching against loaders and rulesets as well.

This plugin also provides a new option, `ignoredConnections` to allow for more granular control over whether a cycle is ignored. The `exclude` option from the original plugin is still implemented to match existing behavior, but causes any cycle containing the module to be ignored entirely. When only specific cycles are meant to be ignored, `ignoredConnections` allows for specifying both a `from` and a `to` pattern to match against, ignoring only cycles where an explicit dependency between two modules is present.

## Examples

- Detect all cycles present in a compilation, ignoring any that include external packages from `node_modules`, and emitting compilation errors for each cycle.

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

export default {
  entry: './src/index.js',
  plugins: [
    new rspack.CircularDependencyRspackPlugin({
      failOnError: true,
      exclude: /node_modules/,
    }),
  ],
};
```

- Ignore a specific connection between two modules, as well as any connection `to` any module matching a given pattern.

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

export default {
  entry: './src/index.js',
  plugins: [
    new rspack.CircularDependencyRspackPlugin({
      ignoredConnections: [
        ['some/module/a.js', 'some/module/b.js'],
        ['', /modules\/.*Store.js/],
      ],
    }),
  ],
};
```

## Options

### failOnError

- **Type:** `boolean`
- **Default:** `false`

When `true`, detected cycles will generate Error level diagnostics rather than Warnings. This will have no noticeable effect in watch mode, but will cause full builds to fail when the errors are emitted.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.CircularDependencyRspackPlugin({
      failOnError: true,
    }),
  ],
};
```

### exclude

- **Type:** `RegExp`
- **Default:** `undefined`

Similar to `exclude` from the original [`circular-dependency-plugin`](https://github.com/aackerman/circular-dependency-plugin), detected cycles containing any module resource path that matches this pattern will be ignored.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.CircularDependencyRspackPlugin({
      // Ignore any cycles involving external packages from `node_modules`
      exclude: /node_modules/,
    }),
  ],
};
```

### ignoredConnections

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

A list of explicit connections that should cause a detected cycle to be ignored. Each entry in the list represents a connection as `[from, to]`, matching any connection where `from` depends on `to`.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.CircularDependencyRspackPlugin({
      ignoredConnections: [
        // Ignore a specific connection between modules
        ['some/module/a', 'some/module/b'],
        // Ignore any connection depending on `b`
        ['', 'some/module/b'],
        // Ignore any connection between "Store-like" modules
        [/.*Store\.js/, /.*Store\.js/],
      ],
    }),
  ],
};
```

Each pattern can be represented as either a plain string or a `RegExp`. Plain strings will be matched as substrings against the module identifier for that part of a connection, and RegExps will match anywhere in the entire identifier. For example:

- The string `'some/module/'` will match any module in the `some/module` directory, like `some/module/a` and `some/module/b`.
- The RegExp `!file-loader!.*\.mdx` will match any `.mdx` module processed by `file-loader`.
- Empty strings effectively match any module, since an empty string is always a substring of any other string.

### onDetected

- **Type:** `(entrypoint: string, modules: string[], compilation: Compilation) => void`
- **Default:** `undefined`

Handler function called for every detected cycle. Providing this handler overrides the default behavior of adding diagnostics to the compilation, meaning the value of `failOnError` will be effectively unused.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.CircularDependencyRspackPlugin({
      onDetected(entrypoint, modules, compilation) {
        console.log(`Found a cycle in ${entrypoint}: ${modules.join(' -> ')}`);
      },
    }),
  ],
};
```

This handler can be used to process detected cycles further before emitting warnings or errors to the compilation, or to handle them in any other way not directly implemented by the plugin.

`entrypoint` is the name of the entry where this cycle was detected. Because of how entrypoints are traversed for cycle detection, it's possible that the same cycle will be detected multiple times, once for each entrypoint.

`modules` is the list of identifiers of module contained in the cycle, where both the first and the last entry of the list will always be the same module, and the only module that is present more than once in the list.

`compilation` is the full Compilation object, allowing the handler to emit errors or inspect any other part of the bundle as needed.

### onIgnored

- **Type:** `(entrypoint: string, modules: string[], compilation: Compilation) => void`
- **Default:** `undefined`

Handler function called for every detected cycle that was intentionally ignored, whether by the `exclude` pattern, any match of an `ignoredConnection`, or any other possible reason.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

const ignoredCycles = [];
export default {
  plugins: [
    new rspack.CircularDependencyRspackPlugin({
      onIgnored(entrypoint, modules, compilation) {
        ignoredCycles.push({ entrypoint, modules });
      },
    }),
  ],
};
```

### onStart

- **Type:** `(compilation: Compilation) => void`
- **Default:** `undefined`

Hook function called immediately before cycle detection begins, useful for setting up temporary state to use in the `onDetected` handler or logging progress.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.CircularDependencyRspackPlugin({
      onStart(compilation) {
        console.log('Starting circular dependency detection');
      },
    }),
  ],
};
```

### onEnd

- **Type:** `(compilation: Compilation) => void`
- **Default:** `undefined`

Hook function called immediately after cycle detection finishes, useful for cleaning up temporary state or logging progress.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.CircularDependencyRspackPlugin({
      onEnd(compilation) {
        console.log('Finished detecting circular dependencies');
      },
    }),
  ],
};
```



---
url: /api/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Introduction

Rspack provides a variety of APIs and command line interface (CLI) to customize the build process.

There are some features overlap between APIs and CLI, e.g. some configuration options may be available via CLI flags, while some others are only available through specific APIs.

The following concepts will help you get started.

## CLI

The Command Line Interface (CLI) to configure and interact with your build process. For the most part, the CLI is used to kick off the process using a [configuration file](/config/index.md) and a few flags (e.g. `--env`).

[Learn more about the CLI →](/api/cli.md)

## Runtime API

When processing modules with rspack, it is important to understand the different module syntaxes – specifically the methods and variables - that are supported. And also the runtime HMR improves the development experience by updating modules in the browser at runtime without needing a whole page refresh.

[Learn more about the Runtime API →](/api/runtime-api/module-methods.md)

## JavaScript API

While most users can get away with using the CLI along with a configuration file, more fine-grained control of the compilation can be achieved via the Node interface. This includes passing multiple configurations, programmatically running or watching, and collecting stats.

[Learn more about the JavaScript API →](/api/javascript-api/index.md)

## Loader API

Loaders are transformations that are applied to the source code of a module. They are written as functions that accept source code as a parameter and return a new version of that code with transformations applied.

[Learn more about the loaders →](/api/loader-api/index.md)

## Plugin API

The plugin interface allows users to tap directly into the compilation process. Plugins can register handlers on lifecycle hooks that run at different points throughout a compilation. When each hook is executed, the plugin will have full access to the current state of the compilation.

[Learn more about the plugins →](/api/plugin-api/index.md)



---
url: /api/cli.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Command line interface

[@rspack/cli](https://npmjs.com/package/@rspack/cli) is the command line tool for Rspack, providing a variety of commands to make working with Rspack easier.

- If you do not have `@rspack/cli` installed, please read the [Quick start](/guide/start/quick-start.md) section first.
- If you are using Rsbuild, please refer to the [Rsbuild CLI](https://rsbuild.rs/guide/basic/cli) section.

:::warning Compatible with webpack-cli
`@rspack/cli` is not compatible with `webpack-cli`, so there will be some differences between the two.
:::

## All commands

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

```bash
npx rspack -h
```

## Common flags

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

| Flag                   | Description                                                                                                                                   |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `-c, --config [value]` | Specify the path to the configuration file, see [Specify the configuration file](/config/index.md#specify-the-configuration-file)             |
| `--configLoader`       | Specify the loader to load the config file, can be `auto`, `jiti` or `native`, defaults to `auto`                                             |
| `--configName`         | Specify the name of the configuration to use.                                                                                                 |
| `--env <env>`          | Pass environment values to a configuration function. For example, `--env production --env foo=bar`                                            |
| `--nodeEnv`            | Set the value of `process.env.NODE_ENV`, defaults to `development` for `rspack dev`, and `production` for `rspack build` and `rspack preview` |
| `-h, --help`           | Show help information                                                                                                                         |
| `-v, --version`        | Show version number                                                                                                                           |

:::tip
All flags in Rspack CLI support the `camelCase` and `kebab-case`, for example, both `--configLoader` and `--config-loader` are valid.
:::

## rspack build

`rspack build` is used to run Rspack build, which will generate the output files in the [output.path](/config/output.md#outputpath) directory.

```bash
npx rspack build  # Read the `rspack.config.*` configuration file by default
```

`rspack build` can be abbreviated as `rspack b`:

```bash
npx rspack b
```

Use the `-c` or `--config` flag to specify the configuration file path:

```bash
npx rspack build -c ./your.config.js
```

The complete flags are as follows:

```
rspack build

Options:
      --entry          entry file                                        [array]
  -o, --outputPath     output path dir                                  [string]
  -m, --mode           mode                                             [string]
  -w, --watch          watch                          [boolean] [default: false]
      --env            env passed to config function                     [array]
  -d, --devtool        set source map style for debugging                [string]
      --json [path]    emit stats json, optionally to the specified path
```

## rspack dev

`rspack dev` is used to run Rspack dev server, which will start a local dev server that will listen for file changes and automatically refresh the browser.

:::info Required dependency
The `rspack dev` command requires [@rspack/dev-server](https://www.npmjs.com/package/@rspack/dev-server) to be installed. If you haven't installed it yet, run:


```sh [npm]
npm add @rspack/dev-server -D
```

```sh [yarn]
yarn add @rspack/dev-server -D
```

```sh [pnpm]
pnpm add @rspack/dev-server -D
```

```sh [bun]
bun add @rspack/dev-server -D
```

```sh [deno]
deno add npm:@rspack/dev-server -D
```

:::

```bash
npx rspack dev
```

Use the `-c` or `--config` flag to specify the configuration file path:

```bash
npx rspack dev -c ./your.config.js
```

`rspack dev` can be abbreviated as `rspack serve` or `rspack s`:

```bash
npx rspack s
npx rspack serve
```

Use `--open` or `--no-open` to override [`devServer.open`](/config/dev-server.md#devserveropen) from the CLI without editing your config file:

```bash
npx rspack dev --open
npx rspack dev --open /my-page
npx rspack dev --no-open
```

The complete flags are as follows:

```
rspack dev

Options:
      --entry          entry file                                        [array]
  -o, --outputPath     output path dir                                  [string]
  -m, --mode           mode                                             [string]
  -w, --watch          watch                          [boolean] [default: false]
      --env            env passed to config function                     [array]
  -d, --devtool        set source map style for debugging                [string]
      --hot            enables hot module replacement
      --port           allows to specify a port to use                  [number]
      --host           allows to specify a hostname to use              [string]
      --open [value]   open browser on server start; pass --no-open to disable, or --open <url> to open a specific URL
```

## rspack preview

`rspack preview` is used to preview the production build output locally, note that you need to build the output first by running the `rspack build` command.

:::info Required dependency
The `rspack preview` command requires [@rspack/dev-server](https://www.npmjs.com/package/@rspack/dev-server) to be installed. If you haven't installed it yet, run:


```sh [npm]
npm add @rspack/dev-server -D
```

```sh [yarn]
yarn add @rspack/dev-server -D
```

```sh [pnpm]
pnpm add @rspack/dev-server -D
```

```sh [bun]
bun add @rspack/dev-server -D
```

```sh [deno]
deno add npm:@rspack/dev-server -D
```

:::

```bash
npx rspack preview
```

The complete flags are as follows:

```
rspack preview [dir]

run the rspack server for build output

Positionals:
  dir  directory want to preview                                        [string]

Options:
      --publicPath  static resource server path                         [string]
      --port        preview server port                                 [number]
      --host        preview server host                                 [string]
      --open        open browser                                       [boolean]
      --server      Configuration items for the server.                 [string]
```



---
url: /api/runtime-api/module-methods.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Module methods

This section covers all methods available in code compiled with Rspack. When using Rspack to bundle your application, you can pick from a variety of module syntax styles including [ES modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules) and [CommonJS](https://nodejs.org/api/modules.html).

While Rspack supports multiple module syntaxes, we recommend following a single syntax for consistency and to avoid odd behaviors or bugs.

Actually Rspack would enforce the recommendation for `.mjs` files, `.cjs` files or `.js` files when their nearest parent `package.json` file contains a ["type"](https://nodejs.org/api/packages.html#type) field with a value of either `"module"` or `"commonjs"`. Please pay attention to these enforcements before you read on:

- `.mjs` or `.js` with `"type": "module"` in package.json
  - No CommonJS allowed, for example, you can't use `require`, `module.exports` or `exports`
  - File extensions are required when importing, e.g, you should use import './src/App.mjs' instead of import './src/App' (you can disable this enforcement with [rules\[\].resolve.fullySpecified](/config/module-rules.md#rulesresolve))
- `.cjs` or `.js` with "type": "commonjs" in package.json
  - Neither import nor export is available

## ES modules (recommended)

Rspack support ES modules syntax natively, you can use static `import`, `export` and `import()` syntax.

:::warning
Keep in mind that you will still probably need SWC or Babel for other ES6+ features.
:::

### import

Statically `import` the `export` of another module.

```js
import MyModule from './my-module.js';
import { NamedExport } from './other-module.js';
```

You can also `import` Data URI, this allow you to embed Base64 encoded JavaScript code directly in the import statement:

```js
// Equivalent to import a module that contains `console.log('hello')`
import 'data:text/javascript;charset=utf-8;base64,Y29uc29sZS5sb2coJ2hlbGxvJyk=';

// Equivalent to import a module that contains `export const number = 42;`
import { number } from 'data:text/javascript;charset=utf-8;base64,ZXhwb3J0IGNvbnN0IG51bWJlciA9IDQyOw==';
```

### export

Export anything as a `default` or named export.

```js
// Named exports
export var Count = 5;
export function Multiply(a, b) {
  return a * b;
}

// Default export
export default {
  // Some data...
};
```

### Dynamic import()

```ts
function import(path: string): Promise;
```

Dynamically load modules, see [Dynamic import](/guide/optimization/code-splitting.md#dynamic-import) for more details.

Calls to `import()` are treated as split points, meaning the requested module and its children are split out into a separate chunk.

```js
if (module.hot) {
  import('lodash').then((_) => {
    // Do something with lodash (a.k.a '_')...
  });
}
```

:::warning
This feature relies on `Promise` internally. If you use `import()` with legacy browsers, remember to shim `Promise` using a polyfill such as [core-js](https://github.com/zloirock/core-js), [es6-promise](https://github.com/stefanpenner/es6-promise) or [promise-polyfill](https://github.com/taylorhakes/promise-polyfill).
:::

### Dynamic expressions in import()

It is not possible to use a fully dynamic import statement, such as `import(foo)`. Because `foo` could potentially be any path to any file in your system or project.

The `import()` must contain at least some information about where the module is located. Bundling can be limited to a specific directory or set of files so that when you are using a dynamic expression, every module that could potentially be requested on an `import()` call is included.

For example, `import(`./locale/$\{language}.json`)` will cause every `.json` file in the `./locale` directory to be bundled into the new chunk. At run time, when the variable `language` has been computed, any file like `english.json` or `german.json` will be available for consumption.

```js
// imagine we had a method to get language from cookies or other storage
const language = detectVisitorLanguage();
import(`./locale/${language}.json`).then((module) => {
  // do something with the translations
});
```

### Magic comments in import() \{#magic-comments}


Rspack/Webpack specific

Inline comments can specify chunk names, loading modes, and other import behavior.

:::tip
Since Rspack 2.1.0, prefer the `rspack`-prefixed magic comments below. The equivalent `webpack`-prefixed comments remain supported for compatibility, for example `webpackIgnore` is equivalent to `rspackIgnore`.

The examples below consistently use the `rspack` prefix. Replace it with the corresponding `webpack` prefix when webpack compatibility is required.
:::

```js
// Single target
import(
  /* rspackChunkName: "my-chunk-name" */
  /* rspackMode: "lazy" */
  /* rspackExports: ["default", "named"] */
  /* rspackFetchPriority: "high" */
  'module'
);

// Multiple possible targets
import(
  /* rspackInclude: /\.json$/ */
  /* rspackExclude: /\.noimport\.json$/ */
  /* rspackChunkName: "my-chunk-name" */
  /* rspackMode: "lazy" */
  /* rspackPrefetch: true */
  /* rspackPreload: true */
  `./locale/${language}`
);
```

#### rspackIgnore \{#rspackignore}

- **Type:** `boolean`
- **webpack equivalent:** `webpackIgnore`

When set to `true`, Rspack will skip analysis and bundling processing for the dynamic import. This results in:

1. The module's dependencies will not be analyzed during build time
2. The module will not be bundled into a separate chunk file
3. The import operation will be executed by the browser's native `import()` at runtime

This is particularly useful for dynamically loading ESM third-party libraries from external CDNs, for example:

```js
import('https://esm.sh/react' /* rspackIgnore: true */).then((React) => {
  console.log(React.version); // 19.0.0
});
```

`rspackIgnore` also applies to the `new URL()` syntax. By default, Rspack will parse module identifiers in `new URL()` and bundle the referenced module into the build output. When you need Rspack to skip processing a particular `new URL()`, you can add the `rspackIgnore: true` comment:

```js
// Rspack will process this URL and bundle './index.css' into the build output
const url1 = new URL('./index.css', import.meta.url);

// Rspack will ignore this URL and preserve the original module identifier
const url2 = new URL(/* rspackIgnore: true */ './index.css', import.meta.url);

// `webpackIgnore` is also supported
const url3 = new URL(/* webpackIgnore: true */ './index.css', import.meta.url);
```

#### rspackMode \{#rspackmode}

- **Type:** `"eager" | "lazy" | "weak" | "lazy-once"`
- **webpack equivalent:** `webpackMode`
- **Default:** `'lazy'`

Different modes for resolving dynamic imports can be specified. The following options are supported:

- `'lazy'` (default): Generates a lazy-loadable chunk for each `import()`ed module.
- `'lazy-once'`: Generates a single lazy-loadable chunk that can satisfy all calls to `import()`. The chunk will be fetched on the first call to `import()`, and subsequent calls to `import()` will use the same network response. Note that this only makes sense in the case of a partially dynamic statement, e.g. `import("./locales/${language}.json")`, where multiple module paths that can potentially be requested.
- `'eager'`: Generates no extra chunk. All modules are included in the current chunk and no additional network requests are made. A Promise is still returned but is already resolved. In contrast to a static import, the module isn't executed until the call to `import()` is made.
- `'weak'`: Tries to load the module if the module function has already been loaded in some other way (e.g. another chunk imported it or a script containing the module was loaded). A Promise is still returned, but only successfully resolves if the chunks are already on the client. If the module is not available, the Promise is rejected. A network request will never be performed. This is useful for universal rendering when required chunks are always manually served in initial requests (embedded within the page), but not in cases where app navigation will trigger an import not initially served.

For example, use `lazy-once` to put all possible locale modules into a single async chunk:

```js
const language = detectVisitorLanguage();
const messages = await import(
  /* rspackMode: "lazy-once" */
  `./locales/${language}.js`
);
```

#### rspackPrefetch \{#rspackprefetch}

- **Type:**
  - `number`: chunk prefetch priority
  - `boolean`: `false` means not to prefetch, `true` means priority is `0`
- **webpack equivalent:** `webpackPrefetch`

Tells the browser that the resource is probably needed for some navigation in the future, see [Prefetching/Preloading modules](/guide/optimization/code-splitting.md#prefetchingpreloading-modules) for more details.

For example, the browser prefetches the editor chunk during idle time after the parent chunk loads:

```js
export function openEditor() {
  return import(
    /* rspackPrefetch: true */
    './editor.js'
  );
}
```

You can also use a number to set the prefetch priority:

```js
import(/* rspackPrefetch: 10 */ './editor.js');
```

#### rspackPreload \{#rspackpreload}

- **Type:**
  - `number`: chunk preload priority
  - `boolean`: `false` means not to preload, `true` means priority is `0`
- **webpack equivalent:** `webpackPreload`

Tells the browser that the resource might be needed during the current navigation. See [Prefetching/Preloading modules](/guide/optimization/code-splitting.md#prefetchingpreloading-modules) for more details.

For example, preload a charting library in parallel with its parent chunk:

```js
export async function renderDashboard() {
  const { renderChart } = await import(
    /* rspackPreload: true */
    './chart.js'
  );

  renderChart();
}
```

#### rspackChunkName \{#rspackchunkname}

- **Type:** `string`
- **webpack equivalent:** `webpackChunkName`

A name for the new chunk.

```js
const settings = await import(
  /* rspackChunkName: "settings" */
  './settings.js'
);
```

The final filename is still determined by [`output.chunkFilename`](/config/output.md#outputchunkfilename).

#### rspackFetchPriority \{#rspackfetchpriority}

- **Type:** `"low" | "high" | "auto"`
- **webpack equivalent:** `webpackFetchPriority`

Set [`fetchPriority`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority) for specific dynamic imports. It's also possible to set a global default value for all dynamic imports by using the `module.parser.javascript.dynamicImportFetchPriority` option.

For example, give a critical above-the-fold module a high fetch priority:

```js
const hero = await import(
  /* rspackFetchPriority: "high" */
  './hero.js'
);
```

#### rspackInclude \{#rspackinclude}

- **Type:** `RegExp`
- **webpack equivalent:** `webpackInclude`

A regular expression that will be matched against during import resolution. Only modules that match **will be bundled**.

For example, include only `.json` files from the `./locales` directory in the dynamic import context:

```js
const messages = await import(
  /* rspackInclude: /\.json$/ */
  `./locales/${language}`
);
```

#### rspackExclude \{#rspackexclude}

- **Type:** `RegExp`
- **webpack equivalent:** `webpackExclude`

A regular expression that will be matched against during import resolution. Any module that matches **will not be bundled**.

For example, exclude test files from the `./locales` directory:

```js
const messages = await import(
  /* rspackExclude: /\.test\.js$/ */
  `./locales/${language}.js`
);
```

:::info
`rspackInclude` and `rspackExclude` only filter candidate modules discovered under the static path prefix, such as `./locales`; they do not change that prefix. The equivalent `webpackInclude` and `webpackExclude` comments are also supported for compatibility.
:::

#### rspackExports \{#rspackexports}

- **Type:** `string | string[]`
- **webpack equivalent:** `webpackExports`

Tells Rspack to only bundle the specified exports of a dynamically `import()`ed module. It can decrease the output size of a chunk.

For example, explicitly declare the required exports when the imported namespace is passed to another function and Rspack cannot statically determine which exports it uses:

```js
const widget = await import(
  /* rspackExports: ["render", "version"] */
  './widget.js'
);

consumeWidget(widget);
```

When code directly accesses properties from the imported module or uses destructuring, Rspack can usually infer the used exports automatically, so `rspackExports` is unnecessary.

## CommonJS

Rspack is also support `CommonJS` syntax natively, you can use `require` and `module.exports` methods.

### require

Synchronously retrieve the exports from another module.

```js
require(dependency: string);
```

### require.resolve

Synchronously retrieves the module ID without executing the module code. This method will include the module in the final bundle. The returned module ID is primarily intended for use with `require.cache[id]` or the Rspack internal `__webpack_require__(id)` function. Direct use of this method should be avoided in most application scenarios.

```js
require.resolve(dependency: string);
```

:::warning
Module ID's type can be a number or a string depending on the `optimization.moduleIds` configuration.
:::

### require.cache

Multiple requires of the same module result in only one module execution and only one export. Therefore a cache in the runtime exists. Removing values from this cache causes new module execution and a new export.

```js
var d1 = require('dependency');
require('dependency') === d1;
delete require.cache[require.resolve('dependency')];
require('dependency') !== d1;
```

### require.context


Rspack/Webpack specific

`require.context` is a function specific to webpack that allows you to dynamically require a set of modules.

You can use `require.context` in your code, and Rspack will parse and reference the matching modules during the build process.

:::tip
The return value of `require.context` is the same as [import.meta.webpackContext](/api/runtime-api/module-variables.md#importmetawebpackcontext).
:::

- **Type:**

```ts
function requireContext(
  /**
   * A directory to search.
   */
  directory: string,
  /**
   * Whether subdirectories should be searched.
   * @default true
   */
  includeSubdirs?: boolean,
  /**
   * A regular expression to match files.
   * @default /^\.\/.*$/ (any file)
   */
  filter?: RegExp,
  /**
   * Module loading mode.
   * @default 'sync'
   */
  mode?: 'sync' | 'eager' | 'weak' | 'lazy' | 'lazy-once',
): Context;
```

- **Example:**

```js
// Create a context, with files from the test directory that
// can be required with a module specifier ending with `.test.js`.
const context = require.context('./test', false, /\.test\.js$/);
```

```js
// Create a context with all files in the parent folder and
// descending folders ending with `.stories.js`.
const context = require.context('../', true, /\.stories\.js$/);
```

```js
// If mode is set to 'lazy', the underlying modules will be loaded asynchronously
const context = require.context('./locales', true, /\.json$/, 'lazy');
```

:::tip
Rspack uses static analysis to parse the parameters of `require.context` during compilation. Therefore, the parameters must be [literals](https://developer.mozilla.org/en-US/docs/Glossary/Literal).

For example, the value of `filter` cannot be a variable, nor can it be the value generated by `new RegExp()`. It can only be a regular expression literal.
:::

### require.ensure


Rspack/Webpack specific

:::tip
We recommend using the more standard `import()` instead of `require.ensure()`.
:::

Split the given `dependencies` into a separate bundle and load them asynchronously.

- **Type:**

```ts
function requireEnsure(
  /**
   * List of modules that need to be loaded asynchronously
   */
  dependencies: String[],
  /**
   * Called once all modules in dependencies have been loaded.
   * You can still use require() inside this function to load modules.
   */
  callback: function(),
  /**
   * A function that is executed when Rspack fails to load the dependencies.
   */
  errorCallback?: function(error),
  /**
   * A name given to the chunk created by this particular require.ensure().
   * By passing the same chunkName to various require.ensure() calls,
   * we can combine their code into a single chunk, resulting in only one bundle that the browser must load.
   */
  chunkName?: string
): Context;
```

:::warning

- This feature relies on [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) internally. If you use `require.ensure` in older browsers, remember to shim `Promise` using a polyfill such as [es6-promise](https://github.com/stefanpenner/es6-promise) or [promise-polyfill](https://github.com/taylorhakes/promise-polyfill).
- As in webpack, the callback can also accept a parameter named `require` (and it must be named `require`). This parameter behaves the same as the CommonJS global `require`, but we recommend using the global `require` directly instead, because loaders may rename the callback parameter and break dependency analysis.

:::

- **Example:**

```ts
var a = require('normal-dep');

if (module.hot) {
  require.ensure(['b'], function () {
    var c = require('c');

    // Do something special...
  });
}
```

### require.resolveWeak


Rspack/Webpack specific

Similar to `require.resolve`, but this method won't pull the module into the final bundle. It's what is considered a "weak" dependency.

```js
require.resolveWeak(dependency: string);
```

For example:

```js
if (__webpack_modules__[require.resolveWeak('module')]) {
  // Do something when module is available...
}
if (require.cache[require.resolveWeak('module')]) {
  // Do something when module was loaded before...
}

// You can perform dynamic resolves ("context")
// similarly to other require/import methods.
const page = 'Foo';
__webpack_modules__[require.resolveWeak(`./page/${page}`)];
```

## Data URI module

Rspack supports importing Data URI modules using the `import` and `require` syntax.

- **import**

```js
import DataURI from 'data:text/javascript,export default 42';
```

- **require**

```js
require('data:text/javascript,module.exports = 42');
```

In addition, Base64 encoded requests are also supported:

```js
const {
  number,
  fn,
} = require('data:text/javascript;charset=utf-8;base64,ZXhwb3J0IGNvbnN0IG51bWJlciA9IDQyOwpleHBvcnQgZnVuY3Rpb24gZm4oKSB7CiAgcmV0dXJuICJIZWxsbyB3b3JsZCI7Cn0=');
```

::: tip
The Data URI module can be used as a method to implement virtual modules, such as combining with a Loader to dynamically load custom modules at runtime.
:::

### Built-in rules

Rspack supports these [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types) for data URI modules by default: `application/json`, `text/javascript`, `application/javascript`, `application/node`, and `application/wasm`. This means that when you create data URI modules with these MIME types, Rspack will automatically recognize them.

Rspack's built-in MIME rules are as follows:

```js
const defaultMimeRules = [
  {
    mimetype: 'application/node',
    type: 'javascript/auto',
  },
  {
    mimetype: 'application/json',
    type: 'json',
  },
  {
    mimetype: {
      or: ['text/javascript', 'application/javascript'],
    },
    type: 'javascript/esm',
    // ...
  },
  {
    mimetype: 'application/wasm',
    type: 'webassembly/async',
    // ...
  },
];
```

### Custom rules

You can also use [rules\[\].mimetype](/config/module-rules.md#rulesmimetype) to extend the matching rules for Data URI modules, for example, to add custom loaders for `text/javascript`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        mimetype: 'text/javascript',
        use: [
          // ...
        ],
      },
    ],
  },
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/api/module-methods/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /api/runtime-api/module-variables.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Module variables

This section covers all variables available in code compiled with Rspack. Modules will be able to access specific data from the compilation process through `module` and other variables.

## CommonJS

### module.loaded

`false` means that the module is being executed, `true` the synchronous execution has been completed.

### module.id

Current module ID.

```js title=src/main.js
module.id === require.resolve('./src/main.js'); // true
```

### module.hot

Indicates whether or not hot module replacement is enabled and provides an interface to the process. See the [HMR API page](/api/runtime-api/hmr.md) for details.

### global

See [node.js global](https://nodejs.org/api/globals.html#globals_global) for details.

Rspack will replace the global with a proxy object and handle compatibility issues in it.


```js title=Source
global['property']
```
```js title=Compiled
__webpack_require__.g['property'];

// webpack/runtime/global
__webpack_require__.g = (function () {
  // compatibility code
})();
```

### \_\_filename

Depends on the configuration [`node.__filename`](/config/node.md#node__filename).

- `false`: undefined
- `mock`: equal to `'/index.js'`
- `true`: [NodeJs \_\_filename](https://nodejs.org/api/modules.html#__filename)

If used inside an expression that is parsed by the Parser, the configuration option is treated as `true`.


```js title=Source
__filename
```
```js title=Compiled
'src/main.js';
```

### \_\_dirname

Depends on the configuration [`node.__dirname`](/config/node.md#node__dirname).

- `false`: undefined
- `mock`: equal to `'/'`
- `true`: [NodeJs \_\_dirname](https://nodejs.org/api/modules.html#__dirname)

If used inside an expression that is parsed by the Parser, the configuration option is treated as `true`.


```js title=Source
__dirname
```
```js title=Compiled
'src';
```

## import.meta (ESM) \{#import-meta}

The `import.meta` exposes context-specific metadata to a JavaScript module, such as the URL of the module. It is only available in modules that support ESM ([module type](/misc/glossary.md#module-type) is `javascript/auto` or `javascript/esm`).

Normally, unknown `import.meta` metadata is replaced with `undefined` by default. When using [ESM output](/guide/features/esm.md), [`module.parser.javascript.importMeta`](/config/module-parser.md#javascriptimportmeta) defaults to `'preserve-unknown'`, so unknown metadata is preserved for runtime evaluation. You can also use the object form of `module.parser.javascript.importMeta` to control known `import.meta` properties individually.

Rspack statically analyzes `import.meta` properties and replaces them with concrete values at compile time, so dynamic access to `import.meta` (e.g., `Object.keys(import.meta)`) is not supported and will emit a warning. You should access metadata on `import.meta` via property access or destructuring assignment.


```js title=Source
// Will emit a warning
Object.keys(import.meta);
// typeof access is allowed
typeof import.meta;
// Property access is allowed
import.meta.url;
// Destructuring assignment is allowed
let { url } = import.meta;
```
```js title=Compiled
// Warning
Object.keys({});

('object');

('file:///project/index.js');

let { url } = { url: 'file:///project/index.js' };
```

### import.meta.url

Returns the absolute `file:` URL string of the current module.


```js title=Source
import.meta.url;
typeof import.meta.url;
```
```js title=Compiled
'file:///project/index.js';
'string';
```

### import.meta.main

Returns a boolean indicating whether the current module is the entry module.


```js title=Source
if (import.meta.main) {
  main();
}
```
```js title=Compiled
if (
  __webpack_module_cache__[/* entry module id */ __webpack_require__.s] ===
  module
) {
  main();
}
```

### import.meta.filename

Returns the full file path of the current module. This is the ESM equivalent of [`__filename`](#__filename), commonly used to get the current file's path information in ESM modules.

The compilation behavior is controlled by the [`node.__filename`](/config/node.md#node__filename) configuration option. See that configuration documentation for details.

### import.meta.dirname

Returns the directory path of the current module. This is the ESM equivalent of [`__dirname`](#__dirname), commonly used to construct paths based on the current file's location in ESM modules.

The compilation behavior is controlled by the [`node.__dirname`](/config/node.md#node__dirname) configuration option. See that configuration documentation for details.

### import.meta.resolve


[Added in v2.0.0](https://github.com/web-infra-dev/rspack/releases/tag/v2.0.0)

Stability: Experimental

The ESM equivalent of [`require.resolve()`](/api/runtime-api/module-methods.md#requireresolve), used to get the ID of another module. It includes the module in the final bundle and returns its module ID.


```js title=Source
let img = new Image();
img.src = import.meta.resolve('./img.png');
```
```js title=Compiled
let img = new Image();
img.src = './src/img.png'; // module ID of img.png
```

:::warning
`import.meta.resolve()` is currently experimental. To use it, you must enable [`module.parser.javascript.importMetaResolve`](/config/module-parser.md#javascriptimportmetaresolve). Rspack also plans to [align this API with the standard behavior](https://github.com/openjs-foundation/bundler-collab-space/issues/8) in the future, so its behavior may change. Use it with caution.
:::

### import.meta.glob


[Added in v2.0.5](https://github.com/web-infra-dev/rspack/releases/tag/v2.0.5)Rspack only

`import.meta.glob` allows you to import multiple modules at once using glob patterns. Rspack will parse and reference the matching modules during the build process.

- **Type:**

```ts
interface ImportMetaGlobOptions<Eager extends boolean = boolean> {
  /**
   * If `true`, modules are loaded synchronously.
   *
   * @default false
   */
  eager?: Eager;
  /**
   * Import only the specific named export. Set to `default` to import the default export.
   */
  import?: string;
  /**
   * Append a query to each matched module request.
   */
  query?: string | Record<string, string | number | boolean>;
  /**
   * Search files inside `node_modules` and hidden paths.
   *
   * @default false
   */
  exhaustive?: boolean;
  /**
   * Base path for resolving relative glob patterns and returned keys.
   */
  base?: string;
  /**
   * Match file paths case-sensitively.
   *
   * @default true
   */
  caseSensitive?: boolean;
}

function glob(
  /**
   * A glob pattern, or an array of glob patterns, to match files.
   */
  pattern: string | readonly string[],
  options?: ImportMetaGlobOptions<false>,
): Record<string, () => Promise<any>>;

function glob(
  /**
   * A glob pattern, or an array of glob patterns, to match files.
   */
  pattern: string | readonly string[],
  options: ImportMetaGlobOptions<true>,
): Record<string, any>;
```

- **Parameters:**
  - `pattern`: A glob pattern string, or an array of glob pattern strings, to match files (e.g., `'./dir/*.js'`). Supports `*`, `?`, `[abc]`, `{a,b}`, and `**` for recursive matching. Array patterns can also include negative patterns such as `'!**/bar.js'`.
  - `options.eager`: When set to `true`, modules are included directly in the bundle and loaded synchronously. By default (`false`), modules are lazily loaded and each value is a thunk function that returns a `Promise` resolving to the module.
  - `options.import`: Import only the specified export from each matched module. For example, use `'default'` to get default exports, or a named export such as `'setup'`.
  - `options.query`: Append a query to each matched module request. It can be a query string such as `'?raw'`, or an object that is serialized as a URL query string. The keys returned from `import.meta.glob()` do not include the query.
  - `options.exhaustive`: Search files inside `node_modules` and hidden paths. This is disabled by default because it can increase build time.
  - `options.base`: Base path for resolving relative glob patterns and returned keys. Absolute glob patterns are still resolved from the project root, while returned keys are made relative to `base`.
  - `options.caseSensitive`: Whether to match file paths case-sensitively. When set to `false`, matching ignores case, while returned object keys preserve the filesystem's original casing. Defaults to `true`.

- **Example:**

```js
// Lazy (default): each value is a function () => Promise<module>
const modules = import.meta.glob('./dir/*.js');

// All matched modules are available as async thunks
const foo = await modules['./dir/foo.js']();
console.log(foo.default);

// Eager: each value is the module object directly
const eagerModules = import.meta.glob('./dir/*.js', { eager: true });
console.log(eagerModules['./dir/foo.js'].default);

// Import only the default export from each matched module
const defaultModules = import.meta.glob('./dir/*.js', { import: 'default' });
const fooDefault = await defaultModules['./dir/foo.js']();
console.log(fooDefault);

// Combine eager loading with import selection
const eagerDefaultModules = import.meta.glob('./dir/*.js', {
  eager: true,
  import: 'default',
});
console.log(eagerDefaultModules['./dir/foo.js']);

// Append a query to each matched import
const rawModules = import.meta.glob('./dir/*.js', {
  query: '?raw',
  import: 'default',
});
const rawFoo = await rawModules['./dir/foo.js']();

// Query objects are serialized as URL query strings
const dataModules = import.meta.glob('./dir/*.js', {
  query: { type: 'data', inline: true },
  eager: true,
});

// Resolve files from ./base and expose keys relative to ./base
const modulesWithBase = import.meta.glob('./**/*.js', {
  base: './base',
});

// Include matches inside node_modules and hidden paths
const exhaustiveModules = import.meta.glob(
  ['./node_modules/**/*.js', './.config/*.js'],
  {
    exhaustive: true,
  },
);

// Recursive matching with **
const allModules = import.meta.glob('./components/**/*.js', { eager: true });
```

:::tip
Rspack uses static analysis to parse the parameters of `import.meta.glob()` during compilation. Therefore, the `pattern` parameter must be a string literal or an array of string literals, and the `options` parameter must be an object literal. Variables or dynamically constructed values are not supported.
:::

:::warning
`import.meta.glob()` matches files on the filesystem at build time and includes them in the bundle. Avoid using overly broad glob patterns, as they can significantly increase build time and output size.
:::

### import.meta.webpackContext


Rspack/Webpack specific

`import.meta.webpackContext` is the ESM equivalent of [`require.context()`](/api/runtime-api/module-methods.md#requirecontext). It allows you to dynamically import a set of modules and is provided for compatibility with webpack context modules.

For new Rspack code, we recommend using [`import.meta.glob`](#importmetaglob) instead when webpack-compatible context behavior is not required.

You can use `import.meta.webpackContext` in your code, and Rspack will parse and reference the matching modules during the build process.

- **Type:**

```ts
function webpackContext(
  /**
   * A directory to search.
   */
  request: string,
  options?: {
    /**
     * Whether subdirectories should be searched.
     * @default true
     */
    recursive?: boolean;
    /**
     * A regular expression to match files.
     * @default /^\.\/.*$/ (any file)
     */
    regExp?: RegExp;
    /**
     * Module loading mode.
     * @default 'sync'
     */
    mode?: 'sync' | 'eager' | 'weak' | 'lazy' | 'lazy-once';
    include?: RegExp;
    exclude?: RegExp;
    preload?: boolean | number;
    prefetch?: boolean | number;
    chunkName?: string;
    exports?: string | string[][];
  },
): Context;
```

- **Example:**

```js
// Create a context, with files from the test directory that
// can be required with a module specifier ending with `.test.js`.
const context = import.meta.webpackContext('./test', {
  recursive: false,
  regExp: /\.test\.js$/,
});
```

```js
// Create a context with all files in the parent folder and
// descending folders ending with `.stories.js`.
const context = import.meta.webpackContext('../', {
  recursive: true,
  regExp: /\.stories\.js$/,
});
```

```js
// If mode is set to 'lazy', the underlying modules will be loaded asynchronously
const context = import.meta.webpackContext('./locales', {
  recursive: true,
  regExp: /\.json$/,
  mode: 'lazy',
});
```

:::tip
Rspack uses static analysis to parse the parameters of `import.meta.webpackContext()` during compilation. Therefore, the parameters must be [literals](https://developer.mozilla.org/en-US/docs/Glossary/Literal).

For example, the value of `regExp` cannot be a variable, nor can it be the value generated by `new RegExp()`. It can only be a regular expression literal.
:::

#### context API

The context returned by `import.meta.webpackContext()` is a function that takes a `request` argument (module path).

This function has three properties: `resolve`, `keys`, and `id`.

- `resolve` is a function and returns the module id of the parsed module specifier.
- `keys` is a function that returns an array of all possible requests that the context module can handle.
- `id` is the module id of the context module. This may be useful for `module.hot.accept`.

This can be useful if you want to require all files in a directory or matching a pattern.

Consider a scenario where you have a folder structure like this:

```
src
├── components
│   ├── Button.js
│   ├── Header.js
│   └── Footer.js
```

You can use `import.meta.webpackContext()` to dynamically import all component files in the folder:

```js
const componentsContext = import.meta.webpackContext('./components', {
  recursive: false,
  regExp: /\.js$/,
});

componentsContext.keys().forEach((fileName) => {
  const componentModule = componentsContext(fileName);

  // Here you can use your module, for example console.log
  console.log(componentModule);
});
```

`import.meta.webpackContext()` streamlines the process of module importation especially when you have a lot of files to manage. When using it, please avoid matching unnecessary files, as this might lead to significantly increased build time and output size.

### import.meta.webpackHot


Rspack/Webpack specific

The ESM equivalent of [`module.hot`](#modulehot). `import.meta.webpackHot` can be used in strict ESM modules (module type `javascript/esm`), while `module.hot` cannot.

### import.meta.rspackHash


[Added in v2.1.2](https://github.com/web-infra-dev/rspack/releases/tag/v2.1.2)Rspack only

It provides access to the hash of the compilation.


```js title=Source
import.meta.rspackHash;
```
```js title=Compiled
__webpack_require__.h();

// webpack/runtime/get_full_hash
__webpack_require__.h = function () {
  return '9210c6f859a51c6f9a62';
};
```

### import.meta.rspackPublicPath


[Added in v2.1.2](https://github.com/web-infra-dev/rspack/releases/tag/v2.1.2)Rspack only

Equals the configuration option's [`output.publicPath`](/config/output.md#outputpublicpath).


```js title=Source
import.meta.rspackPublicPath;
```
```js title=Compiled
__webpack_require__.p;

// output.publicPath !== "auto"
__webpack_require__.p = 'output.publicPath';
// output.publicPath === "auto"
__webpack_require__.p = 'calculated from document/location';
```

> See [Dynamically set publicPath](/guide/features/asset-base-path.md#dynamically-set-publicpath) for more information about the usage of `import.meta.rspackPublicPath`.

### import.meta.rspackBaseUri


[Added in v2.1.2](https://github.com/web-infra-dev/rspack/releases/tag/v2.1.2)Rspack only

Get or change base URI at runtime.


```js title=Source
import.meta.rspackBaseUri;
```
```js title=Compiled
__webpack_require__.b;

// chunk loading
__webpack_require__.b = document.baseURI || self.location.href;
```

### import.meta.rspackNonce


[Added in v2.1.2](https://github.com/web-infra-dev/rspack/releases/tag/v2.1.2)Rspack only

Rspack is capable of adding a nonce to all scripts that it loads. To activate this feature, set `import.meta.rspackNonce` in your entry script.


```js title=Source
import.meta.rspackNonce = 'your_nonce_code';
```
```js title=Compiled
__webpack_require__.nc = '2312312';

// webpack/runtime/load_script
if (__webpack_require__.nc) {
  script.setAttribute('nonce', __webpack_require__.nc);
}
```

### import.meta.rspackShareScopes


[Added in v2.1.2](https://github.com/web-infra-dev/rspack/releases/tag/v2.1.2)Rspack only

This object is used as a shared scope in the remote container and is filled with the provided modules from a host.


```js title=Source
import.meta.rspackShareScopes;
```
```js title=Compiled
__webpack_require__.S;
```

### import.meta.rspackInitSharing


[Added in v2.1.2](https://github.com/web-infra-dev/rspack/releases/tag/v2.1.2)Rspack only

This method is used to initialize modules of a shared scope in the host container.


```js title=Source
import.meta.rspackInitSharing('default');
```
```js title=Compiled
__webpack_require__.I('default');
```

### import.meta.rspackVersion


[Added in v2.1.2](https://github.com/web-infra-dev/rspack/releases/tag/v2.1.2)Rspack only

Current Rspack version, default to version in `@rspack/core/package.json`, can be modified through `output.bundlerInfo.version`.


```js title=Source
import.meta.rspackVersion;
```
```js title=Compiled
__webpack_require__.rv();

// webpack/runtime/rspack_version
__webpack_require__.rv = () => '0.7.4';
```

### import.meta.rspackUniqueId


[Added in v2.1.2](https://github.com/web-infra-dev/rspack/releases/tag/v2.1.2)Rspack only

The ID of the current bundler, the value is `bundler={bundler}@{version}`:

- `bundler`: Default to `"rspack"` and can be modified through [output.bundlerInfo.bundler](/config/output.md#outputbundlerinfo).
- `version`: Default to version in `@rspack/core/package.json` and can be modified through [output.bundlerInfo.version](/config/output.md#outputbundlerinfo).


```js title=Source
import.meta.rspackUniqueId;
```
```js title=Compiled
__webpack_require__.ruid;

// webpack/runtime/rspack_unique_id
__webpack_require__.ruid = 'bundler=rspack@2.1.2';
```

## Runtime

### \_\_webpack\_hash\_\_


Stability: Deprecated

Rspack/Webpack specific

The CommonJS equivalent of [`import.meta.rspackHash`](#importmetarspackhash).

### \_\_webpack\_runtime\_id\_\_


Rspack/Webpack specific

Access the runtime id of current entry.


```js title=Source
__webpack_runtime_id__
```
```js title=Compiled
__webpack_require__.j;

// webpack/runtime/runtime_id
__webpack_require__.j = '909';
```

### \_\_webpack\_public\_path\_\_


Stability: Deprecated

Rspack/Webpack specific

The CommonJS equivalent of [`import.meta.rspackPublicPath`](#importmetarspackpublicpath).

### \_\_webpack\_base\_uri\_\_


Stability: Deprecated

Rspack/Webpack specific

The CommonJS equivalent of [`import.meta.rspackBaseUri`](#importmetarspackbaseuri).

### \_\_webpack\_nonce\_\_


Stability: Deprecated

Rspack/Webpack specific

The CommonJS equivalent of [`import.meta.rspackNonce`](#importmetarspacknonce).

## Modules

### \_\_webpack\_modules\_\_


Rspack/Webpack specific

Access to the internal object of all modules.


```js title=Source
__webpack_modules__
```
```js title=Compiled
var __webpack_modules__ = {
  'main.js': function () {
    __webpack_require__.m;
  },
};
__webpack_require__.m = __webpack_modules__;
```

### \_\_webpack\_module\_\_


Rspack/Webpack specific

It provides access to the current `module`. `module` is not available in strict ESM.


```js title=Source
__webpack_module__
```
```js title=Compiled
"main.js": function(renamed_module) {
  renamed_module
}
```

### \_\_webpack\_module\_\_.id


Rspack/Webpack specific

It provides access to the ID of current module (`module.id`). `module` is not available in strict ESM.


```js title=Source
__webpack_module__.id
```
```js title=Compiled
"main.js": function(renamed_module) {
  renamed_module.id
}
```

### \_\_webpack\_layer\_\_


Rspack/Webpack specific

Access the [layer](/guide/advanced/layer.md) of the current module. Its value is the configured layer name, or `null` when the module has no layer.

Rspack replaces `__webpack_layer__` at compile time, allowing optimizers to remove unreachable layer-specific branches.


```js title=Source
const currentLayer = __webpack_layer__;
```
```js title=Compiled
const currentLayer = 'client';
```

### \_\_webpack\_require\_\_


Rspack/Webpack specific

The raw require function.
This expression isn't parsed by the Parser for dependencies.


```js title=Source
__webpack_require__('./dep.js')
```
```js title=Compiled
"main.js": function(_, __, renamed_require) {
  renamed_require('./dep.js')
}
```

### \_\_non\_webpack\_require\_\_


Rspack/Webpack specific

Generates a `require` function that is not parsed by webpack.
Can be used to do cool stuff with a global require function if available.


```js title=Source
__non_webpack_require__('outer.js')
```
```js title=Compiled
"main.js": function(_, __, __webpack_require__) {
  require('outer.js')
}
```

### \_\_webpack\_is\_included\_\_


Rspack/Webpack specific

Test whether or not the given module is bundled by webpack.


```js title=Source
if (__webpack_is_included__('./dep.js')) {
  // do something
}
```
```js title=Compiled
if (true) {
  // do something
}
```

### \_\_resourceQuery


Rspack/Webpack specific

The resource query of the current module.
If the following `require` call was made, then the query string would be available in `file.js`.

```js
require('file.js?test');
```


```js title=Source
__resourceQuery
```
```js title=Compiled
'?test';
```

### \_\_webpack\_exports\_info\_\_


Rspack/Webpack specific

In modules, `__webpack_exports_info__` is available to allow exports introspection:

- `__webpack_exports_info__` is always `true`
- `__webpack_exports_info__.<exportName>.used` is `false` when the export is known to be unused, `true` otherwise
- `__webpack_exports_info__.<exportName>.useInfo` is
  - `false` when the export is known to be unused
  - `true` when the export is known to be used
  - `null` when the export usage could depend on runtime conditions
  - `undefined` when no info is available
- `__webpack_exports_info__.<exportName>.provideInfo` is
  - `false` when the export is known to be not provided
  - `true` when the export is known to be provided
  - `null` when the export provision could depend on runtime conditions
  - `undefined` when no info is available
- Accessing the info from nested exports is possible: i. e. `__webpack_exports_info__.<exportName>.<exportProperty1>.<exportProperty2>.used`
- Check whether exports can be mangled with `__webpack_exports_info__.<exportName>.canMangle`


```js title=Source
if (__webpack_exports_info__.someUsedExport.used) { }
if (__webpack_exports_info__.someUnusedExport.used) { }
```
```js title=Compiled
if (true) {
}
if (false) {
}
```

## Chunks

### \_\_webpack\_chunkname\_\_


Rspack/Webpack specific

Get current chunk name.


```js title=Source
__webpack_chunkname__
```
```js title=Compiled
__webpack_require__.cn;

// webpack/runtime/chunk_name
__webpack_require__.cn = 'main';
```

### \_\_webpack\_chunk\_load\_\_


Rspack/Webpack specific

The internal chunk loading function. Takes one argument:

- `chunkId`: the id for the chunk to load.


```js title=Source
__webpack_chunk_load__
```
```js title=Compiled
__webpack_require__.e;

// webpack/runtime/ensure_chunk
__webpack_require__.e = function (chunkId) {
  // return chunk loading promise
};
```

Example to load chunks from alternate public path when one failed:

```js
const originalLoad = __webpack_chunk_load__;
const publicPaths = ['a', 'b', 'c'];
__webpack_chunk_load__ = async (id) => {
  let error;
  for (const path of publicPaths) {
    import.meta.rspackPublicPath = path;
    try {
      return await originalLoad(id);
    } catch (e) {
      error = e;
    }
  }
  throw error;
};
import('./module-a').then((moduleA) => {
  // now webpack will use the custom __webpack_chunk_load__ to load chunk
});
```

### \_\_webpack\_get\_script\_filename\_\_


Rspack/Webpack specific

It provides filename of the chunk by its id.


```js title=Source
__webpack_get_script_filename__
```
```js title=Compiled
__webpack_require__.u;

// webpack/runtime/get_chunk_filename
__webpack_require__.u = function (chunkId) {
  // ...
};
```

It is assignable, which allows changing the filename used by the runtime. For example, it can be used to determine the final path when loading chunks.

```js
const oldFn = __webpack_get_script_filename__;

__webpack_get_script_filename__ = (chunkId) => {
  const filename = oldFn(chunkId);
  return filename + '.changed';
};
```

## Module Federation

### \_\_webpack\_share\_scopes\_\_


Stability: Deprecated

Rspack/Webpack specific

The CommonJS equivalent of [`import.meta.rspackShareScopes`](#importmetarspacksharescopes).

### \_\_webpack\_init\_sharing\_\_


Stability: Deprecated

Rspack/Webpack specific

The CommonJS equivalent of [`import.meta.rspackInitSharing`](#importmetarspackinitsharing).

## System.js

### \_\_system\_context\_\_


Rspack/Webpack specific

Context from System.js when `output.library.type="system"`

## Rspack

### \_\_rspack\_version\_\_


Stability: Deprecated

Rspack only

The CommonJS equivalent of [`import.meta.rspackVersion`](#importmetarspackversion).

### \_\_rspack\_unique\_id\_\_


Stability: Deprecated

Rspack only

The CommonJS equivalent of [`import.meta.rspackUniqueId`](#importmetarspackuniqueid).


This page is adapted from [webpack documentation](https://webpack.js.org/api/module-variables/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /api/runtime-api/hmr.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Hot module replacement

Rspack provides the same interface as webpack for implementing HMR.

If you've enabled Hot Module Replacement via the [HotModuleReplacementPlugin](/plugins/hot-module-replacement-plugin.md), its interface is exposed on the `module.hot` and `import.meta.webpackHot` objects.

In ESM, use `import.meta.webpackHot` instead of `module.hot`.

## Example

First, check if the interface is available, then use it. Here's how to `accept` an updated module:

```js
if (module.hot) {
  module.hot.accept('./library.js', function () {
    // Do something with the updated library module...
  });
}

// or
if (import.meta.webpackHot) {
  import.meta.webpackHot.accept('./library.js', function () {
    // Do something with the updated library module…
  });
}
```

The following methods are supported by `module.hot` and `import.meta.webpackHot`.

## Module API

### accept

Accepts updates for the given `dependencies` and fires a `callback` to handle those updates. You can also attach an optional error handler:

```js
module.hot.accept(
  dependencies, // Either a string or an array of strings
  callback, // Function to fire when the dependencies are updated
  errorHandler, // (err, {moduleId, dependencyId}) => {}
);

// or
import.meta.webpackHot.accept(
  dependencies, // Either a string or an array of strings
  callback, // Function to fire when the dependencies are updated
  errorHandler, // (err, {moduleId, dependencyId}) => {}
);
```

When using ESM `import`, all imported symbols from `dependencies` are automatically updated. Note: The dependency string must exactly match the `from` string in the `import`. In some cases, `callback` can be omitted. Using `require()` in the `callback` isn't useful here.

When using CommonJS, update dependencies manually using `require()` in the `callback`. Omitting the `callback` isn't useful here.

#### errorHandler for accept

`(err, {moduleId, dependencyId}) => {}`

- `err`: The error thrown by the callback in the second argument or during dependency execution when using ESM dependencies.
- `moduleId`: The current module ID.
- `dependencyId`: The module ID of the (first) changed dependency.

### accept (self)

Accepts updates for itself.

```js
module.hot.accept(
  errorHandler, // Function to handle errors when evaluating the new version
);

// or
import.meta.webpackHot.accept(
  errorHandler, // Function to handle errors when evaluating the new version
);
```

When this module or its dependencies are updated, it can be disposed and re-evaluated without notifying parents. This makes sense if the module has no exports (or exports are updated in another way).

The `errorHandler` fires when evaluating this module (or its dependencies) throws an exception.

#### errorHandler for self accept

`(err, {moduleId, module}) => {}`

- `err`: The error when evaluating the new version.
- `moduleId`: The current module ID.
- `module`: The current module instance.
  - `module.hot`: Allows using the HMR API of the errored module instance. A common scenario is to self-accept it again. It also makes sense to add a dispose handler to pass data along. Note that the errored module might already be partially executed, so avoid getting into an inconsistent state. Use `module.hot.data` to store partial state.
  - `module.exports`: Can be overridden, but be careful since property names might be mangled in production mode.

### decline

Rejects updates for the given `dependencies`, forcing the update to fail with a `'decline'` code.

```js
module.hot.decline(
  dependencies, // Either a string or an array of strings
);

// or
import.meta.webpackHot.decline(
  dependencies, // Either a string or an array of strings
);
```

Flags a dependency as not updatable. This makes sense when changes to this dependency's exports can't be handled or handling isn't implemented yet. Depending on your HMR management code, updates to these dependencies (or their unaccepted dependencies) usually cause a full page reload.

### decline (self)

Rejects updates for itself.

```js
module.hot.decline();

// or
import.meta.webpackHot.decline();
```

Flag this module as not-update-able. This makes sense when this module has irreversible side-effects, or HMR handling is not implemented for this module yet. Depending on your HMR management code, an update to this module (or unaccepted dependencies) usually causes a full-reload of the page.

### dispose (or addDisposeHandler)

Add a handler which is executed when the current module code is replaced. This should be used to remove any persistent resource you have claimed or created. If you want to transfer state to the updated module, add it to the given `data` parameter. This object will be available at `module.hot.data` after the update.

```js
module.hot.dispose((data) => {
  // Clean up and pass data to the updated module...
});

// or
import.meta.webpackHot.dispose((data) => {
  // Clean up and pass data to the updated module...
});
```

### invalidate

Calling this method will invalidate the current module, which disposes and recreates it when the HMR update is applied. This bubbles like a normal update of this module. `invalidate` can't be self-accepted by this module.

When called during the `idle` state, a new HMR update will be created containing this module. HMR will enter the `ready` state.

When called during the `ready` or `prepare` state, this module will be added to the current HMR update.

When called during the `check` state, this module will be added to the update when an update is available. If no update is available it will create a new update. HMR will enter the `ready` state.

When called during the `dispose` or `apply` state, HMR will pick it up after getting out of those states.

#### Use cases

**Conditional Accepting**

A module can accept a dependency, but can call `invalidate` when the change of the dependency is not handleable:

```js
import { x, y } from './dep';
import { processX, processY } from 'anotherDep';

const oldY = y;

processX(x);
export default processY(y);

module.hot.accept('./dep', () => {
  if (y !== oldY) {
    // This can't be handled, bubble to parent
    module.hot.invalidate();
    return;
  }
  // This can be handled
  processX(x);
});
```

**Conditional self accept**

A module can self-accept itself, but can invalidate itself when the change is not handleable:

```js
const VALUE = 'constant';

export default VALUE;

if (
  module.hot.data &&
  module.hot.data.value &&
  module.hot.data.value !== VALUE
) {
  module.hot.invalidate();
} else {
  module.hot.dispose((data) => {
    data.value = VALUE;
  });
  module.hot.accept();
}
```

**Triggering custom HMR updates**

```js
const moduleId = chooseAModule();
const code = __webpack_modules__[moduleId].toString();
__webpack_modules__[moduleId] = eval(`(${makeChanges(code)})`);
if (require.cache[moduleId]) {
  require.cache[moduleId].hot.invalidate();
  module.hot.apply();
}
```

T> When `invalidate` is called, the [`dispose`](#dispose-or-adddisposehandler) handler will be eventually called and fill `module.hot.data`. If [`dispose`](#dispose-or-adddisposehandler) handler is not registered, an empty object will be supplied to `module.hot.data`.

W> Do not get caught in an `invalidate` loop, by calling `invalidate` again and again. This will result in stack overflow and HMR entering the `fail` state.

### removeDisposeHandler

Remove the handler added via `dispose` or `addDisposeHandler`.

```js
module.hot.removeDisposeHandler(callback);

// or
import.meta.webpackHot.removeDisposeHandler(callback);
```

## Management API

### status

Retrieve the current status of the hot module replacement process.

```js
module.hot.status(); // Will return one of the following strings...

// or
import.meta.webpackHot.status();
```

| Status  | Description                                                                         |
| ------- | ----------------------------------------------------------------------------------- |
| idle    | The process is waiting for a call to [`check`](#check)                              |
| check   | The process is checking for updates                                                 |
| prepare | The process is getting ready for the update (e.g. downloading the updated module)   |
| ready   | The update is prepared and available                                                |
| dispose | The process is calling the `dispose` handlers on the modules that will be replaced  |
| apply   | The process is calling the `accept` handlers and re-executing self-accepted modules |
| abort   | An update was aborted, but the system is still in its previous state                |
| fail    | An update has thrown an exception and the system's state has been compromised       |

### check

Test all loaded modules for updates and, if updates exist, `apply` them.

```js
module.hot
  .check(autoApply)
  .then((outdatedModules) => {
    // outdated modules...
  })
  .catch((error) => {
    // catch errors
  });

// or
import.meta.webpackHot
  .check(autoApply)
  .then((outdatedModules) => {
    // outdated modules...
  })
  .catch((error) => {
    // catch errors
  });
```

The `autoApply` parameter can either be a boolean or `options` to pass to the `apply` method when called.

### apply

Continue the update process (as long as `module.hot.status() === 'ready'`).

```js
module.hot
  .apply(options)
  .then((outdatedModules) => {
    // outdated modules...
  })
  .catch((error) => {
    // catch errors
  });

// or
import.meta.webpackHot
  .apply(options)
  .then((outdatedModules) => {
    // outdated modules...
  })
  .catch((error) => {
    // catch errors
  });
```

The optional `options` object can include the following properties:

- `ignoreUnaccepted` (boolean): Ignore changes made to unaccepted modules.
- `ignoreDeclined` (boolean): Ignore changes made to declined modules.
- `ignoreErrored` (boolean): Ignore errors thrown in accept handlers, error handlers and while reevaluating module.
- `onDeclined` (function(info)): Notifier for declined modules
- `onUnaccepted` (function(info)): Notifier for unaccepted modules
- `onAccepted` (function(info)): Notifier for accepted modules
- `onDisposed` (function(info)): Notifier for disposed modules
- `onErrored` (function(info)): Notifier for errors

The `info` parameter will be an object containing some of the following values:

```ts
{
  type: 'self-declined' | 'declined' |
        'unaccepted' | 'accepted' |
        'disposed' | 'accept-errored' |
        'self-accept-errored' | 'self-accept-error-handler-errored',
  moduleId: 4, // The module in question.
  dependencyId: 3, // For errors: the module id owning the accept handler.
  chain: [1, 2, 3, 4], // For declined/accepted/unaccepted: the chain from where the update was propagated.
  parentId: 5, // For declined: the module id of the declining parent
  outdatedModules: [1, 2, 3, 4], // For accepted: the modules that are outdated and will be disposed
  outdatedDependencies: { // For accepted: The location of accept handlers that will handle the update
    5: [4]
  },
  error: new Error(...), // For errors: the thrown error
  originalError: new Error(...) // For self-accept-error-handler-errored:
                                // the error thrown by the module before the error handler tried to handle it.
}
```

### addStatusHandler

Register a function to listen for changes in `status`.

```js
module.hot.addStatusHandler((status) => {
  // React to the current status...
});

// or
import.meta.webpackHot.addStatusHandler((status) => {
  // React to the current status...
});
```

Bear in mind that when the status handler returns a `Promise`, the HMR system will wait for the `Promise` to resolve before continuing.

### removeStatusHandler

Remove a registered status handler.

```js
module.hot.removeStatusHandler(callback);

// or
import.meta.webpackHot.removeStatusHandler(callback);
```


This page is adapted from [webpack documentation](https://webpack.js.org/api/hot-module-replacement/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /api/javascript-api/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# JavaScript API

Rspack provides a set of JavaScript APIs to be used in JavaScript runtimes like Node.js, Deno, or Bun.

The JavaScript API is useful in scenarios in which you need to customize the build or development process since all the reporting and error handling must be done manually and webpack only does the compiling part. For this reason the [`stats`](/config/stats.md) configuration options will not have any effect in the `rspack()` call.

:::tip
`@rspack/core` is designed to align with webpack's JavaScript API to ensure functional consistency and a similar user experience.
:::

Rspack's JavaScript API differs from webpack's in its lifecycle and performance characteristics.
See [JavaScript API architecture](/api/javascript-api/architecture.md).

## Installation

To start using the Rspack JavaScript API, first install `@rspack/core` if you haven't yet:


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

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

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

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

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

Then introduce the `@rspack/core` module in your JavaScript file:


**ESM**

```js title="build.mjs"
import { rspack } from '@rspack/core';
```


**CJS**

```js title="build.cjs"
const { rspack } = require('@rspack/core');
```


## rspack()

The imported rspack function is fed a Rspack Configuration Object and runs the Rspack compiler if a callback function is provided:

```js
import { rspack } from '@rspack/core';

rspack({}, (err, stats) => {
  if (err || stats.hasErrors()) {
    // ...
  }
  // Done processing
});
```

```ts
function rspack(
  options: MultiRspackOptions | RspackOptions,
  callback?: Callback<Error, MultiStats | Stats>,
): null | MultiCompiler | Compiler;
```

:::tip
The `err` object will not include compilation errors. Those must be handled separately using `stats.hasErrors()`, which will be covered in detail in the [Error Handling](/api/javascript-api/index.md#error-handling) section of this guide. The `err` object will only contain rspack-related issues, such as misconfiguration, etc.
:::

:::tip
You can provide the `rspack` function with an array of configurations. See the [MultiCompiler](/api/javascript-api/index.md#multicompiler) section below for more information.
:::

## Compiler instance

If you don't pass the `rspack` runner function a callback, it will return a Rspack `Compiler` instance. This instance can be used to manually trigger the Rspack runner or have it build and watch for changes, much like the [CLI](/api/cli.md). The `Compiler` instance provides the following methods:

- `.run(callback)`
- `.watch(watchOptions, handler)`

Typically, only one master `Compiler` instance is created, although child compilers can be created in order to delegate specific tasks. The `Compiler` is ultimately a function which performs bare minimum functionality to keep a lifecycle running. It delegates all the loading, bundling, and writing work to registered plugins.

The `hooks` property on a `Compiler` instance is used to register a plugin to any hook event in the `Compiler`'s lifecycle. The [`RspackOptionsApply`](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack/src/rspackOptionsApply.ts) utilities are used by Rspack to configure its `Compiler` instance with all the built-in plugins.

> See [Compiler API](/api/javascript-api/compiler.md) for more details.


Compiler.ts

## compiler.run

The `run` method is then used to kickstart all compilation work. Upon completion, the given `callback` function is executed. The final logging of stats and errors should be done in this `callback` function.

:::warning
The API only supports a single concurrent compilation at a time. When using `run` or `watch`, call `close` and wait for it to finish before calling `run` or `watch` again. Concurrent compilations will corrupt the output files.
:::

```js
import { rspack } from '@rspack/core';

const compiler = rspack({
  // ...
});

compiler.run((err, stats) => {
  // ...

  compiler.close((closeErr) => {
    // ...
  });
});
```

## compiler.watch

Calling the `watch` method triggers the rspack runner, but then watches for changes (much like CLI: `rspack --watch`), as soon as Rspack detects a change, runs again. Returns an instance of `Watching`.

```js
import { rspack } from '@rspack/core';

const compiler = rspack({
  // ...
});

const watching = compiler.watch(
  {
    // Example
    aggregateTimeout: 300,
    poll: undefined,
  },
  (err, stats) => {
    // Print watch/build result here...
    console.log(stats);
  },
);
```

`Watching` options are covered in detail [here](/config/watch.md#watchoptions).

:::warning
Filesystem inaccuracies may trigger multiple builds for a single change. In the example above, the `console.log` statement may fire multiple times for a single modification. Users should expect this behavior and may check `stats.hash` to see if the file hash has actually changed.
:::

> See [`Compiler.watch`](/api/javascript-api/compiler.md#watch) for more details.


Watching.ts

## Stats object

The `stats` object that is passed as a second argument of the [`rspack()`](/api/javascript-api/index.md#rspack) callback, is a good source of information about the code compilation process. It includes:

- Errors and Warnings (if any)
- Timings
- Module and Chunk information

The [Rspack CLI](/api/cli.md) uses this information to display nicely formatted output in your console.

:::tip
When using the `MultiCompiler`, a `MultiStats` instance is returned that fulfills the same interface as `stats`, i.e. the methods described below.
:::

> See [Stats API](/api/javascript-api/stats.md) for more details.


Stats.ts

## MultiCompiler

The `MultiCompiler` module allows Rspack to run multiple configurations in separate compilers. If the `options` parameter in the Rspack's JavaScript API is an array of options, Rspack applies separate compilers and calls the callback after all compilers have been executed.

```js
import { rspack } from '@rspack/core';

rspack(
  [
    { entry: './index1.js', output: { filename: 'bundle1.js' } },
    { entry: './index2.js', output: { filename: 'bundle2.js' } },
  ],
  (err, stats) => {
    process.stdout.write(stats.toString() + '\n');
  },
);
```

> See [MultiCompiler API](/api/javascript-api/compiler.md#multicompiler) for more details.

## Error handling

For good error handling, you need to account for these three types of errors:

- Fatal rspack errors (wrong configuration, etc)
- Compilation errors (missing modules, syntax errors, etc)
- Compilation warnings

Here's an example that handles all conditions:

```js
import { rspack } from '@rspack/core';

rspack(
  {
    // ...
  },
  (err, stats) => {
    if (err) {
      console.error(err.stack || err);
      if (err.details) {
        console.error(err.details);
      }
      return;
    }

    const info = stats.toJson();

    if (stats.hasErrors()) {
      console.error(info.errors);
    }

    if (stats.hasWarnings()) {
      console.warn(info.warnings);
    }

    // Log result...
  },
);
```

## Custom file systems

:::danger Differences with webpack

1. The current support for `inputFileSystem` in Rspack is limited, and the ability to customize the filesystem read capability consistent with webpack has not yet been implemented. Please refer to: [Issue #5091](https://github.com/web-infra-dev/rspack/issues/5091).

2. With Rspack, when using a specified output file system, there's no longer a requirement to supply `mkdirp` and `join` utility methods.

:::

By default, Rspack reads files and writes files to disk using a normal file system. However, it is possible to change the input or output behavior using a different kind of file system (memory, webDAV, etc). To accomplish this, one can change the `inputFileSystem` or `outputFileSystem`. For example, you can replace the default `outputFileSystem` with [`memfs`](https://github.com/streamich/memfs) to write files to memory instead of to disk:

```js
import { createFsFromVolume, Volume } from 'memfs';
import { rspack } from '@rspack/core';

const fs = createFsFromVolume(new Volume());
const compiler = rspack({/* options */});

compiler.outputFileSystem = fs;
compiler.run((err, stats) => {
  // Read the output later:
  const content = fs.readFileSync('...');
  compiler.close((closeErr) => {
    // ...
  });
});
```

## `sources` object

`@rspack/core` exports the [webpack-sources](https://github.com/webpack/webpack-sources) module through `sources`. It provides a set of classes for creating and manipulating source code fragments and source maps. When developing Rspack plugins, you can use these classes to handle and manipulate source code.

```js
import { sources } from '@rspack/core';

const { RawSource } = sources;
const source = new RawSource('console.log("Hello, world!");');
```

For detailed usage, please refer to the [webpack-sources](https://github.com/webpack/webpack-sources) documentation.


This page is adapted from [webpack documentation](https://webpack.js.org/api/node/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /api/javascript-api/architecture.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# JavaScript API architecture

Rspack exposes a webpack-compatible JavaScript API through `@rspack/core`, while most compilation work runs in Rust. The two layers communicate through a Node-API binding.

## What is a native-backed object?

An ordinary JavaScript object stores its data directly in the JavaScript engine. For example, reading the `name` property of `{ name: 'main' }` does not require a call into Rust.

Rspack's `Compilation`, `Module`, `Chunk`, and graph objects work differently. Most of their compilation data is stored in Rust, while the JavaScript object usually stores only an identifier or internal handle used to locate that data. When a plugin reads certain getters or calls certain methods, Rspack accesses Rust through the Node-API binding and converts the result back into a JavaScript value. These objects are called **native-backed objects**.

```text
Ordinary JavaScript object

  Read property ──────> Data in JavaScript object ──────> Result available directly


Native-backed object

  Read getter          JavaScript object              Node-API binding
  or call method ────> (identifier / internal handle) ────> (cross-runtime access)
                                                              │
                                                              ▼
                                                    Rust Compiler / Compilation
                                                    (compilation data)
                                                              │
                                                              ▼
  Receive JavaScript value <────── Convert data <──────── Node-API binding
```

The two kinds of objects can use exactly the same JavaScript syntax while behaving differently:

| Object type                | Where the data is stored | What happens on property access or method call       | Lifetime                               |
| -------------------------- | ------------------------ | ---------------------------------------------------- | -------------------------------------- |
| Ordinary JavaScript object | JavaScript memory        | Read directly without crossing the binding           | Data normally exists while referenced  |
| Native-backed object       | Primarily in Rust        | May read or modify data through the Node-API binding | Limited by its compiler or compilation |

A native-backed object can contain both kinds of properties:

- immutable data such as strings and numbers may be copied into JavaScript when the object is created, so reading it later does not access Rust;
- getters and methods may access Rust on every call to retrieve current compilation data or perform an operation.

Keeping the JavaScript object alive does not guarantee that it still refers to data from the build that created it. After a rebuild, a getter or method may retrieve data from the latest Rust compilation, or it may throw because its target no longer exists.

This implementation model has two direct consequences:

1. **Lifetime:** A native-backed object reliably refers to the intended Rust data only within the compiler, compilation, or hook execution scope that produced it.
2. **Performance:** Reading a getter or calling a method may convert data between JavaScript and Rust. Repeating the same access in a loop can accumulate significant cost.

If data is needed later, copy strings, numbers, or ordinary JavaScript objects while the corresponding build is still active instead of retaining the native-backed object itself.

## Compiler lifecycle

Creating an `@rspack/core` `Compiler` does not immediately create the corresponding native compiler. Rspack first normalizes options and runs plugin `apply` calls in JavaScript. It creates the Rust compiler on demand when a build API such as `run()` or `watch()` is called for the first time.

After the native compiler has been created, the following information has already been finalized and passed to Rust:

- normalized options and builtin plugins;
- registration functions that connect JavaScript hooks to the native hook adapter;
- file systems and resolver factories used for cross-language calls.

Do not assume that arbitrary changes to `compiler.options` will still be synchronized to Rust after the native compiler has been created. Apply plugins and finish configuration before the first call to `run()` or `watch()`.

:::warning Difference from webpack's object model
A `Compiler` instance has only one active native `Compilation` at a time. Every build, including each watch rebuild, replaces that native compilation.

In development, some webpack plugins continue to use a JavaScript `Compilation` after that build's `done` hook has finished. A watch rebuild may already have started before this later work runs, creating a race in which the plugin holds a `Compilation` from the previous build. To remain compatible with this common pattern, Rspack treats every JavaScript `Compilation` as a view of the compiler's **current** native compilation. Getters and methods on the old object can therefore read or modify the latest build instead of throwing. Keeping that object does not preserve the previous build.

In watch mode, use the `Compilation` and native-backed objects provided to the current build's hooks. If historical data is required, copy it into ordinary JavaScript values during the corresponding build.
:::

When a compiler is no longer needed, call `close()` and wait for its callback. This waits for the current compilation to finish and releases the native resources and JavaScript callbacks owned by the compiler.

## Compilation and object lifetimes

Every build, including each watch rebuild, creates a new `Compilation`. Objects such as `Module`, `Chunk`, and graph objects obtained from a `Compilation` do not copy all of their data into JavaScript. Reading some properties or calling some methods still requires Rspack to retrieve data from the current Rust compilation through Node-API.

Follow these rules:

- Use a `Compilation` and its `Module`, `Chunk`, graph, dependency, and block objects only in hooks and callbacks for the current build.
- Unless the API documentation explicitly promises a longer lifetime, do not retain these objects after the hook finishes or into the next build.
- If information is needed later, save JavaScript-owned strings or numbers such as identifiers, names, paths, and hashes, or convert the data into an ordinary JavaScript object.
- After a watch rebuild, obtain objects again from the new `Compilation` instead of reusing objects saved from the previous build.

## Hook and callback execution

The Rust compiler can use multiple threads to run several independent compilation tasks at the same time. JavaScript hooks, loaders, and other callbacks cannot run directly on those Rust threads. They must be scheduled back into the JavaScript environment in which the Rspack compiler was created.

User code in one JavaScript environment runs on one JavaScript thread. Even if multiple Rust threads trigger callbacks at the same time, those callbacks enter a queue and are executed one by one on the JavaScript thread:

```text
Rust threads run in parallel                 JavaScript runs on one thread

  Compilation task A ─┐
  Compilation task B ─┼─> Cross-thread callback queue ─> Run callbacks one by one
  Compilation task C ─┘                                      │
                                                             └─> Return result
                                                                 └─> Corresponding Rust task continues
```

The cost of hooks and callbacks is therefore not limited to Node-API conversion and thread scheduling. More importantly, they introduce a **serial execution point**: multiple Rust tasks that could otherwise run in parallel may all wait for the JavaScript queue. The more frequently a callback runs and the longer it takes, the more it can reduce the benefits of Rust parallelism. Rust work before and after the callback can still run in parallel, but the part that depends on the JavaScript result is limited by single-threaded throughput.

### Why loaders are especially likely to become a bottleneck

Rspack can process several files at the same time, but JavaScript loaders must run on the JavaScript thread. When several files need loader processing at once, their JavaScript loaders queue up, and the Rust compilation tasks waiting for those results pause at that boundary. The heavier the JavaScript loader and the more often it runs, the closer the overall build gets to serial execution.

When equivalent functionality is available, prefer an Rspack builtin loader. For example:

- use [`builtin:swc-loader`](/guide/features/builtin-swc-loader.md) for JavaScript and TypeScript
  transforms;
- use [`builtin:lightningcss-loader`](/guide/features/builtin-lightningcss-loader.md) for CSS
  transforms.

Builtin loaders run on the Rust side, reducing JavaScript queueing and cross-language data conversion while making better use of Rspack's parallelism.

## Efficient usage

### Read only the assets you need

`compilation.assets` looks like an ordinary JavaScript object, but its asset contents are provided on demand by the native compilation. `Object.keys(assets)` retrieves only asset names. Rspack retrieves the corresponding `Source` from Rust through the binding only when `assets[name]` is read.

If only some assets are needed, the following pattern is inefficient:

```js title="Inefficient"
compilation.hooks.processAssets.tap('ExamplePlugin', (assets) => {
  for (const [name, source] of Object.entries(assets)) {
    if (name.endsWith('.js')) {
      consumeJavaScriptAsset(name, source);
    }
  }
});
```

`Object.entries(assets)` reads the `Source` of every asset before the loop starts. Even if the loop
uses only a few assets, this causes unnecessary cross-language communication and memory usage.

Use `Object.keys()` to filter asset names first, then read only the required sources:

```js title="Recommended"
compilation.hooks.processAssets.tap('ExamplePlugin', (assets) => {
  for (const name of Object.keys(assets)) {
    if (!name.endsWith('.js')) {
      continue;
    }

    const source = assets[name];
    consumeJavaScriptAsset(name, source);
  }
});
```

If every asset is needed, using `Object.entries()` or `Object.values()` does not introduce unused reads.

### Read once in a loop

Read and retain data obtained from Rust during a single pass:

```js
compilation.hooks.processAssets.tap('ExamplePlugin', () => {
  const moduleInfo = [];

  for (const module of compilation.modules) {
    const size = module.size();
    moduleInfo.push({
      identifier: module.identifier(),
      size,
    });
  }

  consumeModuleInfo(moduleInfo);
});
```

`module.size()` retrieves data from Rust through the binding. Keeping `size` in a local variable avoids calling `module.size()` again in later logic.



---
url: /api/javascript-api/compiler.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Compiler

The Compiler is a core object in Rspack. A Compiler instance is created when you call Rspack's [JavaScript API](/api/javascript-api/index.md) or [CLI](/api/cli.md).

It provides methods like [run](#run) and [watch](#watch) to start builds, and exposes [Compiler hooks](/api/plugin-api/compiler-hooks.md) that allow plugins to hook into different stages of the build process.

## Compiler methods

### run

Starts a compilation and calls the callback when compilation completes or fails with an error.

```ts
function run(
  callback: (
    error: Error, // Only includes compiler-related errors, such as configuration errors, not compilation errors
    stats: Stats, // Detailed information generated during compilation
  ) => void,
  options?: {
    modifiedFiles?: ReadonlySet<string>; // Modified files included in this compilation
    removedFiles?: ReadonlySet<string>; // Deleted files included in this compilation
  },
): void;
```

:::warning

If you need to call the `run` method on the same `compiler` object multiple times, note the following:

1. This API doesn't support concurrent compilation. Before starting a new compilation, call `compiler.close()` in the `compiler.run` callback and wait for it to finish before calling `compiler.run` again. Running multiple compilations simultaneously can produce unexpected output files.
2. Rspack's cache invalidation relies on the `modifiedFiles` and `removedFiles` parameters. When caching is enabled and you're using a custom watcher, pass these values to Rspack via the `options` parameter.

:::

```js
compiler.run((err, stats) => {
  // Deal with the compiler errors
  handleCompilerError(err);
  // Deal with the compilation errors
  handleModuleErrors(stats.toJson().errors);
  // Deal with the result
  handleBuildResult(stats);
  // End this compilation
  compiler.close((closeErr) => {
    // Start a new compilation
    compiler.run((err, stats) => {});
  });
});
```


Stats.ts

### watch

Watches files and directories, starting a compilation after they change. Calls the handler after each compilation completes or fails.

```ts
function watch(
  watchOptions: WatchOptions, // Options for starting the watcher
  handler: (error: Error, stats: Stats) => void, // Callback after each compilation
): Watching; // Watching controller
```

:::warning Warning
This API only supports one compilation at a time. Call `compiler.close` in the `compiler.watch` callback and wait for it to finish before calling `compiler.watch` again. Concurrent compilations will corrupt output files.
:::

```js
const watching = compiler.watch(
  {
    aggregateTimeout: 300,
    poll: undefined,
  },
  (err, stats) => {
    // Deal with the result
    handleBuildResult(stats);
  },
);
```

The Watching object provides the following methods:

- `watch`:
  - **Type**: `(files: Iterable<string>, dirs: Iterable<string>, missing: Iterable<string>): void`
  - **Usage**: Adds files and directories to watch.
- `invalidate`:
  - **Type**: `(callback: () => void): void`
  - **Usage**: Immediately ends the current watch cycle and starts a new compilation with the recorded file changes, without stopping the watcher.
- `suspend`:
  - **Type**: `(): void`
  - **Usage**: Enters watch-only mode and doesn't start new compilations.
- `resume`:
  - **Type**: `(): void`
  - **Usage**: Exits watch-only mode and starts a compilation with the recorded file changes.
- `close`:
  - **Type**: `(callback: () => void): void`
  - **Usage**: Stops the watcher.


WatchOptions.ts

Stats.ts

### close

Closes the compiler and handles low-priority tasks like caching.

```ts
function close(
  callback: (err: Error) => void, // Callback after closing
): void;
```

### getInfrastructureLogger

Create a [logger object](/api/javascript-api/logger.md) that is not associated with any compilation, which is used to print global logs.

```ts
function getInfrastructureLogger(name: string): Logger;
```


Logger.ts

### getCache

Creates a cache object to share data during the build process.

```ts
function getCache(name: string): CacheFacade;
```


Cache.ts

### purgeInputFileSystem

Stops the input file system read loop, which contains an internal timer that may prevent the process from exiting after calling `compiler.close`.

```ts
function purgeInputFileSystem(): void;
```

### createChildCompiler

Runs another Rspack instance inside Rspack as a child compiler with different settings. Copies all hooks and plugins from the parent (or top-level) compiler and creates a child `Compiler` instance. Returns the created `Compiler`.

```ts
function createChildCompiler(
  compilation: Compilation,
  compilerName: string,
  compilerIndex: number,
  outputOptions: OutputOptions,
  plugins: RspackPlugin[],
): Compiler;
```


Compilation.ts

OutputOptions.ts

RspackPlugin.ts

### runAsChild

Runs the child compiler, performing a complete compilation and generating assets.

```ts
function runAsChild(
  callback(
    err: Error, // Error related to the child compiler
    entries: Chunk[], // Chunks generated by the child compiler
    compilation: Compilation, // The compilation created by the child compiler
  ): void;
): void;
```


Chunk.ts

Compilation.ts

### isChild

Whether this compiler is a child compiler.

```ts
function isChild(): boolean;
```

## Compiler properties

### hooks

See [compiler hooks](/api/plugin-api/compiler-hooks.md) for more details.

### rspack

- **Type:** `typeof rspack`

Get the exports of @rspack/core to obtain the associated internal objects. This is especially useful when you cannot directly reference `@rspack/core` or there are multiple Rspack instances.

A common example is accessing the [sources](/api/javascript-api/index.md#sources-object) object in a Rspack plugin:

```js
const { RawSource } = compiler.rspack.sources;
const source = new RawSource('console.log("Hello, world!");');
```

### webpack

- **Type:** `typeof rspack`

Equivalent to `compiler.rspack`, this property is used for compatibility with webpack plugins.

If the Rspack plugin you are developing needs to be webpack compatible, you can use this property instead of `compiler.rspack`.

```js
console.log(compiler.webpack === compiler.rspack); // true
```

### name

- **Type:** `string`

Get the name:

- For the root compiler, it is equivalent to [`name`](/config/other-options.md#name).
- For the child compiler, it is the value passed into `createChildCompiler`.
- For the MultiCompiler and in the KV form, it is the key.

### context

Current project root directory:

- Created through `new Compiler`, it is the value passed in.
- Created through `rspack({})`, it is [context configuration](/config/context.md).

### root

- **Type:** `Compiler`

Get the root of the child compiler tree.

### options

- **Type:** `RspackOptionsNormalized`

Get the full options used by this compiler.

### target

- **Type:**

```ts
type CompilerTarget = {
  // ECMAScript version
  esVersion?: number | null;
  // Platform names with versions
  targets?: Record<string, string> | null;
};
```

Get the target information derived from the [`target`](/config/target.md) configuration. This is useful for plugin and loader authors who need to access the target environment information.

- `targets`: An object of platform names and their versions (e.g., `{ 'chrome': '87', 'firefox': '78', 'node': '18' }`).
- `esVersion`: The ECMAScript version number (e.g., `5`, `2015`, `2022`).

For example, access `compiler.target` in a plugin:

```js
class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.initialize.tap('ExamplePlugin', () => {
      const { targets, esVersion } = compiler.target ?? {};
      console.log(targets, esVersion);
    });
  }
}
```

Or access `compiler.target` in a custom loader:

```js title="my-loader.js"
export default function myLoader(source) {
  const options = this.getOptions();
  const compilerTarget = this._compiler.target ?? {};
  // Use user-specified targets, or fall back to Rspack's derived targets
  const targets = options.targets ?? compilerTarget.targets;
  // Fall back to Rspack's derived ECMAScript version when needed
  const ecmaVersion = options.ecmaVersion ?? compilerTarget.esVersion;
  // Use targets for transformation...
  return transform(source, { targets, ecmaVersion });
}
```

### watchMode

- **Type:** `boolean`

Whether started through `compiler.watch`.

### watching

- **Type:** `Watching`

Get the watching object, see [watch method](#watch) for more details.

### running

- **Type:** `boolean`

Whether the compilation is currently being executed.

### inputFileSystem

- **Type:** `InputFileSystem`

Get the proxy object used for reading from the file system, which has optimizations such as caching inside to reduce duplicate reading of the same file.


InputFileSystem.ts

### outputFileSystem

- **Type:** `OutputFileSystem`

Get the proxy object used for writing to the file system, `fs` by default.


OutputFileSystem.ts

### watchFileSystem

- **Type:** `WatchFileSystem`

Get the proxy object used for watching files or directories changes, which provides a `watch` method to start watching, and passes in the changed and removed items in the callback.


WatchFileSystem.ts

## MultiCompiler

The `MultiCompiler` module allows Rspack to run multiple configurations in separate compilers. If the options parameter in the Rspack's JavaScript API is an array of options, Rspack applies separate compilers and calls the callback after all compilers have been executed.

```js
import { rspack } from '@rspack/core';

rspack(
  [
    { entry: './index1.js', output: { filename: 'bundle1.js' } },
    { entry: './index2.js', output: { filename: 'bundle2.js' } },
  ],
  (err, stats) => {
    process.stdout.write(stats.toString() + '\n');
  },
);
```

It can also be created through `new MultiCompiler`:

```js
const compiler1 = new Compiler({/* */});
const compiler2 = new Compiler({/* */});

new MultiCompiler([compiler1, compiler2]);

new MultiCompiler([compiler1, compiler2], {
  parallelism: 1, // the maximum number of parallel compilers
});

new MultiCompiler({
  name1: compiler1,
  name2: compiler2,
});
```

`MultiCompiler` also provides some methods and attributes of the `Compiler`.

### MultiCompiler methods

#### setDependencies

Specify the dependency relationship between the compilers, using `compiler.name` as the identifier, to ensure the execution order of the compilers.

```ts
setDependencies(compiler: Compiler, dependencies: string[]): void;
```

#### validateDependencies

Check whether the dependency relationship between the compilers is legal. If there is a cycle or a missing dependency, it will trigger the callback.

```ts
validateDependencies(
  callback: (err: Error) => void; // callback when there is an error
): boolean
```

#### run

Execute the `run` method of each compiler according to the dependency relationship to start the compilation process.

```ts
run(
  callback: (err: Error, stats: MultiStats) => void,
  options?: {
    modifiedFiles?: ReadonlySet<string>; // Modified files included in this compilation
    removedFiles?: ReadonlySet<string>; // Deleted files included in this compilation
  },
): void;
```

#### watch

Execute the `watch` method of each compiler according to the dependency relationship to start watching, and start a compilation process after the file changes.

```ts
function watch(
  watchOptions: WatchOptions | WatchOptions[],
  handler: (err: Error, stats: MultiStats) => void,
): MultiWatching;
```

#### close

Execute the `close` method of each compiler to close them, and handle low-priority tasks such as caching during this period.

```ts
close(callback: (err: Error) => void): void;
```

#### purgeInputFileSystem

Execute the `purgeInputFileSystem` of each compiler to stop the read loop of the file system

```ts
purgeInputFileSystem(): void;
```

#### getInfrastructureLogger

Create a [logger object](/api/javascript-api/logger.md) that is not associated with any compilation, which is used to print global logs.

```ts
getInfrastructureLogger(name: string): Logger;
```

> Same with `compilers[0].getInfrastructureLogger()`


Logger.ts

### MultiCompiler properties

#### compilers

- **Type:** `Compiler[]`

Get all included compilers.


Compiler.ts

#### options

ReadOnly
- **Type:** `RspackOptionsNormalized[]`

Get all the [full options](/config/index.md) used by the compilers.

#### inputFileSystem

WriteOnly
- **Type:** `InputFileSystem`

Set the proxy object used for reading from the file system for each compiler.


InputFileSystem.ts

#### outputFileSystem

WriteOnly
- **Type:** `OutputFileSystem`

Set the proxy object used for writing from the file system for each compiler.


OutputFileSystem.ts

#### watchFileSystem

WriteOnly
- **Type:** `WatchFileSystem`

Set the proxy object used for watching files or directories changes for each compiler.


WatchFileSystem.ts

#### running

- **Type:** `boolean`

Whether the compilation is currently being executed.



---
url: /api/javascript-api/compilation.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Compilation

The Compilation object is one of the core objects used in the Rspack build process. Whenever Rspack performs a build (including rebuilds in watch mode), a new Compilation instance is created, which contains all the information about the current build.

This page lists the available methods and properties of the Compilation object. You can also refer to [Compilation Hooks](/api/plugin-api/compilation-hooks.md) to learn about the hooks provided by the Compilation object.

:::warning Notice
In Rspack, the real compilation object runs on the Rust side, and the JavaScript compilation object is only a **proxy object** used to communicate with the Rust compilation object.

Therefore, some complex data structures and methods will not be supported on the JavaScript compilation object, the data is **read-only** and the structure may differ from webpack.
:::

## Get compilation object

You can get the current compilation object via [compiler.hooks.thisCompilation](/api/plugin-api/compiler-hooks.md#thiscompilation) or [compiler.hooks.compilation](/api/plugin-api/compiler-hooks.md#compilation) hooks.

```js
class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.thisCompilation.tap('ExamplePlugin', (compilation) => {
      console.log('thisCompilation hook called:', compilation);
    });

    compiler.hooks.compilation.tap('ExamplePlugin', (compilation) => {
      console.log('compilation hook called:', compilation);
    });
  }
}
```

## Compilation methods

### emitAsset

Emit a new asset, throw an error if the asset already exists.

```ts
emitAsset(
  filename: string, // filename of the new asset
  source: Source, // content of the new asset
  info?: AssetInfo // asset info of the new asset
): void;
```

The following code will add a new asset named `asset-name.js` and will not be compressed because `minimized` is set to `true`:

```js
compiler.hooks.thisCompilation.tap('MyPlugin', (compilation) => {
  const { RawSource } = compiler.rspack.sources;
  compilation.hooks.processAssets.tap('MyPlugin', () => {
    const buffer = Buffer.from(
      'i am content of emit asset, do not minimize me',
    );
    const source = new RawSource(buffer, false);
    compilation.emitAsset('asset-name.js', source, {
      minimized: true,
    });
  });
});
```


Source.ts

AssetInfo.ts

### updateAsset

Update an existing asset, throw an error if the asset does not exist.

```ts
updateAsset(
  filename: string, // filename of the updating asset
  source: Source | ((source: Source) => Source), // the new content or a function returns the new content
  info?:  // the new info or a function returns the new info
    | AssetInfo
    | ((assetInfo: AssetInfo) => AssetInfo | undefined)
): void;
```

The following code replaces the content of `main.js`:

```js
compiler.hooks.thisCompilation.tap('MyPlugin', (compilation) => {
  const { RawSource } = compiler.rspack.sources;
  compilation.hooks.processAssets.tap('MyPlugin', () => {
    const updatedSource = new RawSource(`console.log("Updated");`);
    compilation.updateAsset('main.js', updatedSource, {
      // optional asset info...
    });
  });
});
```


Source.ts

AssetInfo.ts

### renameAsset

Rename an existing asset.

```ts
renameAsset(
  filename: string, // filename of the renaming asset
  newFilename: string // new filename
): void;
```

The following code renames the asset named `main.js` to `my-asset-name.js`:

```js
compiler.hooks.thisCompilation.tap('MyPlugin', (compilation) => {
  compilation.hooks.processAssets.tap('MyPlugin', () => {
    compilation.renameAsset('main.js', 'my-asset-name.js');
  });
});
```

### deleteAsset

Delete an existing asset.

```ts
deleteAsset(
  filename: string // filename of the deleting asset
): void;
```

The following code will delete the asset named `no-need.js`:

```js
compiler.hooks.thisCompilation.tap('MyPlugin', (compilation) => {
  compilation.hooks.processAssets.tap('MyPlugin', () => {
    compilation.deleteAsset('no-need.js');
  });
});
```

### getAssets

Get the list of asset objects.

```ts
getAssets(): ReadonlyArray<{
  name: string;
  source: Source;
  info: AssetInfo;
}>;
```

The following code will print the total size of all assets:

```js
compiler.hooks.compilation.tap('MyPlugin', (compilation) => {
  compilation.hooks.processAssets.tap('MyPlugin', () => {
    const assets = compilation.getAssets();
    const totalSize = assets.reduce(
      (total, asset) => total + asset.source.size(),
      0,
    );
    console.log(`total size: ${totalSize}`);
  });
});
```


Source.ts

AssetInfo.ts

### getAsset

Get the asset object with the specified name.

```ts
getAsset(
  name: string // name of the asset
): Readonly<{
  name: string;
  source: Source;
  info: AssetInfo;
}> | void;
```

The following code will print the size of the asset named `main.js`:

```js
compiler.hooks.compilation.tap('MyPlugin', (compilation) => {
  compilation.hooks.processAssets.tap('MyPlugin', () => {
    const assetSize = compilation.getAsset('main.js')?.source.size();
    console.log(`main size: ${assetSize}`);
  });
});
```


Source.ts

AssetInfo.ts

### getPath

Generate path string based on the Filename template, see [Filename placeholders](/config/filename-placeholders.md) for the template rules.

```ts
getPath(
  filename: Filename, // filename template
  data: PathData = {} // generating path data
): string;
```

The following code will replace the placeholder in the template to generate the path:

```js
const path = compilation.getPath('[contenthash]-[fullhash].js', {
  contentHash: 'some1',
  hash: 'some2',
});
console.log(path); // "some1-some2.js"
```


Filename.ts

PathData.ts

### getPathWithInfo

Generate path string and asset info based on the Filename template, see [Filename placeholders](/config/filename-placeholders.md).

```ts
getPathWithInfo(
  filename: Filename, // filename template
  data: PathData = {} // generating path data
): {
  path: string;
  info: AssetInfo;
};
```

The following code will replace the placeholder in the template to generate the path and asset info:

```ts
const { path, info } = compilation.getPathWithInfo(
  '[contenthash]-[fullhash].js',
  {
    contentHash: 'some1',
    hash: 'some2',
  },
);
console.log(path); // "some1-some2.js"
console.log(info);
/* Object {
  immutable: true,
  minimized: false,
  fullhash: [ 'some2' ],
  chunkhash: [],
  contenthash: [ 'some1' ],
  development: false,
  hotModuleReplacement: false,
  related: {},
  extras: {}
} */
```


Filename.ts

PathData.ts

AssetInfo.ts

### getStats

Get the stats object of current compilation:

```ts
getStats(): Stats;
```

The following code prints the total number of modules:

```js
compiler.hooks.emit.tapAsync('MyPlugin', (compilation) => {
  const modules = compilation.getStats().toJson({ modules: true }).modules;
  console.log(`Total modules: ${modules.length}`);
});
```


Stats.ts

### createChildCompiler

Allows running another instance of Rspack inside of Rspack. However, as a child with different settings and configurations applied. It copies all hooks and plugins from the parent (or top-level compiler) and creates a child `Compiler` instance. Returns the created `Compiler`.

```ts
createChildCompiler(
  name: string, // name for the child `Compiler`
  outputOptions: OutputNormalized, // Output options object
  plugins: RspackPluginInstance[] // Plugins that will be applied
): Compiler;
```

The following code will start a child compiler with `child-entry.js` as the entry, and output to `dist/child`:

```js
compiler.hooks.make.tap('MyPlugin', (compilation) => {
  const childCompiler = compilation.createChildCompiler(
    'ChildCompiler',
    {
      path: 'dist/child',
    },
    [new compiler.rspack.EntryPlugin(compiler.context, './child-entry.js')],
  );
  childCompiler.compile((err, childCompilation) => {});
});
```


Compiler.ts

### addRuntimeModule

Add a custom runtime module to the compilation.

```ts
addRuntimeModule(
  c: Chunk, // the runtime chunk which to add the runtime module
  m: RuntimeModule, // the runtime module instance to add
): void;
```

The following code will add a runtime module which define `__webpack_require__.mock` to the `"main"` chunk:

```js title="rspack.config.mjs"
export default {
  entry: './index.js',
  plugins: [
    {
      apply(compiler) {
        const { RuntimeModule } = compiler.rspack;

        class CustomRuntimeModule extends RuntimeModule {
          constructor() {
            super('custom');
          }

          generate() {
            const compilation = this.compilation;
            return `
            __webpack_require__.mock = function() {
              // ...
            };
          `;
          }
        }

        compiler.hooks.thisCompilation.tap('CustomPlugin', (compilation) => {
          compilation.hooks.runtimeRequirementInTree
            .for(RuntimeGlobals.ensureChunkHandlers)
            .tap('CustomPlugin', (chunk, set) => {
              if (chunk.name === 'main') {
                compilation.addRuntimeModule(chunk, new CustomRuntimeModule());
              }
            });
        });
      },
    },
  ],
};
```

When implementing a custom runtime module class, the following methods/properties can be overridden to control the behavior of the runtime module:

- Pass the `name` and `stage` parameters in the constructor to specify the module name and the insertion stage.
- Override the `generate()` method to control the generated code of the module.
- Override the `shouldIsolate()` method to control whether the module is wrapped in an IIFE.
- Override the `attach()` method to modify the behavior when the module is added.
- Modify its `fullHash` or `dependentHash` properties to control whether the module can be cached.

### rebuildModule

Triggers a re-build of the module.

```ts
rebuildModule(
  m: Module, // module to be rebuilt
  f: (err: Error | null, m: Module | null) => void //  function to be invoked when the module finishes rebuilding
): void;
```

The following code will rebuild the module ending with `a.js`:

```js
compiler.hooks.compilation.tap('MyPlugin', (compilation) => {
  compilation.hooks.finishModules.tapPromise('MyPlugin', async (modules) => {
    const oldModule = Array.from(modules).find((item) =>
      item.resource.endsWith('a.js'),
    );
    compilation.rebuildModule(oldModule, (err, m) => {
      console.log(`Rebuilt ${m.identifier()}.`);
    });
  });
});
```


Module.ts

### getLogger

Get a log output utility object with the specified name, which can be used to print logs with unified format in the plugin.

```ts
getLogger(name: string | (() => string)): Logger;
```

The following code prints the asset to the debug log in `processAssets`:

```js
compiler.hooks.compilation.tap('MyPlugin', (compilation) => {
  const logger = compilation.getLogger('MyPlugin');

  compilation.hooks.processAssets.tap('MyPlugin', () => {
    for (const asset of compilation.getAssets()) {
      logger.debug(`asset name: ${asset.name}`);
      logger.debug(`asset info: ${asset.info}`);
    }
  });
});
```


Logger.ts

### getCache

Get a cache object with the specified name, which can be used for the plugin to share data during multiple compilations.

```ts
getCache(name: string): CacheFacade;
```


Cache.ts

## Compilation properties

### options

**Type**: `RspackOptionsNormalized`

The normalized options used by this Compilation, see [Configure Rspack](/config/index.md) for details.

### runtimeTemplate

**Type**: `RuntimeTemplate`

Helpers that generate runtime code matching the capabilities of the targeted environment, as
declared by [`output.environment`](/config/output.md#outputenvironment). Use them instead of
hand-written snippets so that generated code stays valid for older targets.

```js
class MyPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap('MyPlugin', (compilation) => {
      const { runtimeTemplate } = compilation;

      // `() => (globalThis)` when arrow functions are supported,
      // `function() { return globalThis; }` otherwise
      runtimeTemplate.returningFunction('globalThis');

      // `(a) => {\n\tconsole.log(a);\n}` when arrow functions are supported,
      // `function(a) {\n\tconsole.log(a);\n}` otherwise
      runtimeTemplate.basicFunction('a', 'console.log(a);');
    });
  }
}
```


RuntimeTemplate.ts

### compiler

**Type**: `Compiler`

Current [compiler object](/api/javascript-api/index.md).


Compiler.ts

### hooks

The [Compilation hooks](/api/plugin-api/compilation-hooks.md).

### hash/fullhash

**Type**: `Readonly<string | null>`

The hash of this compilation.

### assets

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

The mapping from asset filenames and content sources.


Source.ts

### chunkGroups

**Type**: `ReadonlyArray<ChunkGroup>`

The list of chunk group objects, with the structure as follows:


ChunkGroup.ts

### entrypoints

**Type**: `ReadonlyMap<string, Entrypoint>`

The mapping from name to entrypoint, which is a special chunk group and include a runtime chunk.


Entrypoint.ts

### namedChunkGroups

**Type**: `ReadonlyMap<string, Readonly<ChunkGroup>>`

The mapping from names to chunk groups.


ChunkGroup.ts

### modules

**Type:** `ReadonlySet<Module>`

List of all modules, with the structure as follows:


Module.ts

### builtModules

**Type:** `ReadonlySet<Module>`

List of built modules that were not be cached, with the structure as follows:


Module.ts

### chunks

**Type:** `ReadonlySet<Chunk>`

List of all chunks, with the structure as follows:


Chunk.ts

### namedChunks

**Type:** `ReadonlyMap<string, Readonly<Chunk>>`

The mapping from names to chunks.


Chunk.ts

### fileDependencies

**Type:** `CompilationDependencies`

List of files this compilation depends on.


CompilationDependencies.ts

### contextDependencies

**Type:** `CompilationDependencies`

List of directories this compilation depends on.


CompilationDependencies.ts

### missingDependencies

**Type:** `CompilationDependencies`

List of not existing files this compilation depends on.


CompilationDependencies.ts

### buildDependencies

**Type:** `CompilationDependencies`

List of build dependencies this compilation depends on.


CompilationDependencies.ts

### errors

**Type:** `RspackError[]`

List of emitted errors during this compilation, with the structure as follows:


RspackError.ts

### warnings

**Type:** `RspackError[]`

List of emitted warnings during this compilation.


RspackError.ts


This page is adapted from [webpack documentation](https://webpack.js.org/api/compilation-object/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /api/javascript-api/stats.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Stats

The `stats` object that is passed as a second argument of the [`rspack()`](/api/javascript-api/index.md#rspack) callback, is a good source of information about the code compilation process. It includes:

- Errors and Warnings (if any)
- Timings
- Module and Chunk information

The `Stats` object provides two important methods:

- `toJson()`: Output information in the form of a [Stats JSON](/api/javascript-api/stats-json.md) object, which is often used in analysis tools.
- `toString()`: Output information in the form of a string, which is often used in the CLI tools.

Rspack also provides `StatsFactory` and `StatsPrinter` to fine-grained control the output object or string.

```txt title=Stats Output
Compilation ===============> Stats JSON =================> Stats Output
           ╰─ StatsFactory ─╯           ╰─ StatsPrinter ─╯
╰─────────── stats.toJson() ───────────╯
╰───────────────────────── stats.toString() ──────────────────────────╯
```

Create a stats object related to a compilation through [`compilation.getStats()`](/api/javascript-api/compilation.md#getstats) or `new Stats(compilation)`.

:::warning Timing matters

`stats.toJson()` and `stats.toString()` rely on compilation artifacts that are finalized in `compiler.hooks.done`. If they are called at other times (for example, on stale `Stats` objects captured earlier), some stats fields can be incomplete.

For complete and stable stats output, call these methods in `compiler.hooks.done`:

```js
compiler.hooks.done.tap('MyPlugin', (stats) => {
  const statsJson = stats.toJson({ all: false, errors: true, warnings: true });
  const statsText = stats.toString({ preset: 'errors-warnings' });
  console.log(statsJson.errors);
  console.log(statsText);
});
```

:::

## Stats methods

### hasErrors

Can be used to check if there were errors while compiling.

**Type:**

```ts
hasErrors(): boolean;
```

Use the return value to handle compilation errors:

```js
if (stats.hasErrors()) {
  console.error('Compilation failed');
}
```

### hasWarnings

Can be used to check if there were warnings while compiling.

**Type:**

```ts
hasWarnings(): boolean;
```

Use the return value to handle compilation warnings:

```js
if (stats.hasWarnings()) {
  console.warn('Compilation completed with warnings');
}
```

### toJson

Return the compilation information in the form of a [Stats JSON](/api/javascript-api/stats-json.md) object. The [Stats configuration](/config/stats.md) can be a string (preset value) or an object for granular control:

**Type:**

```ts
toJson(options?: StatsValue): StatsCompilation;
```

Use the `'minimal'` preset and print the number of errors:

```js
const statsJson = stats.toJson('minimal');
console.log(statsJson.errorsCount);
```

Use an options object to select the fields to include, then print the compilation hash:

```js
const statsJson = stats.toJson({
  assets: false,
  hash: true,
});
console.log(statsJson.hash);
```

### toString

Return the compilation information in the form of a formatted string (similar to the output of [CLI](/api/cli.md)).

**Type:**

```ts
toString(opts?: StatsValue): string;
```

Options are the same as `stats.toJson(options)` with one addition:

```js
stats.toString({
  // Add console colors
  colors: true,
});
```

Here's an example of `stats.toString()` usage:

```js
import { rspack } from '@rspack/core';

rspack(
  {
    // ...
  },
  (err, stats) => {
    if (err) {
      console.error(err);
      return;
    }

    console.log(
      stats.toString({
        chunks: false, // Makes the build much quieter
        colors: true, // Shows colors in the console
      }),
    );
  },
);
```

## Stats properties

### compilation

**Type:** `Compilation`

Get the related compilation object.


Stats.ts

### hash

**Type:** `string | null`

Get the hash of this compilation, same as [`Compilation.hash`](/api/javascript-api/compilation.md#hashfullhash).

When using it as a string, check for `null` first:

```js
if (stats.hash !== null) {
  console.log(stats.hash);
}
```

## MultiStats

When using `MultiCompiler` to run multiple compilation tasks, their results are packaged as a `MultiStats` object. It provides a combined hash and methods for checking, serializing, and formatting all child compilation results.

### hash

ReadOnly
**Type:** `string`

Get the hash formed by concatenating the hashes of all child compilations.

Print the concatenated hash:

```js
console.log(multiStats.hash);
```

### hasErrors

Returns `true` if any child compilation has errors.

**Type:**

```ts
hasErrors(): boolean;
```

Use the return value to handle errors across all child compilations:

```js
if (multiStats.hasErrors()) {
  console.error('At least one compilation failed');
}
```

### hasWarnings

Returns `true` if any child compilation has warnings.

**Type:**

```ts
hasWarnings(): boolean;
```

Use the return value to handle warnings across all child compilations:

```js
if (multiStats.hasWarnings()) {
  console.warn('At least one compilation completed with warnings');
}
```

### toJson

Returns a `StatsCompilation` whose `children` array contains the [Stats JSON](/api/javascript-api/stats-json.md) for each child compilation. Fields enabled for every child, such as `errors` and `warnings`, are also aggregated at the top level.

**Type:**

```ts
toJson(options: boolean | StatsPresets | MultiStatsOptions): StatsCompilation;
```

Use one preset for every child compilation and inspect the number of results:

```js
const statsJson = multiStats.toJson('minimal');
console.log(statsJson.children?.length);
```

`MultiStatsOptions` also supports a `children` option for configuring each child compilation individually. The following example prints the errors from the first child compilation:

```js
const statsJson = multiStats.toJson({
  children: [
    { all: false, errors: true },
    { all: false, assets: true },
  ],
});
console.log(statsJson.children?.[0]?.errors);
```

### toString

Format each child compilation according to the [stats configuration](/config/stats.md), then concatenate the results into one string.

**Type:**

```ts
toString(options: boolean | StatsPresets | MultiStatsOptions): string;
```

Use one preset for every child compilation and print the combined output:

```js
const statsText = multiStats.toString('minimal');
console.log(statsText);
```

## Stats factory

Used to generate the stats json object from the Compilation, and provides hooks for fine-grained control during the generation process.

It can be got through [`compilation.hooks.statsFactory`](/api/plugin-api/compilation-hooks.md#statsfactory). Or create a new one by `new StatsFactory()`.

### Hooks

See [StatsFactory hooks](/api/plugin-api/stats-hooks.md#statsfactory) for more details.

### create

The core method of `StatsFactory`, according to the `type` to specify the current data structure, find and run the corresponding generator to generate the stats json item.

```ts
stats = statsFactory.create('compilation', compilation, {});
```

> The `StatsFactory` object only handles the calling of hooks, and the processing code of the corresponding type can be found in [`DefaultStatsFactoryPlugin`](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack/src/stats/DefaultStatsFactoryPlugin.ts).

## Stats printer

Used to generate the output string from the stats json object, and provides hooks for fine-grained control during the generation process.

It can be got through [`compilation.hooks.statsPrinter`](/api/plugin-api/compilation-hooks.md#statsprinter). Or create a new one by `new StatsPrinter()`.

### Hooks

See [StatsPrinter hooks](/api/plugin-api/stats-hooks.md#statsprinter) for more details.

### print

The core method of `StatsPrinter`, according to the type to specify the current data structure, find and run the corresponding generator to generate the output string of the stats item.

```ts
stats = statsPrinter.print('compilation', stats, {});
```

> The `StatsPrinter` object only handles the calling of hooks, and the processing code of the corresponding type can be found in [`DefaultStatsPrinterPlugin`](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack/src/stats/DefaultStatsPrinterPlugin.ts).



---
url: /api/javascript-api/stats-json.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Stats JSON

While using Rspack, you can use the following command to generate a JSON file of the statistics module information to analyze the module dependency relationship:

```bash
# Generate a statistical information JSON file named `compilation-stats.json`
$ rspack --json=compilation-stats.json
```

## Structure

The properties included in the output depend on the [stats configuration](/config/stats.md). The known fields of the top-level object are as follows:

```ts
type StatsCompilation = {
  // Fixed simulated webpack version number for compatibility with plugins
  version?: string;
  // Current version number of rspack
  rspackVersion?: string;
  // Compilation name
  name?: string;
  // Compilation specific hash
  hash?: string;
  // Environment information included when `stats.env` is enabled
  env?: any;
  // Compilation time in milliseconds
  time?: number;
  // Compilation build end timestamp
  builtAt?: number;
  // The `output.publicPath` in the configuration
  publicPath?: string;
  // Path to rspack output directory
  outputPath?: string;
  // Chunk name to emitted asset(s) mapping
  assetsByChunkName?: Record<string, string[]>;
  // List of asset objects, refer to the "Asset Object"
  assets?: StatsAsset[];
  // Number of assets omitted from the output
  filteredAssets?: number;
  // List of chunk objects, refer to the "Chunk Object"
  chunks?: StatsChunk[];
  // List of module objects, refer to the "Module Object"
  modules?: StatsModule[];
  // Map of entry objects, refer to the "Entry/ChunkGroup Object"
  entrypoints?: Record<string, StatsChunkGroup>;
  // Map of named chunk groups, refer to the "Entry/ChunkGroup Object"
  namedChunkGroups?: Record<string, StatsChunkGroup>;
  // List of error objects, refer to the "Error/Warning Object"
  errors?: StatsError[];
  // Number of errors
  errorsCount?: number;
  // Number of error details omitted from the output
  filteredErrorDetailsCount?: number;
  // List of warning objects, refer to the "Error/Warning Object"
  warnings?: StatsError[];
  // Number of warnings
  warningsCount?: number;
  // Number of warning details omitted from the output
  filteredWarningDetailsCount?: number;
  // Number of modules omitted from the output
  filteredModules?: number;
  // Stats for child compilations
  children?: StatsCompilation[];
  // Compilation logs, grouped by logger name
  logging?: Record<string, StatsLogging>;
} & Record<string, any>;
```

## Asset object

Each asset object represents an output file emitted from the compilation, and its structure is as follows:

```ts
type StatsAssetInfo = {
  // Whether the asset can be long-term cached because its name contains a hash
  immutable?: boolean;
  // Whether the asset was minimized
  minimized?: boolean;
  // Full hash values used by this asset
  fullhash: string[];
  // Chunk hash values used by this asset
  chunkhash: string[];
  // Content hash values used by this asset
  contenthash: string[];
  // Original source filename, when the asset was created from a source file
  sourceFilename?: string;
  // Whether the asset was copied from another file
  copied?: boolean;
  // Whether the asset exceeds `performance.maxAssetSize`
  isOverSizeLimit?: boolean;
  // Whether the asset is only used in development
  development?: boolean;
  // Whether the asset contains data for hot module replacement
  hotModuleReplacement?: boolean;
  // Whether the asset is JavaScript emitted as an ES module
  javascriptModule?: boolean;
  // Related asset filenames, grouped by relationship type
  related: Record<string, string[]>;
} & Record<string, any>;

type StatsAsset = {
  // Stats item type, such as "asset" or a related asset type
  type: string;
  // The `output` filename
  name: string;
  // Additional information about the asset
  info: StatsAssetInfo;
  // The size of the file in bytes
  size: number;
  // Whether the asset was emitted during this compilation
  emitted: boolean;
  // Whether the asset was not emitted during this compilation (`!emitted`)
  cached: boolean;
  // Related assets, such as source maps
  related?: StatsAsset[];
  // Chunk IDs related to this asset
  chunks?: Array<string | number | null | undefined>;
  // Chunk names related to this asset
  chunkNames?: string[];
  // Chunk ID hints related to this asset
  chunkIdHints?: string[];
  // Chunk IDs related to this auxiliary asset
  auxiliaryChunks?: Array<string | number | null | undefined>;
  // Chunk names related to this auxiliary asset
  auxiliaryChunkNames?: string[];
  // Chunk ID hints related to this auxiliary asset
  auxiliaryChunkIdHints?: string[];
  // Number of related assets omitted from the output
  filteredRelated?: number;
  // Whether the asset exceeds `performance.maxAssetSize`
  isOverSizeLimit?: boolean;
} & Record<string, any>;
```

## Chunk object

Each chunk object represents a group of modules known as a chunk, and its structure is as follows:

```ts
type StatsChunk = {
  // Stats item type
  type: string;
  // The list of product files contained in the chunk
  files: string[];
  // The list of attached product files contained in the chunk
  auxiliaryFiles: string[];
  // Chunk ID
  id?: string | number;
  // List of chunk names contained within this chunk
  names: string[];
  // List of ID hints associated with the chunk
  idHints: string[];
  // The runtime used by the chunk
  runtime: string[];
  // Size of the chunk (in bytes)
  size: number;
  // Total size of chunk modules group by the output type (in bytes)
  sizes: Record<string, number>;
  // Chunk hash
  hash?: string;
  // Whether the chunk contains an entry module
  entry: boolean;
  // Whether the chunk is loaded on initial page load or on demand
  initial: boolean;
  // Whether the chunk was rendered into an output asset
  rendered: boolean;

  // Parent chunk IDs
  parents?: Array<string | number>;
  // Children chunk IDs
  children?: Array<string | number>;
  // Sibling chunk IDs
  siblings?: Array<string | number>;
  // Child chunks grouped by loading order
  childrenByOrder: Record<string, Array<string | number>>;

  // Chunk create reason when splitting chunks (need to enable `optimization.splitChunks`).
  reason?: string;

  // List of origins describing how the given chunk originated
  origins?: StatsChunkOrigin[];

  // List of modules contained in the chunk, for details, refer to the "Module Object"
  modules?: StatsModule[];
  // Number of modules omitted from the output
  filteredModules?: number;
} & Record<string, any>;

type StatsChunkOrigin = {
  // Module identifier (compatibility alias of `moduleIdentifier`)
  module: string;
  // Internal identifier of the originating module
  moduleIdentifier: string;
  // Readable name of the originating module
  moduleName: string;
  // Location of the dependency in the originating module
  loc: string;
  // The dependency request in the module
  request: string;
  // ID of the module
  moduleId?: string | number | null;
} & Record<string, any>;
```

## Module object

Each module object represents a module in the dependency graph, and its structure is as follows:

```ts
type StatsModule = {
  // Stats item type
  type: string;
  // Module source type
  moduleType: string;
  // Module layer
  layer?: string;
  // A unique identifier used internally
  identifier?: string;
  // Path to the actual file
  name?: string;
  // Absolute path used by the module for conditional matching
  nameForCondition?: string;
  // Legacy aliases for preOrderIndex and postOrderIndex
  index?: number;
  index2?: number;
  // The top-down and bottom-up indexes of the module in the chunk group
  preOrderIndex?: number;
  postOrderIndex?: number;
  // Estimated size of the module in bytes
  size: number;
  // Module sizes grouped by source type
  sizes: Record<string, number>;
  // Whether the module can be cached
  cacheable?: boolean;
  // Whether the module went through loaders and parsing
  built: boolean;
  // Whether the module went through code generation
  codeGenerated: boolean;
  // Whether the module was executed during the build
  buildTimeExecuted: boolean;
  // Whether the module was reused from cache
  cached: boolean;
  // Whether a missing module only produces a warning
  optional?: boolean;
  // Whether the module is not included in any chunk
  orphan?: boolean;
  // Module ID
  id?: string | number | null;
  // Parent module ID
  issuerId?: string | number | null;
  // IDs of chunks that contain the module
  chunks?: Array<string | number>;
  // Assets generated by the module
  assets?: string[];
  // Whether the module is only included as a dependency of another module
  dependent?: boolean;
  // Unique identifier of the parent module
  issuer?: string;
  // Path to the actual file of parent module
  issuerName?: string;
  // Reference path from the entry to the current module
  issuerPath?: StatsModuleIssuer[];
  // Whether the module failed to compile
  failed?: boolean;
  // Number of errors
  errors?: number;
  // Number of warnings
  warnings?: number;
  // Reasons why the module is included
  reasons?: StatsModuleReason[];
  // Number of reasons omitted from the output
  filteredReasons?: number;
  // Used module exports (`true` means all exports are used)
  usedExports?: boolean | string[] | null;
  // List of fields exported by the module (need to enable `optimization.providedExports`)
  providedExports?: string[] | null;
  // Optimization bailout reasons (need to enable `optimization.concatenateModules`)
  optimizationBailout?: string[] | null;
  // The module's depth in the module graph
  depth?: number;
  // If current module is generated by scope hoisting, this is the list of the original modules (need to enable `optimization.concatenateModules`)
  modules?: StatsModule[];
  // Number of nested modules omitted from the output
  filteredModules?: number;
  // Source code
  source?: string | Buffer;
} & Record<string, any>;

type StatsModuleIssuer = {
  identifier: string;
  name: string;
  id?: string | number | null;
} & Record<string, any>;

type StatsModuleReason = {
  moduleIdentifier?: string;
  moduleName?: string;
  resolvedModuleIdentifier?: string;
  resolvedModule?: string;
  type?: string;
  active: boolean;
  explanation?: string;
  userRequest?: string;
  loc?: string;
  moduleId?: string | number | null;
  resolvedModuleId?: string | number | null;
} & Record<string, any>;
```

## Entry/ChunkGroup Object

Each entrypoint or chunk group object represents a group of chunks and assets, and its structure is as follows:

```ts
type StatsEntrypoints = Record<string, StatsChunkGroup>;
type StatsNamedChunkGroups = Record<string, StatsChunkGroup>;

type StatsChunkGroup = {
  // Name of the chunk group
  name: string;
  // List of IDs of the chunks included
  chunks: Array<string | number>;
  // Assets generated by the chunk group
  assets: Array<{
    // File name
    name: string;
    // File size
    size: number;
  }>;
  // Present on entrypoint and named chunk group objects, but omitted from nested children
  // Total asset count if it exceeds `stats.chunkGroupMaxAssets`; otherwise 0
  filteredAssets?: number;
  // Total size of the assets generated by the chunk group
  assetsSize: number;

  // Auxiliary assets generated by the chunk group
  auxiliaryAssets?: Array<{
    // File name
    name: string;
    // File size
    size: number;
  }>;
  // Total size of the auxiliary assets generated by the chunk group
  auxiliaryAssetsSize?: number;
  // Ordered children chunk groups, order by preload/prefetch
  children?: {
    // preload children chunk groups
    preload?: StatsChunkGroup[];
    // prefetch children chunk groups
    prefetch?: StatsChunkGroup[];
  };
  // Assets of ordered children chunk groups, order by preload/prefetch
  childAssets?: {
    // preload assets
    preload?: string[];
    // prefetch assets
    prefetch?: string[];
  };
  // Whether the assets of this entrypoint exceeds performance.maxEntrypointSize
  isOverSizeLimit?: boolean;
} & Record<string, any>;
```

## Error/Warning Object

Each error or warning object represents an error/warning thrown during the build process, and its structure is as follows:

```ts
type StatsError = {
  // Visual message of the error/warning
  message: string;
  // Machine-readable error/warning code
  code?: StatsErrorCode | string;
  // A custom filename associated with this error/warning.
  file?: string;
  // Detail info of the error/warning
  details?: string;
  // Number of detail lines omitted because of `stats.errorsSpace` or `stats.warningsSpace`
  filteredDetails?: number;
  // Stack info of the error/warning
  stack?: string;
  /**
   * The identifier of the module related to this error/warning.
   * Usually an absolute path, may include inline loader requests.
   * @example
   * - `/path/to/project/src/index.js`
   * - `!builtin:react-refresh-loader!/path/to/project/src/index.css`
   */
  moduleIdentifier?: string;
  /**
   * The readable name of the module related to this error/warning.
   * Usually a relative path, no inline loader requests.
   * @example
   * - `"./src/index.js"`
   * - `"./src/index.css"`
   */
  moduleName?: string;
  // Location of the error/warning in the module
  loc?: string;
  // ID of the module where the error/warning occurs
  moduleId?: string | number | null;
  // Module import trace from entry module
  moduleTrace?: StatsModuleTraceItem[];

  // ID of the related chunk
  chunkId?: string;
  // Name of the related chunk
  chunkName?: string;
  // Whether the related chunk is an entry chunk
  chunkEntry?: boolean;
  // Whether the related chunk is an initial chunk
  chunkInitial?: boolean;
} & Record<string, any>;

type StatsModuleTraceItem = {
  originIdentifier: string;
  originName: string;
  moduleIdentifier: string;
  moduleName: string;
  originId?: string | number | null;
  moduleId?: string | number | null;
  dependencies: StatsModuleTraceDependency[];
};

type StatsModuleTraceDependency = {
  loc: string;
} & Record<string, any>;
```

## Logging object

Each key in `StatsCompilation.logging` is a logger name, and its value has the following structure:

```ts
type StatsLogging = {
  entries: StatsLoggingEntry[];
  filteredEntries: number;
  debug: boolean;
} & Record<string, any>;

type StatsLoggingEntry = {
  type: string;
  message: string;
  trace?: string[] | undefined;
  children?: StatsLoggingEntry[] | undefined;
} & Record<string, any>;
```


This page is adapted from [webpack documentation](https://webpack.js.org/api/stats/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /api/javascript-api/logger.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Logger

Logging output is an additional way to display messages to the end users.

Rspack logger is available to [loaders](/guide/features/loader.md) and [plugins](/guide/features/plugin.md). Emitting as part of the [Stats](/api/javascript-api/stats-json.md) and configured by the user in [rspack configuration](/config/index.md).

Benefits of custom logging API in Rspack:

- Common place to configure the logging display level
- Logging output exportable as part of the `stats.json`
- Stats presets affect logging output
- Plugins can affect logging capturing and display level
- When using multiple plugins and loaders they use a common logging solution
- CLI, UI tools for Rspack may choose different ways to display logging
- Rspack core can emit logging output, e.g. timing data

By introducing Rspack logging API we hope to unify the way Rspack plugins and loaders emit logs and allow better ways to inspect build problems. Integrated logging solution supports plugins and loaders developers by improving their development experience. Paves the way for non-CLI Rspack solutions like dashboards or other UIs.

:::warning Avoid noise in the log
**Avoid noise in the log!**

Keep in mind that multiple plugins and loaders are used together. Loaders are usually processing multiple files and are invoked for every file. Choose a logging level as low as possible to keep the log output informative.
:::

## Examples

### In plugin

There are two types of logging methods:

1. [compilation.getLogger](/api/javascript-api/compilation.md#getlogger): the content will be stored within the stats, use this when logging is related to the compilation.
2. `compiler.getInfrastructureLogger`: the content will not be stored, used this when logging is outside the compilation cycle.

You can use them in your plugin like below:

```js title=MyPlugin.js
const PLUGIN_NAME = 'my-plugin';
export class MyRspackPlugin {
  apply(compiler) {
    // access Logger from compiler
    const logger = compiler.getInfrastructureLogger(PLUGIN_NAME);
    logger.log('log from compiler');

    compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
      // access Logger from compilation
      const logger = compilation.getLogger(PLUGIN_NAME);
      logger.info('log from compilation');
    });
  }
}
```

### In loader

You can get the logger from loader context like below:

```js title="my-loader.mjs"
export default function (source) {
  // access Logger from loader
  const logger = this.getLogger('my-loader');
  logger.info('hello Logger');
  return source;
}
```

## Logger API

### Basic API

**Type:** `(...args: any[]): void;`

Methods are in turn from high to low according to the log level:

- `error`: for error messages.
- `warn`: for warnings.
- `info`: for important information messages. These messages are displayed by default. Only use this for messages that the user really needs to see.
- `log`: for unimportant information messages. These messages are displayed only when user had opted-in to see them.
- `debug`: for debugging information. These messages are displayed only when user had opted-in to see debug logging for specific modules.

While using `compilation.getLogger`, the output level can be controlled by `stats.logging` and `stats.loggingDebug`:


```js title="rspack.config.mjs"
export default {
  plugins: [{
    apply(compiler) {
      compiler.hooks.thisCompilation.tap("test plugin", compilation => {
        const logger = compilation.getLogger("TEST");
        logger.error("I am an error");
        logger.warn("I am a warning");
        logger.info("I am an information");
        logger.log("I am a log");
        logger.debug("I am a debug log");
      });
    }
  }],
  stats: {
    logging: "verbose",
    loggingDebug: true
  },
};
```
```js title=Output
asset main.js 264 bytes [emitted] (name: main)
runtime modules 124 bytes 2 modules
./index.js 15 bytes [built] [code generated]

DEBUG LOG from TEST
<e> I am an error
<w> I am a warning
<i> I am an information
    I am a log
    I am a debug log
```

While using `compiler.getInfrastructureLogger`, the output level can be controlled by `infrastructureLogging.level` and `infrastructureLogging.debug`:


```js title="rspack.config.mjs"
export default {
  plugins: [{
    apply(compiler) {
      compiler.hooks.thisCompilation.tap("test plugin", compilation => {
        const logger = compiler.getInfrastructureLogger("TEST");
        logger.error("I am an error");
        logger.warn("I am a warning");
        logger.info("I am an information");
        logger.log("I am a log");
        logger.debug("I am a debug log");
      });
    }
  }],
  infrastructureLogging: {
    level: "verbose",
    debug: true
  },
};
```
```js title=Output
<e> [TEST] I am an error
<w> [TEST] I am a warning
<i> [TEST] I am an information
    [TEST] I am a log
    [TEST] I am a debug log
Rspack compiled successfully in 49 ms
```

### assert

Display errors when assertion is false.

- **Level:** `error`
- **Type:**: `assert(assertion: any, ...args: any[]): void;`


```js
logger.assert(false, "I am an assert error");
logger.assert(true, "Never displayed");
```
```js title=Output
LOG from TEST
<e> I am an assert error
```

### status

Display progress status information, use `console.status` if exists, otherwise fallback to \`console.info.

- **Level:** `info`
- **Type:** `status(...args: any[]): void`


```js
logger.status("status info");
```
```js title=Output
[TEST] status info
```

### trace

Display a stack trace, only available while using compilation logger and also need to enable the `stats.loggingTrace`.

- **Level:** `debug`
- **Type:** `trace(): void`


```js
logger.trace();
```
```js title=Output
DEBUG LOG from TEST
    Trace
|     at Object.fn
|     at SyncHook.callAsyncStageRange
```

### clear

Clean all logs, just like `console.clear()`.

- **Level:** `log`
- **Type:** `clear(): void;`


```js
logger.debug("not displayed");
logger.clear();
logger.debug("will displayed");
```
```js title=Output
[TEST] will displayed
```

### Group API

Includes these methods:

- `group(...args: any[]): void`: to group messages. Displayed collapsed like `logger.log`.
- `groupEnd(...args: any[]): void`: to end a logging group.
- `groupCollapsed(...args: any[]): void`: to group messages together. Displayed collapsed like `logger.log`. Displayed expanded when logging level is set to `'verbose'` or `'debug'`.


```js
logger.group("Group");
logger.info("Info");
logger.log("Log");
logger.debug("Debug");
logger.groupCollapsed("Collapsed group");
logger.log("Log inside collapsed group");
logger.group("Inner group");
logger.log("Inner inner message");
logger.groupEnd();
logger.groupEnd();
logger.log("Log");
logger.groupEnd();
logger.log("End");
```
```js title=Output
<-> [TEST] Group
  <i> [TEST] Info
      [TEST] Log
      [TEST] Debug
  <-> [TEST] Collapsed group
        [TEST] Log inside collapsed group
    <-> [TEST] Inner group
          [TEST] Inner inner message
      [TEST] Log
    [TEST] End
```

### Time API

Includes these methods:

- `time(label: any): void`: to start a timer.
- `timeLog(label: any): void`: record time difference without ending the timer.
- `timeEnd(label: any): void`: to end the timer and record the time difference.
- `timeAggregate(label: any): void`: to aggregate capture the time difference.
- `timeAggregateEnd(label: any): void`: to end the aggregate capturing and record the total difference.


```js
const wait = time => new Promise(resolve => setTimeout(resolve, time))
logger.time("normal");
await wait(100);
logger.timeLog("normal");
await wait(100);
logger.timeEnd("normal");

for (let i = 10;i--;) {
logger.time("aggregate")
await wait(i \* 10);
logger.timeAggregate("aggregate")
}
logger.timeAggregateEnd("aggregate")

```
```js title=Output
<t> [TEST] normal: 101.091167 ms
<t> [TEST] normal: 202.565 ms
<t> [TEST] aggregate: 460.416124 ms
```

### Profile API

Includes these methods:

- `profile(label: any): void`: to start capturing a profile. Delegated to `console.profile` when supported.
- `profileEnd(label: any): void`: to end capturing a profile. Delegated to `console.profileEnd` when supported.

### Child logger

You can also create a child logger with `logger.getChildLogger()`. Child logger has same methods.


```js
const logger = compiler.getInfrastructureLogger("TEST");
logger.info("logger info");
const childLogger = logger.getChildLogger("CHILD");
childLogger.info("child logger info");
```
```js title=Output
<i> [TEST] logger info
<i> [TEST/CHILD] child logger info
```


This page is adapted from [webpack documentation](https://webpack.js.org/api/logging/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /api/javascript-api/cache.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Cache

When writing Rspack plugins, you can use `compiler.getCache(name: string)` or `compilation.getCache(name: string)` to get the cache object which can share data in the build process. The cache data is stored on the `Compiler`, so it can be used in multiple `Compilation`s in the watch mode.

:::warning Notice

- Only available when [cache: true](/config/cache.md) which it is enabled in `mode="development"` by default.
- Only used for the JavaScript plugins, the Rust cache cannot be accessed.
- Only memory cache is provided, persistent cache is not supported yet.

:::

## Example

The following code finds out the newly added assets in the `processAssets`:

```js
compiler.hooks.compilation.tap('MyPlugin', (compilation) => {
  compilation.hooks.processAssets.tapPromise('MyPlugin', async () => {
    const cache = compilation.getCache('MyPlugin');
    const currentAssets = compilation.getAssets().map((i) => i.name);
    const lastAssets = await cache.getPromise('assets', null);
    if (lastAssets) {
      for (const asset of currentAssets) {
        if (!lastAssets.includes(asset)) {
          console.log(`New asset: ${asset}`);
        }
      }
    }
    await cache.storePromise('assets', null, currentAssets);
  });
});
```

## Methods

### Caching

#### get/getPromise

Get cache data asynchronously, callback by function or promise.

- **Type:**
  - `get`: `<T>(identifier: string, etag: Etag | null, callback: (err: Error, result: T) => void): void`
  - `getPromise`: `<T>(identifier: string, etag: Etag | null): Promise<T>;`
- **Arguments:**
  - identifier: ID of data item
  - etag: Etag of the data item, can be generated by `getLazyHashedEtag`

#### store/storePromise

Store cache data asynchronously, callback by function or promise.

- **Type:**
  - `store`: `<T>(identifier: string, etag: Etag | null, data: T, callback: (err: Error) => void): void;`
  - `storePromise`: `<T>(identifier: string, etag: Etag | null): Promise<T>;`
- **Arguments:**
  - identifier: ID of data item
  - etag: Etag of the data item, can be generated by `getLazyHashedEtag`

#### provide/providePromise

Try to get cache data asynchronously, call the computer function to generate when not exists, callback by function or promise.

- **Type:**
  - `provide`:
    ```ts
    provide<T>(
      identifier: string,
      etag: Etag | null,
      computer: (fn: (err: Error, result: T) => void) => void,
      callback: () => T | Promise<T>,
    ): void;
    ```
  - `providePromise`
    ```ts
    providePromise<T>(
      identifier: string,
      etag: Etag | null,
      computer: () => T | Promise<T>,
    ): Promise<T>;
    ```
- **Arguments:**
  - identifier: ID of data item
  - etag: Etag of the data item, can be generated by `getLazyHashedEtag`
  - computer: The called generating function when cache is not exists


```js title=MyPlugin.js
const createAssetsData = async () => {
  console.log('only called once');
  return compilation.getAssets().map((i) => i.name);
};

compilation.hooks.processAssets.tapPromise('MyPlugin', async () => {
  const cache = compilation.getCache('MyPlugin');
  console.log(await cache.getPromise('assets', null)); // undefined
  await cache.providePromise('assets', null, createAssetsData); // call createAssetsData
  console.log(await cache.getPromise('assets', null)); // ["main.js"]
  await cache.providePromise('assets', null, createAssetsData); // not call
});
```
```txt title=Output
undefined
only called once
[ 'main.js' ]
```

### getLazyHashedEtag/mergeEtags

By using the `getLazyHashedEtag` and `mergeEtags` methods, an etag can be created as the unique identifier of the data item. It will not be calculated immediately when created, but rather delayed until it is used, and also can be cached. This can be used to improve performance when complex data objects are used as the unique identifier.

- `getLazyHashedEtag`: `(obj: HashableObject): Etag`, calculates the hash of the object to generate the etag as the data identifier, the object needs to implement the `updateHash(hash: Hash)`.
- `mergeEtags`: `(a: Etag, b: Etag): Etag`, merges two etags to one.


```js title=MyPlugin.js
const cache = compilation.getCache('MyPlugin');
const dataEtag = cache.getLazyHashedEtag({
  content: 'a'.repeat(10000),
  updateHash(hash) {
    console.log("only called once");
    hash.update(this.content);
  }
});
const mergedEtag = cache.mergeEtags(dataEtag, "other etag");
await cache.storePromise("assets", mergedEtag, "cached value");
console.log(await cache.getPromise("assets", mergedEtag));
```
```txt title=Output
only called once
cached value
```

### getItemCache

By using the `getItemCache` method, a cache object for a single data item can be created. This cache object provides simplified data access methods, do not need identifier and etag as arguments any more.

- **Type:** `(identifier, etag): ItemCacheFacade`

```ts
type ItemCacheFacade = {
  get<T>(callback: (err: Error, result: T) => void): void; // async data getter, callback by function
  getPromise<T>(): Promise<T>; // async data getter, callback by promise
  store<T>(data: T, callback: (err: Error, result: T) => void): void; // async data setter, callback by function
  storePromise<T>(data: T): Promise<void>; // async data setter, callback by promise
  provide<T>( // try to get the data, use function to compute if not exists, callback by function
    computer: (fn: (err: Error, result: T) => void) => void,
    callback: (err: Error, result: T) => void,
  ): void;
  providePromise<T>( // try to get the data, use function to compute if not exists, callback by promise
    computer: (fn: (err: Error, result: T) => void) => void,
  ): Promise<T>;
};
```


```js title=MyPlugin.js
const cache = compilation.getCache('MyPlugin');
const itemCache = cache.getItemCache('item');
await itemCache.storePromise('cached value');
console.log(await itemCache.getPromise());
```
```txt title=Output
cached value
```

### getChildCache

By using the `getChildCache` method, a child cache object can be generated, with its interface being completely consistent, and it can be utilized when there are numerous caches that require grouping for storage.

- **Type:** `(name: string): CacheFacade`



---
url: /api/javascript-api/swc.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# SWC API

Rspack uses [SWC](https://swc.rs/) under the hood to transform and minify JavaScript code, and experimentally exposes some SWC JavaScript APIs through `rspack.experiments.swc`. This allows you to directly call SWC methods like `transform` or `minify` without installing the additional [@swc/core](https://www.npmjs.com/package/@swc/core) package.

## Examples

Here is a simple example demonstrating how to transform JavaScript code using Rspack:

```js
import { rspack } from '@rspack/core';

const { swc } = rspack.experiments;
const sourceCode = 'const a: number = 10;';

swc
  .transform(sourceCode, {
    filename: 'main.ts',
    jsc: {
      parser: {
        syntax: 'typescript',
      },
      // ...other options
    },
  })
  .then((result) => {
    console.log(result.code);
  });

const output = swc.transformSync(sourceCode, {
  filename: 'main.ts',
  jsc: {
    parser: {
      syntax: 'typescript',
    },
    // ...other options
  },
});
console.log(output.code);
```

In addition to using the `swc` API directly, you can also use it in loaders or plugins to help with code transform or minify.

```js title="my-loader.mjs"
export default function myLoader(source) {
  const { swc } = this._compiler.rspack.experiments;
  const customCode = `
    const a = 10;
    const b = 20;
    // custom code
  `;

  const callback = this.async();

  swc
    .minify(customCode, {
      compress: true,
      sourceMap: true,
      // ...other options
    })
    .then((result) => {
      callback(null, `${result.code}\n${source}`);
    });
}
```

```ts title="my-plugin.mjs"
class MyPlugin {
  apply(compiler) {
    const { swc } = compiler.rspack.experiments;

    compiler.hooks.emit.tapAsync('MyPlugin', (compilation, callback) => {
      const customCode = `
        const a = 10;
        const b = 20;
        // custom code
      `;

      const output = swc.minifySync(customCode, {
        compress: true,
        sourceMap: true,
        //...other options
      });
      // ....
    });
  }
}
```

## Options

The API options accepted by the above APIs are passed to SWC.

You can learn more about configuration options in the SWC official documentation:

- [SWC Transform API](https://swc.rs/docs/usage/core#transform) - Code transform options
- [SWC Minify API](https://swc.rs/docs/usage/core#minify) - Code minify options

```ts
declare namespace rspack {
  namespace experimental {
    declare const swc: {
      transform(
        code: string,
        options?: TransformOptions,
      ): Promise<TransformOutput>;
      minify(code: string, options?: JsMinifyOptions): Promise<TransformOutput>;
    };

    declare interface JsMinifyOptions {
      compress?: TerserCompressOptions | boolean;
      format?: JsFormatOptions & ToSnakeCaseProperties<JsFormatOptions>;
      mangle?: TerserMangleOptions | boolean;
      ecma?: TerserEcmaVersion;
      keep_classnames?: boolean;
      keep_fnames?: boolean;
      module?: boolean | 'unknown';
      safari10?: boolean;
      toplevel?: boolean;
      sourceMap?: boolean;
      outputPath?: string;
      inlineSourcesContent?: boolean;
    }

    declare interface TransformOptions {
      filename?: string;
      sourceMaps?: boolean;
      jsc?: {
        parser?: {
          syntax?: 'ecmascript' | 'typescript';
          decorators?: boolean;
          dynamicImport?: boolean;
          exportDefaultFrom?: boolean;
          exportNamespaceFrom?: boolean;
          importAssertions?: boolean;
          tsx?: boolean;
        };
        target?: string;
        loose?: boolean;
        externalHelpers?: boolean;
        keepClassNames?: boolean;
        keepFnName?: boolean;
        minifySyntax?: boolean;
        minifyWhitespace?: boolean;
        minifyIdentifiers?: boolean;
      };
      // ...
    }

    declare interface TransformOutput {
      code: string;
      map?: string;
    }
  }
}
```



---
url: /api/javascript-api/resolver.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Resolver API

Rspack uses the higher-performance [rspack-resolver](https://github.com/rstackjs/rspack-resolver) written in Rust to replace webpack's [enhanced-resolve](https://github.com/webpack/enhanced-resolve), and experimentally re-exports these APIs through `rspack.experiments.resolver`. This allows you to directly call rspack-resolver's functions like `resolver.sync` or `resolver.async`.

For complete usage and options, see [rspack-resolver](https://github.com/rstackjs/rspack-resolver). Below is a simple example demonstrating how to use Rspack to resolve module paths:

```js
import { rspack } from '@rspack/core';

const { resolver } = rspack.experiments;

// Directly use Resolver API with default options
const { path: resolvedPath } = resolver.sync(contextPath, './index.js');
const { path: resolvedPath } = await resolver.async(contextPath, './index.js');

// Use ResolverFactory with custom options
const customResolver = new resolver.ResolverFactory(resolveOptions);
const result = customResolver.sync(contextPath, './request.js');
const result = await customResolver.async(contextPath, './request.js');
```



---
url: /api/javascript-api/browser.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Browser API

`@rspack/browser` is a version of Rspack specifically designed for browser environments, without relying on WebContainers or any particular platform. Its API is consistent with the [JavaScript API](/api/javascript-api/index.md) of `@rspack/core`, while additionally providing features and interfaces tailored for the browser environment.

Welcome to try running Rspack in the browser at the [Rspack Playground](https://playground.rspack.rs/).

:::warning
`@rspack/browser` is currently experimental. We will continue to improve its online bundling capabilities, and future releases may introduce breaking changes.
:::

## Usage

Run `@rspack/browser` inside a dedicated Web Worker, because `Atomics.wait` is not allowed on the browser main thread.

Except for the browser-specific file system and Worker setup, the rest of the API is consistent with the [JavaScript API](/api/javascript-api/index.md) of `@rspack/core`.

```ts title="main.ts"
const worker = new Worker(new URL('./rspack.worker.ts', import.meta.url), {
  type: 'module',
});

worker.addEventListener('message', (event) => {
  if (event.data.type === 'done') {
    console.log(event.data.output);
  }
});
```

```ts title="rspack.worker.ts"
import { rspack, builtinMemFs } from '@rspack/browser';

builtinMemFs.volume.fromJSON({
  '/src/index.js': 'console.log("hello from rspack")',
});

rspack({ entry: '/src/index.js' }, (err, stats) => {
  self.postMessage({
    type: 'done',
    output: builtinMemFs.volume.readFileSync('/dist/main.js', 'utf-8'),
  });
});
```

## Response header settings

Note that `@rspack/browser` internally uses [SharedArrayBuffer](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) to implement shared memory across multiple threads. Therefore, you need to set response headers for both your development server and production deployment environment.

If you are using Rspack as your project's bundler, you can set it through [devServer.headers](/config/dev-server.md#devserverheaders):

```js title="rspack.config.mjs"
export default {
  devServer: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp',
    },
  },
};
```

If you are using Rsbuild as your project's bundler, you can set it through [server.headers](https://rsbuild.rs/config/server/headers#serverheaders):

```ts title="rsbuild.config.ts"
export default {
  server: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp',
    },
  },
};
```

For production environments, please refer to the documentation of your project's deployment platform.

## In-Memory File system

Since browsers cannot directly access the local file system, `@rspack/browser` provides an in-memory file system object `builtinMemFs` based on [memfs](https://www.npmjs.com/package/memfs) for reading and writing files in the browser environment. All file system reads and writes in both the Node.js and Rust sides are redirected to this in-memory file system, including reading project configuration, source code, `node_modules` dependencies, and writing output files.

Here is a basic usage example. For the full API, please refer to the [memfs documentation](https://github.com/streamich/memfs):

```ts
import { builtinMemFs } from '@rspack/browser';

// Write files to memfs
builtinMemFs.volume.fromJSON({
  // ...project files
});

// Read files from memfs
const files = builtinMemFs.volume.toJSON();
```

`builtinMemFs` is a global singleton instance. In scenarios involving concurrent builds of multiple projects, it is recommended to enable [experiments.useInputFileSystem](/config/experiments.md#experimentsuseinputfilesystem) to avoid conflicts.\
Please note that, currently in the `@rspack/browser`, `experiments.useInputFileSystem` can only intercept project files that will be ultimately bundled, and cannot intercept files relied upon during the build process, such as those used by Loaders (see also [BrowserRequirePlugin#modules](/api/javascript-api/browser.md#modules) below).

```js title="rspack.config.mjs"
import { builtinMemFs } from '@rspack/browser';

const projectFs = builtinMemFs.memfs(filteredFiles);
export default {
  plugins: [
    {
      apply: (compiler) => {
        compiler.hooks.beforeCompile.tap('SimpleInputFileSystem', () => {
          compiler.inputFileSystem = projectFs.fs;
          compiler.outputFileSystem = projectFs.fs;
        });
      },
    },
  ],
  experiments: {
    useInputFileSystem: [/.*/],
  },
};
```

## Browser-Specific Plugins

To better meet the bundling needs in browser environments, `@rspack/browser` offers several dedicated plugins.

### BrowserHttpImportEsmPlugin

In local development, developers usually download project dependencies via package managers and store them in the `node_modules` directory at the root of the project. When using `@rspack/browser`, you can pre-write dependencies into the `node_modules` directory within the in-memory file system. However, when the modules your project depends on are uncertain (e.g., allowing users to freely choose third-party dependencies), pre-writing all dependencies becomes impractical.

```ts
import { builtinMemFs } from '@rspack/browser';

builtinMemFs.volume.fromJSON({
  '/node_modules/react/index.js': '...',
});
```

`@rspack/browser` provides the `BrowserHttpImportEsmPlugin` plugin. This plugin rewrites third-party dependency module specifiers to URLs of ESM CDNs during module resolution. For example, `import React from "react"` will be rewritten as `import React from "https://esm.sh/react"`. Together with Rspack's [buildHttp](/config/experiments.md#experimentsbuildhttp) feature, dependencies can be dynamically loaded over HTTP during bundling.

```js title="rspack.config.mjs"
import { BrowserHttpImportEsmPlugin } from '@rspack/browser';

export default {
  plugins: [new BrowserHttpImportEsmPlugin({ domain: 'https://esm.sh' })],
  experiments: {
    buildHttp: {
      allowedUris: ['https://'],
    },
  },
};
```

As shown below, `BrowserHttpImportEsmPlugin` supports options to specify the ESM CDN domain or to specify particular versions or URLs for certain dependencies.

```ts
interface BrowserHttpImportPluginOptions {
  /**
   * ESM CDN domain
   */
  domain: string | ((resolvedRequest: ResolvedRequest) => string);
  /**
   * Specify ESM CDN URL for dependencies.
   * If a record is provided, it will be used to map package names to their CDN URLs.
   *
   * Once this function resolves a dependency, other options are ignored.
   */
  dependencyUrl?:
    | Record<string, string | undefined>
    | ((resolvedRequest: ResolvedRequest) => string | undefined);
  /**
   * Specify versions for dependencies.
   * Default to "latest" if not specified.
   */
  dependencyVersions?: Record<string, string | undefined>;
  /**
   * You can attach additional queries supported by the CDN to the `request.url`.
   * For example, to specify the external dependencies under esm.sh, you can do:
   * `request.url.searchParams.set("external", "react,react-dom")`
   */
  postprocess?: (request: ProcessedRequest) => void;
}
```

#### Compatibility with `resolve.alias`

When using `BrowserHttpImportEsmPlugin`, the rewriting of dependency identifiers occurs **before** the alias replacements defined in [resolve.alias](/config/resolve.md#resolvealias). This ordering can lead to conflicts between the plugin’s rewriting logic and alias resolution.

To resolve this issue, you can configure the plugin’s `dependencyUrl` option to preemptively skip requests that should be handled by `resolve.alias`:

```js title="rspack.config.mjs"
import { BrowserHttpImportEsmPlugin } from '@rspack/browser';

export default {
  resolve: {
    alias: {
      '@': '/src', // e.g., "@/util.js" will be resolved to "/src/util.js"
    },
  },
  plugins: [
    new BrowserHttpImportEsmPlugin({
      domain: 'https://esm.sh',
      dependencyUrl(resolvedRequest) {
        // Skip rewriting for requests starting with "@/” to allow alias resolution
        if (resolvedRequest.request.startsWith('@/')) {
          return resolvedRequest.request;
        }
      },
    }),
  ],
};
```

### BrowserRequirePlugin

In Rspack, certain scenarios require dynamically loading and executing JavaScript code, such as [Loaders](/guide/features/loader.md) or the template functions of [HtmlRspackPlugin](/plugins/html-rspack-plugin.md#use-template-function). Since this code may come from untrusted users, executing it directly in the browser environment poses potential security risks. To ensure safety, `@rspack/browser` throws errors by default in such cases to prevent unsafe code execution.

The `BrowserRequirePlugin` plugin provides two ways to address this requirement. Options for `BrowserRequirePlugin` are as follows:

```ts
interface BrowserRequirePluginOptions {
  /**
   * This function defines how to execute CommonJS code.
   */
  execute?: (code: string, runtime: CommonJsRuntime) => void;
  /**
   * This option provides a direct mapping from the module specifier to the module content, similar to the mechanism of a virtual module.
   * If this option is not provided or the mapping result is undefined, it will fallback to resolving from memfs and run `execute`.
   */
  modules?: Record<string, any> | ((id: string) => any);
}
```

#### `modules`


[Added in v1.6.0-beta.0](https://github.com/web-infra-dev/rspack/releases/tag/v1.6.0-beta.0)

This option allows you to directly map a module request id to any JavaScript object within the project. Note that you need to create a corresponding empty file in `memfs`:

```js title="rspack.config.mjs"
import { BrowserRequirePlugin, builtinMemfs } from '@rspack/browser';
import CustomLoader from './custom-loader';

builtinMemFs.volume.fromJSON({
  '/LOADER/custom-loader.js': '',
});

export default {
  module: {
    rules: [
      {
        test: /a\.js$/,
        loader: '/LOADER/custom-loader.js',
      },
    ],
  },
  plugins: [
    new BrowserRequirePlugin({
      modules: {
        '/LOADER/custom-loader.js': CustomLoader,
      },
    }),
  ],
};
```

#### `execute`

This option is used to simulate the `require` process in Node.js: it resolves modules based on memfs, reads file contents, and executes them. When modules is not provided, or the corresponding result is not found in modules, this path will be attempted.

:::warning
Rspack does not execute user code during bundling. For security, it is recommended to run the final bundled output inside an iframe.
:::

```js title="rspack.config.mjs"
import { BrowserRequirePlugin } from '@rspack/browser';

export default {
  plugins: [
    new BrowserRequirePlugin({ execute: BrowserRequirePlugin.unsafeExecute }),
  ],
};
```

You need to provide an `execute` function to dynamically run and load CommonJS modules and modify `runtime.module.exports` to set the module's exports. `@rspack/browser` provides an unsafe implementation `BrowserRequirePlugin.unsafeExecute` that internally uses `new Function` to execute code. You can also implement a safer version based on this API according to your needs, for example:

```ts
function safeExecute(code: string, runtime: CommonJsRuntime) {
  const safeCode = sanitizeCode(code);
  BrowserRequirePlugin.unsafeExecute(safeCode, runtime);
}

function uselessExecute(_code: string, runtime: CommonJsRuntime) {
  runtime.module.exports.hello = 'rspack';
}
```

## Using Module Federation

`@rspack/browser` supports Rspack's [ModuleFederationPlugin](/plugins/module-federation-plugin.md). With this feature, you can pre-bundle complex dependency modules as provider projects deployed to CDN, and then use them in consumer projects that are bundled online in the browser.

When using ModuleFederationPlugin in the browser, please note the following:

1. You need to enable the [BrowserHttpImportEsmPlugin](/api/javascript-api/browser.md#browserhttpimportesmplugin) plugin, as module federation needs to load its runtime dependencies. The CDN needs to provide the development version of `@module-federation/webpack-bundler-runtime` (Magic Comments in the output shouldn't be removed).
2. Shared modules set in ModuleFederationPlugin also need to be configured with `external` and specified versions in BrowserHttpImportEsmPlugin. If you're using `esm.sh` as CDN, you can refer to the following code:

```js title="rspack.config.mjs"
import { BrowserHttpImportEsmPlugin } from '@rspack/browser';

new BrowserHttpImportEsmPlugin({
  domain: 'https://esm.sh',
  dependencyVersions: {
    react: '19.1.1',
  },
  postprocess: (request) => {
    // Set the `dev` parameter for `react-dom` here as well, as you need to ensure that the provider and consumer projects use the same mode of `react` and `react-dom`.
    if (
      request.packageName === '@module-federation/webpack-bundler-runtime' ||
      request.packageName === 'react-dom'
    ) {
      request.url.searchParams.set('dev', '');
    }
    request.url.searchParams.set('external', 'react');
  },
});
```

3. All [ModuleFederationPlugin.shared](/plugins/module-federation-plugin.md#shared) configurations must set `import: false`, meaning that consumer projects bundled online cannot bundle shared modules themselves; shared modules must be provided by pre-bundled provider projects.
4. [ModuleFederationPlugin.implementation](/plugins/module-federation-plugin.md#implementation) option is not supported.



---
url: /api/loader-api/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Overview

## Compatibility

Rspack is committed to being compatible with the loaders within the webpack ecosystem. We ensure that Rspack is as compatible as possible with the webpack loader API, allowing more existing webpack loaders to be directly used in Rspack.

Currently, Rspack is compatible with most of webpack's loader APIs. If you find that a webpack loader cannot be used in Rspack, feel free to file an issue in the [Rspack repository](https://github.com/web-infra-dev/rspack).

## Writing loaders

We provide some basic examples of different types of loaders. If you want to write a loader, you can refer to [Writing loaders](/api/loader-api/writing-loaders.md) to get started.

If you need to use an existing loader, you can refer to [Features - Loader](/guide/features/loader.md) to learn how to use it.

## Loader API

Loader API includes:

- [Loader context](/api/loader-api/context.md): Represents the properties that are available inside of a loader assigned to the `this` property.
- [Inline loader](/api/loader-api/inline.md): Specify a loader in an `import` statement.
- [Inline matchResource](/api/loader-api/inline-match-resource.md): Allows you to dynamically change the matching rules when loading resources.



---
url: /api/loader-api/writing-loaders.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Writing loaders

Learn how to create custom loaders for Rspack to transform files.

## Loader types

Rspack supports multiple loader types, including sync loader, async loader, ESM loader, Raw loader, and Pitching loader.

The following sections provide some basic examples of the different types of loaders.

### Sync loader

Sync loaders are the most basic type of loader. They can synchronously return transformed content using either a `return` statement or the `this.callback` method:

```js title="sync-loader.js"
module.exports = function (source, map, meta) {
  return someSyncOperation(source);
};
```

Compared to the `return` statement, the `this.callback` method offers more flexibility as it allows passing multiple parameters, including error information, source maps, and metadata:

```js title="sync-loader-with-callback.js"
module.exports = function (source, map, meta) {
  this.callback(null, someSyncOperation(source), map, meta);

  // Return undefined when calling callback() to avoid return value conflicts
  return;
};
```

::: info

- The `map` and `meta` parameters are optional, see [this.callback](/api/loader-api/context.md#thiscallback) and [Handling source maps](#handling-source-maps) for more details.
- Rspack will internally convert loaders to async, regardless of whether it's a synchronous loader, for technical and performance reasons.

:::

### Async loader

When you need to perform async operations (such as file I/O, network requests, etc.), you should use an async loader. Call the [this.async()](/api/loader-api/context.md#thisasync) method to get a `callback` function, informing Rspack that this loader requires async processing.

The `callback` of an async loader can also pass multiple parameters, including transformed content, source maps, and metadata:

```js title="async-loader.js"
module.exports = function (source, map, meta) {
  // Get the async callback function
  const callback = this.async();

  // Perform async operation
  someAsyncOperation(source, function (err, result) {
    // Handle error case
    if (err) return callback(err);

    // Return the processing result on success
    callback(null, result, map, meta);
  });
};
```

### ESM loader

Rspack supports ESM loaders, you can write loaders using ESM syntax and export the loader function using `export default`.

When writing ESM loaders, the file name needs to end with `.mjs`, or set `type` to `module` in the nearest `package.json`.

```js title="my-loader.mjs"
export default function loader(source, map, meta) {
  // ...
}
```

If you need to export options like [raw](#raw-loader) or [pitch](#pitching-loader), you can use named exports:

```js title="my-loader.mjs"
export default function loader(source) {
  // ...
}

// Set raw loader
export const raw = true;

// Add pitch function
export function pitch(remainingRequest, precedingRequest, data) {
  // ...
}
```

::: tip
ESM loader and CommonJS loader have the same functionality, but use different module syntax. You can choose the format based on your project needs.
:::

### Raw loader

By default, Rspack converts file content into UTF-8 strings before passing it to loaders for processing. However, when handling binary files (such as images, audio, or font files), we need to work directly with the raw binary data rather than string representations.

By exporting `raw: true` in the loader file, a loader can receive the original `Buffer` object as input instead of a string.

- CJS:

```js title="raw-loader.js"
module.exports = function (source) {
  // Process binary content
  // Here source is a Buffer instance
  const processed = someBufferOperation(source);

  // Return the processed result
  return processed;
};

// Mark as Raw Loader
module.exports.raw = true;
```

- ESM:

```js title="raw-loader.mjs"
export default function loader(source) {
  // ...
}

export const raw = true;
```

When multiple loaders are chained together, each loader can choose to receive and pass processing results as either strings or Buffers. Rspack automatically handles the conversion between Buffer and string between different loaders, ensuring data is correctly passed to the next loader.

Raw Loaders are particularly useful in scenarios involving image compression, binary resource transformation, file encoding, etc. For example, when developing a loader to process images, direct manipulation of binary data is typically required to properly handle image formats.

### Pitching loader

In Rspack's loader execution process, the default exported loader function is always called **from right to left** (called normal stage). However, sometimes a loader may only care about the request's metadata rather than the processing result of the previous loader. To address this need, Rspack provides a pitching stage — a special stage that each loader can define before its normal execution.

Contrary to normal execution, the `pitch` method exported in the loader file is called **from left to right**, before any loader's default function executes. This bidirectional processing mechanism provides developers with more flexible resource handling options.

For example, with the following configuration:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        use: ['a-loader', 'b-loader', 'c-loader'],
      },
    ],
  },
};
```

These steps would occur:

```
|- a-loader `pitch`
  |- b-loader `pitch`
    |- c-loader `pitch`
      |- requested module is picked up as a dependency
    |- c-loader normal execution
  |- b-loader normal execution
|- a-loader normal execution
```

Normally, if it the loader is simple enough which only exports the normal stage hook:

```js
module.exports = function (source) {};
```

Then, the pitching stage will be skipped.

So why might a loader take advantage of the pitching stage?

First, the data passed to the pitch method is exposed in the execution stage as well under this.data and could be useful for capturing and sharing information from earlier in the cycle.

```js
module.exports = function (source) {
  return someSyncOperation(source, this.data.value);
};

module.exports.pitch = function (remainingRequest, precedingRequest, data) {
  data.value = 42;
};
```

Second, if a loader delivers a result in the pitch method, the process turns around and skips the remaining loaders.
In our example above, if the b-loaders pitch method returned something:

```js
module.exports = function (source) {
  return someSyncOperation(source);
};

module.exports.pitch = function (remainingRequest, precedingRequest, data) {
  if (someCondition()) {
    return (
      'module.exports = require(' +
      JSON.stringify('-!' + remainingRequest) +
      ');'
    );
  }
};
```

The steps above would be shortened to:

```
|- a-loader `pitch`
  |- b-loader `pitch` returns a module
|- a-loader normal execution
```

For a real world example, `style-loader` leverages the second advantage to dispatch requests.
Please visit [style-loader](https://github.com/webpack/style-loader/blob/eb06baeb3ac4e3107732a21170b0a7f358c5423f/src/index.js#L39) for details.

## Write with TypeScript

If you write Rspack loader using TypeScript, you can use `LoaderDefinition` to provide complete type definitions for your loader.

```ts title="my-loader.ts"
import type { LoaderDefinition } from '@rspack/core';

// Declare the type of loader options
type MyLoaderOptions = {
  foo: string;
};

const myLoader: LoaderDefinition<MyLoaderOptions> = function (source) {
  const options = this.getOptions();
  console.log(options); // { foo: 'bar' }
  // Transform the source code
  return `// Processed by my-loader\n${source}`;
};

export default myLoader;
```

Alternatively, you can import `LoaderContext` to add types to the loader context:

```ts title="my-loader.ts"
import type { LoaderContext } from '@rspack/core';

type MyLoaderOptions = {
  foo: string;
};

export default function myLoader(
  this: LoaderContext<MyLoaderOptions>,
  source: string,
) {
  const options = this.getOptions();
  console.log(options); // { foo: 'bar' }
  return `// Processed by my-loader\n${source}`;
}
```

## Handling source maps

When developing loaders, properly handling source maps is essential for providing accurate debugging information.

Loader APIs related to source maps:

- Use [this.sourceMap](/api/loader-api/context.md#thissourcemap) to determine whether source map generation is required.
- Use [this.callback](/api/loader-api/context.md#thiscallback) or [this.async](/api/loader-api/context.md#thisasync) methods to return the processed source map.

### Automatic source map handling

Some transformers support automatic source map handling. For example, SWC can automatically generate new source maps based on input source maps.

Here's an example using Rspack's [SWC API](/api/javascript-api/swc.md):

```js title="myLoader.js"
import { rspack } from '@rspack/core';

const { swc } = rspack.experiments;

export default async function myLoader(source, inputSourceMap) {
  const callback = this.async();

  try {
    const result = await swc.transform(source, {
      inputSourceMap,
      sourceMaps: this.sourceMap,
      // ...other options
    });

    callback(null, result.code, this.sourceMap ? result.map : undefined);
  } catch (err) {
    callback(err);
  }
}
```

### Manual source map merging

You can also manually merge multiple source maps using third-party libraries such as [@jridgewell/remapping](https://www.npmjs.com/package/@jridgewell/remapping):

```js title="myLoader.js"
import remapping from '@jridgewell/remapping';

const mergeSourceMap = (inputSourceMap, newSourceMap) => {
  return remapping([newSourceMap, inputSourceMap], () => null);
};

export default async function myLoader(source, inputSourceMap) {
  const callback = this.async();

  try {
    const { code, sourceMap: newSourceMap } = await someTransformFunction(
      source,
      { sourceMap: this.sourceMap },
    );

    if (this.sourceMap) {
      const mergedSourceMap = inputSourceMap
        ? mergeSourceMap(inputSourceMap, newSourceMap)
        : newSourceMap;
      callback(null, code, mergedSourceMap);
    } else {
      callback(null, code);
    }
  } catch (err) {
    callback(err);
  }
}
```

## Publishing loaders

### Declaring peer dependencies

When publishing a loader as an npm package, declare the bundler packages it integrates with as optional peer dependencies. This documents the supported host bundlers without requiring users who only use one bundler to install the other.

If the loader is designed only for Rspack, declare `@rspack/core` as an optional peer dependency. Set the version range according to the APIs the loader relies on. For example, if the loader uses an API introduced in a newer Rspack release, set that release as the minimum supported version.

```json title="package.json"
{
  "peerDependencies": {
    "@rspack/core": "^1.0.0 || ^2.0.0"
  },
  "peerDependenciesMeta": {
    "@rspack/core": {
      "optional": true
    }
  }
}
```

If the loader is designed to work with both Rspack and webpack, declare both `@rspack/core` and `webpack` as optional peer dependencies:

```json title="package.json"
{
  "peerDependencies": {
    "@rspack/core": "^1.0.0 || ^2.0.0",
    "webpack": "^5.0.0"
  },
  "peerDependenciesMeta": {
    "@rspack/core": {
      "optional": true
    },
    "webpack": {
      "optional": true
    }
  }
}
```


This page is adapted from [webpack documentation](https://webpack.js.org/api/loaders/#examples) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /api/loader-api/context.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Loader context

The loader context represents the properties that are available inside of a loader assigned to the `this` property.

## this.addBuildDependency()

- **Type:**

```ts
function addBuildDependency(file: string): void;
```

Add a file as a build dependency of the loader result. Build dependencies are used to invalidate the persistent cache when they change.

Use this for files that affect a loader's behavior or transformation result, such as a loader configuration file.

```js title="loader.mjs"
import path from 'node:path';

export default function loader(source) {
  this.addBuildDependency(
    path.resolve(this.rootContext, 'custom-loader.config.js'),
  );
  return source;
}
```

:::tip
`this.addBuildDependency()` does not make the file a watch dependency. If changes to the file should trigger a rebuild in watch mode, also call [this.addDependency()](#thisadddependency).
:::

## this.addContextDependency()

- **Type:**

```ts
function addContextDependency(directory: string): void;
```

Add the directory as a dependency for the loader results so that any changes to the files in the directory can be listened to.

For example, adding `src/static` as a dependency. When the files in the `src/static` directory change, it will trigger a rebuild.

```js title="loader.mjs"
import path from 'node:path';

export default function loader(source) {
  this.addContextDependency(path.resolve(this.rootContext, 'src/static'));
  return source;
}
```

## this.addDependency()

- **Type:**

```ts
function addDependency(file: string): void;
```

Add a file as a dependency on the loader results so that any changes to them can be listened to. For example, `sass-loader`, `less-loader` use this trick to recompile when the imported style files change.

```js title="loader.mjs"
import path from 'node:path';

export default function loader(source) {
  this.addDependency(path.resolve(this.rootContext, 'src/styles/foo.scss'));
  return source;
}
```

## this.addMissingDependency()

- **Type:**

```ts
function addMissingDependency(file: string): void;
```

Add a currently non-existent file as a dependency of the loader result, so that its creation and any changes can be listened. For example, when a new file is created at that path, it will trigger a rebuild.

```js title="loader.mjs"
import path from 'node:path';

export default function loader(source) {
  this.addMissingDependency(
    path.resolve(this.rootContext, 'src/dynamic-file.json'),
  );
  return source;
}
```

## this.async()

- **Type:** `() => LoaderContextCallback`

Tells Rspack that this loader will be called asynchronously. Returns [this.callback](#thiscallback).

> See [Async loader](/api/loader-api/writing-loaders.md#async-loader) for more details.

## this.cacheable()

- **Type:**

```ts
function cacheable(flag: boolean = true): void;
```

By default, the final build result produced for the current module by the entire loader chain is cacheable. Calling `this.cacheable(false)` marks that result as non-cacheable.

Once a loader has called `this.cacheable(false)`, subsequent loaders cannot make the result cacheable again by calling `this.cacheable(true)` or `this.cacheable()`. Only [`this.clearDependencies()`](#thiscleardependencies) resets this state.

```js title="loader.mjs"
export default function loader(source) {
  this.cacheable(false);
  return source;
}
```

## this.callback()

- **Type:**

```ts
interface AdditionalData {
  [index: string]: any;
}

function callback(
  err?: Error | null,
  content?: string | Buffer,
  sourceMap?: string | Rspack.RawSourceMap,
  additionalData?: AdditionalData,
): void;
```

Call `this.callback()` to return a loader's results, either synchronously or asynchronously. Its arguments are:

1. `err`: An `Error` when the loader fails, or `null` or `undefined` when it succeeds.
2. `content`: The transformed module content as a `string` or `Buffer`. It can be omitted when reporting an error.
3. `sourceMap`: An optional source map as a `string` or `Rspack.RawSourceMap`.
4. `additionalData`: Optional additional data. Rspack passes it as the third argument to the next loader in the chain.

> See [Sync loader](/api/loader-api/writing-loaders.md#sync-loader) for more details.

:::warning
In case this function is called, you should return `undefined` to avoid ambiguous loader results.

The `content`, `sourceMap`, and `additionalData` values are passed to the next loader in the chain.
:::

## this.clearDependencies()

- **Type:**

```ts
function clearDependencies(): void;
```

Clears all [file dependencies](#thisadddependency), [context dependencies](#thisaddcontextdependency), and [missing dependencies](#thisaddmissingdependency) collected by the loader chain. [Build dependencies](#thisaddbuilddependency) are not cleared. This also resets [`cacheable`](#thiscacheable) to `true`, overriding any earlier call to `this.cacheable(false)`.

Only use this method when the current loader will register every dependency required by the final result.

## this.context

- **Type:** `string | null`

The directory path of the currently processed module, which changes with the location of each processed module.

For example, if the loader is processing `/project/src/components/Button.js`, then the value of `this.context` would be `/project/src/components`.

```js title="loader.mjs"
export default function loader(source) {
  console.log(this.context); // '/project/src/components'
  return source;
}
```

If the current module has no resource path, the value of `this.context` is `null`.

## this.loaderIndex

- **Type:** `number`

The index in the loaders array of the current loader.

## this.loaders

- **Type:** `LoaderObject[]`

`this.loaders` contains all loaders applied to the current module. Each item provides information such as the resolved `request`, `path`, `query`, and `options`.

During the pitch phase, you can modify the array to adjust the loader chain. Use [this.loaderIndex](#thisloaderindex) to locate the current loader.

```js title="loader.mjs"
export function pitch() {
  const currentLoader = this.loaders[this.loaderIndex];
  console.log(currentLoader.request);
}
```

## this.data

- **Type:** `unknown`

A data object shared between the pitch and the normal phase.

## this.dependency()

- **Type:**

```ts
function dependency(file: string): void;
```

Alias of [this.addDependency()](#thisadddependency).

## this.emitError()

- **Type:**

```ts
function emitError(error: Error): void;
```

Emit an error.

::: info
Unlike `throw` and `this.callback(err)` in the loader, it does not mark the current module as a compilation failure, it just adds an error to Rspack's Compilation and displays it on the command line at the end of this compilation.
:::

## this.emitWarning()

- **Type:**

```ts
function emitWarning(warning: Error): void;
```

Emit a warning.

## this.experiments.emitDiagnostic()


Stability: Experimental

- **Type:**

```ts
interface DiagnosticLocation {
  /** Text for highlighting the location */
  text?: string;
  /** 1-based line */
  line: number;
  /** 0-based column in bytes */
  column: number;
  /** Length in bytes */
  length: number;
}

interface Diagnostic {
  message: string;
  help?: string;
  sourceCode?: string;
  /**
   * Location to the source code.
   * If `sourceCode` is not provided, location will be omitted.
   */
  location?: DiagnosticLocation;
  /**
   * Optional filename to show.
   * If provided, it becomes the `StatsError.file` value in stats.
   */
  file?: string;
  severity: 'error' | 'warning';
}

function emitDiagnostic(diagnostic: Diagnostic): void;
```

Formats and emits an error or warning diagnostic. Supports the display of module paths, source code snippets, and line/column numbers.

::: info
Unlike `throw` and `this.callback(err)` in a loader, it does not mark the current module as a compilation failure. It adds an error or warning to Rspack's Compilation according to `severity`, then displays it on the command line at the end of the compilation.
:::

- Basic example:

When only `message` and `severity` are provided, only the basic diagnostic information will be printed.

```js title="loader.mjs"
/** @type {import("@rspack/core").LoaderDefinition} */
export default function () {
  this.experiments.emitDiagnostic({
    message: '`React` is not defined',
    severity: 'error',
  });
  this.experiments.emitDiagnostic({
    message: '`React` is not defined',
    severity: 'warning',
  });
  return '';
}
```

This will print:

```
ERROR in (./loader.mjs!)
  × ModuleError: `React` is not defined

WARNING in (./loader.mjs!)
  ⚠ ModuleWarning: `React` is not defined
```

- Printing code snippet:

```js title="loader.mjs"
/** @type {import("@rspack/core").LoaderDefinition} */
export default function () {
  this.experiments.emitDiagnostic({
    message: '`React` is not defined',
    severity: 'error',
    sourceCode: `<div></div>`,
    location: {
      line: 1,
      column: 1,
      length: 3,
    },
    file: './some-file.js',
  });
  return '';
}
```

This will print:

```
ERROR in ./some-file.js
 ./file.js 1:1-4
  × ModuleError: `React` is not defined
   ╭────
 1 │ <div></div>
   ·  ───
   ╰────
```

Here, `./some-file.js` is the value passed to the `file` field.

## this.emitFile()

- **Type:**

```ts
function emitFile(
  name: string,
  content: string | Buffer,
  sourceMap?: string,
  assetInfo?: AssetInfo,
): void;
```

Emit a new file. This method allows you to create new files during the loader execution.

- Basic example:

```js title="loader.mjs"
export default function loader(source) {
  // Emit a new file that will be output as `foo.js` in the output directory
  this.emitFile('foo.js', 'console.log("Hello, world!");');
  return source;
}
```

- Example with asset info:

```js title="loader.mjs"
export default function loader(source) {
  this.emitFile(
    'foo.js',
    'console.log("Hello, world!");',
    undefined, // no sourcemap
    {
      sourceFilename: this.resourcePath,
    },
  );

  return source;
}
```

## this.fs

- **Type:** `InputFileSystem`

Access to the `compilation` object's `inputFileSystem` property.

## this.getContextDependencies()

- **Type:**

```ts
function getContextDependencies(): string[];
```

Returns all directories the loader currently watches as context dependencies, including directories added with [this.addContextDependency()](#thisaddcontextdependency).

```js title="loader.mjs"
export default function loader(source) {
  const contextDependencies = this.getContextDependencies();
  console.log(contextDependencies);

  return source;
}
```

## this.getDependencies()

- **Type:**

```ts
function getDependencies(): string[];
```

Returns all files the loader currently watches as dependencies, including files added with [this.addDependency()](#thisadddependency) or [this.dependency()](#thisdependency).

```js title="loader.mjs"
export default function loader(source) {
  const dependencies = this.getDependencies();
  console.log(dependencies);

  return source;
}
```

## this.getMissingDependencies()

- **Type:**

```ts
function getMissingDependencies(): string[];
```

Returns all paths to files that the loader is watching but that do not exist yet, including paths added with [this.addMissingDependency()](#thisaddmissingdependency). Creating one of these files may trigger a rebuild.

```js title="loader.mjs"
export default function loader(source) {
  const missingDependencies = this.getMissingDependencies();
  console.log(missingDependencies);

  return source;
}
```

Each method returns a new array. Modifying the returned array does not change the dependencies registered by the loader. To remove dependencies from these three lists, use [this.clearDependencies()](#thiscleardependencies).

## this.getOptions()

- **Type:**

```ts
function getOptions(schema?: any): OptionsType;
```

Get the options passed in by the loader's user.

For example:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.txt$/,
        use: {
          loader: './my-loader.mjs',
          options: {
            foo: 'bar',
          },
        },
      },
    ],
  },
};
```

In `my-loader.mjs` get the options passed in:

```js title="my-loader.mjs"
export default function myLoader(source) {
  const options = this.getOptions();
  console.log(options); // { foo: 'bar' }
  return source;
}
```

:::tip
When a loader is configured with a query string such as `loader: './my-loader?s=foo+bar'`, `this.getOptions()` parses that string with Node.js `querystring.parse()`. That means a literal `+` is decoded as a space, so the result is `{ s: 'foo bar' }`.

If you need a literal plus sign, encode `+` as `%2B` or prefer an `options` object in the loader rule. Use [this.query](#thisquery) when you need the raw query string.
:::

In TypeScript, you can set the options type through the generic of `LoaderContext`.

```ts title="my-loader.ts"
import type { LoaderContext } from '@rspack/core';

type MyLoaderOptions = {
  foo: string;
};

export default function myLoader(
  this: LoaderContext<MyLoaderOptions>,
  source: string,
) {
  const options = this.getOptions();
  console.log(options); // { foo: 'bar' }
  return source;
}
```

:::tip
The parameter `schema` is optional and will not be used in Rspack.

To provide the best performance, Rspack does not perform the schema validation. If your loader requires schema validation, please call [schema-utils](https://github.com/webpack/schema-utils) or other schema validation libraries.
:::

## this.getResolve()

- **Type:**

```ts
type ResolveFunction = {
  (
    context: string,
    request: string,
    callback: (
      err: Error | null,
      result?: string | false,
      resolveRequest?: ResolveRequest,
    ) => void,
  ): void;
  (context: string, request: string): Promise<string | false | undefined>;
};

function getResolve(options?: ResolveOptions): ResolveFunction;
```

Creates a resolver like [`this.resolve()`](#thisresolve). Pass `options` to customize the resolver. If no options are provided, it uses the normal resolver without additional options.

The returned resolver supports both callback and Promise forms. When no callback is passed, it returns a Promise.

```js title="loader.mjs"
export default async function loader(source) {
  const resolve = this.getResolve({
    extensions: ['.js', '.json'],
  });
  const result = await resolve(this.context, './dependency');

  console.log(result);
  return source;
}
```

## this.hot

- **Type:** `boolean`

Whether HMR is enabled.

```js title="loader.mjs"
export default function (source) {
  console.log(this.hot); // true if HMR is enabled
  return source;
}
```

## this.importModule()

- **Type:**

```ts
interface ImportModuleOptions {
  /**
   * Specify a layer in which this module is placed/compiled
   */
  layer?: string;
  /**
   * The public path used for the built modules
   */
  publicPath?: PublicPath;
  /**
   * Target base uri
   */
  baseUri?: string;
}

// with callback
function importModule<T = any>(
  request: string,
  options: ImportModuleOptions | undefined,
  callback: (err?: null | Error, exports?: T) => any,
): void;
// without callback, return Promise
function importModule<T = any>(
  request: string,
  options?: ImportModuleOptions,
): Promise<T>;
```

Compile and execute a module at the build time. This is an alternative lightweight solution for the child compiler.

`importModule` will return a Promise if no callback is provided.

```js title="loader.mjs"
import path from 'node:path';

export default async function loader(source) {
  const modulePath = path.resolve(this.rootContext, 'some-module.ts');
  const moduleExports = await this.importModule(modulePath, {
    // optional options
  });

  const result = someProcessing(source, moduleExports);
  return result;
}
```

Or you can pass a callback to it.

```js title="loader.mjs"
import path from 'node:path';

export default function loader(source) {
  const callback = this.async();
  const modulePath = path.resolve(this.rootContext, 'some-module.ts');

  this.importModule(
    modulePath,
    // optional options
    undefined,
    (err, moduleExports) => {
      if (err) {
        return callback(err);
      }

      const result = someProcessing(source, moduleExports);
      callback(null, result);
    },
  );
}
```

## this.query

- **Type:** `string | OptionsType`

The value depends on the loader configuration:

- If the current loader was configured with an options object, `this.query` will point to that object.
- If the current loader has no options, but was invoked with a query string, this will be a string starting with `?`.

Unlike [this.getOptions()](#thisgetoptions), the query-string form is not parsed. For example, `loader: './my-loader?s=foo+bar'` gives `this.query === '?s=foo+bar'`.

## this.remainingRequest

- **Type:** `string`

`this.remainingRequest` consists of the loaders that follow the current loader in the chain and the current resource, joined with `!`.

For example, consider the following loader chain:

```text
/path/to/loader1.mjs!/path/to/loader2.mjs!/path/to/resource.js
```

When Rspack runs `loader1.mjs`, `this.remainingRequest` is:

```text
/path/to/loader2.mjs!/path/to/resource.js
```

You can use it to create an inline request without invoking the current loader again. See [Inline matchResource](/api/loader-api/inline-match-resource.md) for an example.

## this.currentRequest

- **Type:** `string`

`this.currentRequest` consists of the current loader, the loaders that follow it in the chain, and the current resource, joined with `!`.

For example, consider the following loader chain:

```text
/path/to/loader1.mjs!/path/to/loader2.mjs!/path/to/resource.js
```

When Rspack runs `loader2.mjs`, `this.currentRequest` is:

```text
/path/to/loader2.mjs!/path/to/resource.js
```

## this.previousRequest

- **Type:** `string`

`this.previousRequest` consists of the loaders that precede the current loader, joined with `!`. It does not include the current resource.

For example, consider the following loader chain:

```text
/path/to/loader1.mjs!/path/to/loader2.mjs!/path/to/resource.js
```

When Rspack runs `loader2.mjs`, `this.previousRequest` is:

```text
/path/to/loader1.mjs
```

## this.request

- **Type:** `string`

The complete request string, consisting of all loaders and the current resource joined with `!`.

For example, if a `resource.js` is processed by `loader1.mjs` and `loader2.mjs`, the value of `this.request` will be `/path/to/loader1.mjs!/path/to/loader2.mjs!/path/to/resource.js`.

## this.resolve()

- **Type:**

```ts
function resolve(
  context: string,
  request: string,
  callback: (
    err: Error | null,
    result?: string | false,
    resolveRequest?: ResolveRequest,
  ) => void,
): void;
```

Resolve a module specifier.

- `context` must be the absolute path to a directory. This directory is used as the starting location for resolving.
- `request` is the module specifier to be resolved.
- `callback` receives the error, the resolved path (or `false` when the request is ignored), and optional resolution details.

## this.mode

- **Type:** `Mode | undefined`

The value of the [`mode`](/config/mode.md) configuration.

The possible values are `'production'`, `'development'`, `'none'`, and `undefined`. If `mode` is not configured, `this.mode` is `undefined`, even though Rspack applies production-oriented defaults.

```js title="loader.mjs"
export default function loader(source) {
  console.log(this.mode); // 'production', 'development', 'none', or undefined
  return source;
}
```

## this.target

- **Type:** `Target | undefined`

By default, this is a simplified target value derived from the [`target`](/config/target.md) configuration. When possible, Rspack maps the target's capabilities to a value such as `'web'`, `'node'`, `'nwjs'`, or `'electron-main'`. Therefore, `this.target` is not necessarily identical to the original `target` configuration.

```js title="loader.mjs"
export default function loader(source) {
  console.log(this.target); // 'web' or other values
  return source;
}
```

## this.environment

- **Type:** `Environment`

Describes the capabilities supported by the target environment. By default, this is the effective value of [`output.environment`](/config/output.md#outputenvironment): Rspack infers the capabilities from [`target`](/config/target.md), then applies the explicit settings from `output.environment`.

A loader can use this information to choose syntax supported by the output environment.

```js title="loader.mjs"
export default function loader(source) {
  if (this.environment.optionalChaining) {
    console.log('Optional chaining is supported');
  }

  return source;
}
```

## this.utils

- **Type:**

```ts
type Utils = {
  absolutify: (context: string, request: string) => string;
  contextify: (context: string, request: string) => string;
  createHash: (algorithm?: string) => Hash;
};
```

Access to the following utilities.

- `absolutify`: Return a new request string using absolute paths when possible.
- `contextify`: Return a new request string avoiding absolute paths when possible.
- `createHash`: Return a new Hash object from provided hash function.

```js title="loader.mjs"
export default function (content) {
  this.utils.contextify(
    this.context,
    this.utils.absolutify(this.context, './index.js'),
  );

  this.utils.absolutify(this.context, this.resourcePath);

  const mainHash = this.utils.createHash(
    this._compilation.outputOptions.hashFunction,
  );
  mainHash.update(content);
  mainHash.digest('hex');

  return content;
}
```

## this.resource

- **Type:** `string`

The path string of the current module. For example `'/abc/resource.js?query#hash'`.

```js title="loader.mjs"
export default function loader(source) {
  console.log(this.resource); // '/abc/resource.js?query#hash'
  return source;
}
```

## this.resourcePath

- **Type:** `string`

The path string of the current module, excluding the query and fragment parameters. For example, the value is `'/abc/resource.js'` for `'/abc/resource.js?query#hash'`.

```js title="loader.mjs"
export default function loader(source) {
  console.log(this.resourcePath); // '/abc/resource.js'
  return source;
}
```

## this.resourceQuery

- **Type:** `string`

The query parameter for the path string of the current module. For example `'?query'` in `'/abc/resource.js?query#hash'`.

```js title="loader.mjs"
export default function loader(source) {
  console.log(this.resourceQuery); // '?query'
  return source;
}
```

## this.resourceFragment

- **Type:** `string`

The fragment parameter of the current module's path string. For example `'#hash'` in `'/abc/resource.js?query#hash'`.

```js title="loader.mjs"
export default function loader(source) {
  console.log(this.resourceFragment); // '#hash'
  return source;
}
```

## this.rootContext

- **Type:** `string`

The base path configured in Rspack config via [context](/config/context.md).

```js title="loader.mjs"
export default function loader(source) {
  console.log(this.rootContext); // /path/to/project
  return source;
}
```

## this.sourceMap

- **Type:** `boolean`

Tells if source map should be generated.

Since generating source maps can be an expensive task, you should check if source maps are actually requested.

See [Handling source maps](/api/loader-api/writing-loaders.md#handling-source-maps) for more details.

## this.getLogger()

- **Type:**

```ts
function getLogger(name?: string): Logger;
```

Get the logger of this compilation, through which messages can be logged.

## this.version

- **Type:** `number`

The version number of the loader API. Currently 2.

This is useful for providing backwards compatibility. Using the version you can specify custom logic or fallbacks for breaking changes.

## Internal properties

:::warning
Please note that using internal Rspack properties like `this._compiler` and `this._compilation` will cause your loader to lose its independence.

Ideally, loaders should focus on file transformation logic, with deterministic output for given input, without depending on Rspack's internal state. Relying on these internal objects introduces unpredictable behavior, making testing and maintenance more difficult.

Therefore, it's recommended to consider using these properties only when there are no other alternatives.
:::

### this.\_compiler

- **Type:** `Compiler`

Access to the current [Compiler](/api/javascript-api/compiler.md) object of Rspack.

### this.\_compilation

- **Type:** `Compilation`

Access to the current [Compilation](/api/javascript-api/compilation.md) object of Rspack.


This page is adapted from [webpack documentation](https://webpack.js.org/api/loaders/#the-loader-context) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /api/loader-api/inline.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Inline loaders

It's possible to specify loaders in an `import` statement, or any equivalent "importing" method. Separate loaders from the resource with `!`. Each part is resolved relative to the current directory.

```js
import Styles from 'style-loader!css-loader?modules!./styles.css';
```

It's possible to override any loaders, preLoaders and postLoaders from the configuration by prefixing the inline `import` statement:

- Prefixing with `!` will disable all configured normal loaders

  ```js
  import Styles from '!style-loader!css-loader?modules!./styles.css';
  ```

- Prefixing with `!!` will disable all configured loaders (preLoaders, loaders, postLoaders)

  ```js
  import Styles from '!!style-loader!css-loader?modules!./styles.css';
  ```

- Prefixing with `-!` will disable all configured preLoaders and loaders but not postLoaders

  ```js
  import Styles from '-!style-loader!css-loader?modules!./styles.css';
  ```

Options can be passed with a query parameter, e.g. `?key=value&foo=bar`, or a JSON object, e.g. `?{"key":"value","foo":"bar"}`.


This page is adapted from [webpack documentation](https://webpack.js.org/concepts/loaders/#inline) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /api/loader-api/inline-match-resource.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Inline matchResource

Inline matchResource allows you to dynamically change the matching rules when loading resources. You can set the `matchResource` for a module specifier by prefixing `<match-resource>!=!` to the module specifier.

When a `matchResource` is set, it will be used to match with the `module.rules` instead of the original resource. This can be useful if further loaders should be applied to the resource, or if the module type needs to be changed.

:::tip
It is not recommended to use this syntax in source code. Inline request syntax is intended to only be used by loader generated code. Not following this recommendation will make your code Rspack-specific and non-standard.
:::

## Example

```js title="file.js"
/* STYLE: body { background: red; } */
console.log('yep');
```

A loader could transform the file into the following file and use the `matchResource` to apply the user-specified CSS processing rules:

```js title="file.js (transformed by loader)"
import './file.js.css!=!extract-style-loader/getStyles!./file.js';
console.log('yep');
```

This will add a dependency to `extract-style-loader/getStyles!./file.js` and treat the result as `file.js.css`.
Because `module.rules` has a rule matching `/\.css$/` and it will apply to this dependency.

The loader could look like this:

```js title="extract-style-loader/index.js"
const getStylesLoader = require.resolve('./getStyles');

module.exports = function (source) {
  if (STYLES_REGEXP.test(source)) {
    source = source.replace(STYLES_REGEXP, '');
    return `import ${JSON.stringify(
      this.utils.contextify(
        this.context || this.rootContext,
        `${this.resource}.css!=!${getStylesLoader}!${this.remainingRequest}`,
      ),
    )};${source}`;
  }
  return source;
};
```

```js title="extract-style-loader/getStyles.js"
module.exports = function (source) {
  const match = source.match(STYLES_REGEXP);
  return match[0];
};
```


This page is adapted from [webpack documentation](https://webpack.js.org/api/loaders/#inline-matchresource) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), with modifications.




---
url: /api/plugin-api/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Overview

## Plugin hooks

Rspack plugin hooks are similar to the webpack plugin, mainly including the following categories:

- [Compiler hooks](/api/plugin-api/compiler-hooks.md): Intervene at various stages of the entire build process
- [Compilation hooks](/api/plugin-api/compilation-hooks.md): Intervene at various stages of a single build
- [RuntimePlugin hooks](/api/plugin-api/runtime-plugin-hooks.md): Intervene in the generation of runtime code
- [ExternalModule hooks](/api/plugin-api/external-module-hooks.md): Control how external modules are assigned to chunks
- [NormalModuleFactory hooks](/api/plugin-api/normal-module-factory-hooks.md): Intervene at various stages of the module creation process
- [Stats hooks](/api/plugin-api/stats-hooks.md): Intervene in the generation of stats

## Compatibility status

Rspack is committed to being compatible with the plugins within the webpack ecosystem. We ensure that Rspack is as compatible as possible with the webpack plugin API, allowing more existing webpack plugins to be directly used in Rspack.

We have already made most of the webpack plugin APIs compatible. You can visit [this page](https://github.com/orgs/web-infra-dev/projects/9) to learn about the current compatibility status of webpack plugin APIs.

## Writing plugins compatible with Rspack and webpack

In most cases, you don't need to do any extra work to make a webpack plugin run correctly in Rspack. However, you should avoid directly importing classes or methods from the webpack package. Instead, retrieve these classes or methods from the `compiler` object within your plugin.

```js
export class Plugin {
  apply(compiler) {
    const {
      DefinePlugin, // Retrieve plugin
      NormalModule,
      sources: { RawSource }, // Retrieve class
    } = compiler.webpack;
  }
}
```

Although Rspack strives to be compatible with webpack's plugin API, you may still encounter some subtle differences between Rspack and webpack's plugin APIs. To determine whether your plugin is running in webpack or Rspack, you can check the `compiler.rspack` property:

```js
export class Plugin {
  apply(compiler) {
    if (compiler.rspack) {
      // Logic for running in Rspack
    } else {
      // Logic for running in webpack
    }
  }
}
```



---
url: /api/plugin-api/compiler-hooks.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Compiler hooks

Compiler hooks allow Rspack plugins to intervene at specific stages of the build process. These hooks represent various lifecycle stages from initialization to asset output.

This document lists the available compiler hooks in Rspack, their trigger timing, parameters, and usage examples.

:::tip
See [Compiler](/api/javascript-api/compiler.md) for more information about the Compiler object.
:::

## Overview


## `environment`

Called while preparing the compiler environment, right after initializing the plugins in the configuration file.

- **Type:** `SyncHook<[]>`

## `afterEnvironment`

Called right after the `environment` hook, when the compiler environment setup is complete.

- **Type:** `SyncHook<[]>`

## `entryOption`

Called after the [`entry`](/config/entry.md) configuration from Rspack options has been processed.

- **Type:** `SyncBailHook<[string, EntryNormalized]>`
- **Arguments:**
  - `string`: same with [`context`](/config/context.md)
  - `EntryNormalized`: normalized [`entry`](/config/entry.md)

## `afterPlugins`

Called after setting up initial set of internal plugins.

- **Type:** `SyncHook<[Compiler]>`
- **Arguments:**
  - `Compiler`: current compiler instance


Compiler.ts

## `afterResolvers`

Triggered after resolver setup is complete.

- **Type:** `SyncHook<[Compiler]>`
- **Arguments:**
  - `Compiler`: current compiler instance


Compiler.ts

## `initialize`

Called when a compiler object is initialized.

- **Type:** `SyncHook<[]>`

## `beforeRun`

Adds a hook right before running the compiler.

:::note

This hook is only triggered when calling [compiler.run()](/api/javascript-api/index.md#compilerrun) (which is used by the `rspack build` command), and will not be executed in watch mode. You can use the [watchRun](#watchrun) hook in watch mode.

:::

- **Type:** `AsyncSeriesHook<[Compiler]>`
- **Arguments:**
  - `Compiler`: current compiler instance


Compiler.ts

- **Example:** Sync operation

```js
class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.beforeRun.tap('ExamplePlugin', (compiler) => {
      console.log('Build is about to start...');
    });
  }
}
```

- **Example:** Async operation

```js
class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.beforeRun.tapPromise(
      'ExamplePlugin',
      (compiler) => {
        console.log('Build is about to start...');

        await someAsyncOperation();
      },
    );
  }
}
```

## `run`

Called at the beginning of a build execution.

:::note

This hook is only triggered when calling [compiler.run()](/api/javascript-api/index.md#compilerrun) (which is used by the `rspack build` command), and will not be executed in watch mode. You can use the [watchRun](#watchrun) hook in watch mode.

:::

- **Type:** `AsyncSeriesHook<[Compiler]>`
- **Arguments:**
  - `Compiler`: current compiler instance


Compiler.ts

- **Example:** Sync operation

```js
class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.beforeRun.tap('ExamplePlugin', (compiler) => {
      console.log('Build start...');
    });
  }
}
```

- **Example:** Async operation

```js
class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.beforeRun.tapPromise(
      'ExamplePlugin',
      (compiler) => {
        console.log('Build start...');

        await someAsyncOperation();
      },
    );
  }
}
```

## `watchRun`

Executes a plugin during watch mode after a new compilation is triggered but before the compilation is actually started.

You can use `compiler.modifiedFiles` and `compiler.removedFiles` to get the changed file paths and removed file paths.

:::note

This hook is only triggered when calling [compiler.watch()](/api/javascript-api/index.md#compilerwatch), and will not be called in non-watch mode. You can use the [run](#run) or [beforeRun](#beforerun) hook in non-watch mode.

:::

- **Type:** `AsyncSeriesHook<[Compiler]>`
- **Arguments:**
  - `Compiler`: current compiler instance


Compiler.ts

- **Example:** Sync operation

```js
class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.watchRun.tap('ExamplePlugin', (compiler) => {
      const { modifiedFiles, removedFiles } = compiler;
      if (modifiedFiles) {
        console.log('Changed files:', Array.from(modifiedFiles));
      }
      if (removedFiles) {
        console.log('Removed files:', Array.from(removedFiles));
      }
    });
  }
}
```

- **Example:** Async operation

```js
class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.watchRun.tapPromise('ExamplePlugin', compiler => {
      await someAsyncOperation();
    });
  }
}
```

## `beforeCompile`

Executes a plugin after compilation parameters are created.

- **Type:** `AsyncSeriesHook<[]>`

## `compile`

Called right after `beforeCompile`, before a new [compilation object](/api/javascript-api/compilation.md) is created.

- **Type:** `SyncHook<[]>`

## `thisCompilation`

Called while initializing the compilation, can be used to get the current compilation object.

You can use the `compilation` parameter to access the properties of the compilation object, or register [compilation hooks](/api/plugin-api/compilation-hooks.md).

- **Type:** `SyncHook<[Compilation]>`
- **Arguments:**
  - `compilation`: created [compilation](/api/javascript-api/compilation.md) object


Compilation.ts

- **Example:**

```js
class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.thisCompilation.tap('ExamplePlugin', (compilation) => {
      console.log('compilation created:', compilation);

      compilation.hooks.make.tap('ExamplePlugin', (compilation) => {
        console.log("compilation's make hook called:", compilation);
      });
    });
  }
}
```

## `compilation`

Called after the compilation object is created, can be used to get the current compilation object.

You can use the `compilation` parameter to access the properties of the compilation object, or register [compilation hooks](/api/plugin-api/compilation-hooks.md).

`compilation` hook is called after the [thisCompilation](#thiscompilation) hook, and `thisCompilation` hook is not copied to child compiler, while `compilation` hook is copied to child compiler.

- **Type:** `SyncHook<[Compilation]>`
- **Arguments:**
  - `compilation`: created [compilation](/api/javascript-api/compilation.md) object


Compilation.ts

```js
class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap('ExamplePlugin', (compilation) => {
      console.log('compilation created:', compilation);

      compilation.hooks.make.tap('ExamplePlugin', (compilation) => {
        console.log("compilation's make hook called:", compilation);
      });
    });
  }
}
```

## `make`

Called before the make phase.

In the make phase, Rspack will build the module graph starting from the entry, and use the loader to handle each module.

- **Type:** `AsyncParallelHook<[Compilation]>`
- **Arguments:**
  - `Compilation`: current [compilation](/api/javascript-api/compilation.md) object


Compilation.ts

## `finishMake`

Called after finishing the make phase.

In the make phase, Rspack builds the module graph starting from the entry and uses loaders to handle each module. This hook is called when that process completes.

- **Type:** `AsyncSeriesHook<[Compilation]>`
- **Arguments:**
  - `Compilation`: current [compilation](/api/javascript-api/compilation.md) object


Compilation.ts

## `afterCompile`

Called after the compilation has been finished and sealed, and before Rspack
decides whether to emit the assets ([`shouldEmit`](#shouldemit)).

At this point the assets have been generated and are available on
`compilation.assets`, but nothing has been written to the output directory yet,
so a plugin can still fail the build here without leaving stale files behind.

- **Type:** `AsyncSeriesHook<[Compilation]>`
- **Arguments:**
  - `Compilation`: current [compilation](/api/javascript-api/compilation.md) object


Compilation.ts

## `shouldEmit`

Called before emitting assets. Should return a boolean telling whether to emit.

- **Type:** `SyncBailHook<[Compilation], boolean>`
- **Arguments:**
  - `Compilation`: current [compilation](/api/javascript-api/compilation.md) object


Compilation.ts

- **Example:**

```js
compiler.hooks.shouldEmit.tap('MyPlugin', (compilation) => {
  // return true to emit the output, otherwise false
  return true;
});
```

## `emit`

Called right before emitting assets to output dir.

- **Type:** `AsyncSeriesHook<[Compilation]>`
- **Arguments:**
  - `Compilation`: current [compilation](/api/javascript-api/compilation.md) object


Compilation.ts

## `afterEmit`

Called after emitting assets to output directory.

- **Type:** `AsyncSeriesHook<[Compilation]>`
- **Arguments:**
  - `Compilation`: current [compilation](/api/javascript-api/compilation.md) object


Compilation.ts

## `done`

Called when the compilation has completed.

- **Type:** `AsyncSeriesHook<Stats>`
- **Arguments:**
  - `Stats`: generated stats object


Stats.ts

## `afterDone`

Called after `done` hook.

- **Type:** `SyncHook<Stats>`
- **Arguments:**
  - `Stats`: generated stats object


Stats.ts

## `failed`

Called if the compilation fails.

- **Type:** `SyncHook<[Error]>`

## `invalid`

Executed when a watching compilation has been invalidated. This hook is not copied to child compilers.

- **Type:** `SyncHook<[string | null, number]>`
- **Arguments:**
  - `fileName`: the file path of the invalid file
  - `changeTime`: the change time of the invalid file

When triggering a re-compilation, this hook can be used to get the changed file path and change time, for example:

```ts
compiler.hooks.invalid.tap('MyPlugin', (fileName, changeTime) => {
  console.log(`Changed file: ${fileName}, change time: ${changeTime}`);
});
```

## `watchClose`

Called when a watching compilation has stopped.

- **Type:** `SyncHook<[]>`

## `shutdown`

Called when the compiler is closing.

- **Type:** `AsyncSeriesHook<[]>`

## infrastructureLog

Called when infrastructure logging is triggered, allowing plugins to intercept, modify, or handle log messages.

This hook provides a way to customize Rspack's infrastructure logs - you can filter specific log types, add custom formatting, or completely override the default logging behavior.

If the hook returns `true`, the default infrastructure logging will be prevented. If it returns `undefined`, the default logging will proceed.

- **Type:** `SyncBailHook<[string, string, any[]], true | void>`
- **Arguments:**
  - `name`: The name of the logger
  - `type`: The log type (e.g., 'log', 'warn', 'error', ...)
  - `args`: An array of arguments passed to the logging method
- **Example:**

```js
class ExamplePlugin {
  apply(compiler) {
    compiler.hooks.infrastructureLog.tap('MyPlugin', (name, type, args) => {
      // Custom logging logic
      if (type === 'error') {
        console.error(`[${name}] ERROR:`, ...args);
        return true; // Prevent default logging
      }

      // Let other log types use default behavior
      return undefined;
    });
  }
}
```

> See [infrastructureLogging](/config/infrastructure-logging.md) to learn more about infrastructure logging.



---
url: /api/plugin-api/compilation-hooks.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Compilation hooks

Compilation hooks are the primary extension method for Rspack plugins. These hooks enable developers to intervene at various stages of the build process.

This document lists the available Compilation hooks in Rspack, detailing their triggering timing, parameters, and usage examples.

:::tip
See the [Compilation](/api/javascript-api/compilation.md) for more information about the Compilation object.
:::

:::info
The main compilation logic of Rspack runs on the Rust side. For factors such as stability, performance, and architecture, after the Rust side compilation objects are transferred to the JavaScript side when using hooks, the modifications on these objects will not be synchronized to the Rust side. Therefore, most of hooks are "read-only".
:::

## Overview


## `buildModule`

Read-only
Triggered before a module build has started.

- **Type:** `SyncHook<[Module]>`
- **Arguments:**
  - `Module`: module instance


Module.ts

## `executeModule`

Read-only
If there exists compiled-time execution modules, this hook will be called when they are executed.

- **Type:** `SyncHook<[ExecuteModuleArgument, ExecuteModuleContext]>`
- **Arguments:**
  - `ExecuteModuleArgument`: arguments of compiled-time execution module
  - `ExecuteModuleContext`: context of compiled-time execution module


ExecuteModuleArgument.ts

ExecuteModuleContext.ts

## `succeedModule`

Read-only
Executed when a module has been built successfully.

- **Type:** `SyncHook<[Module]>`
- **Arguments:**
  - `Module`: module instance


Module.ts

## `finishModules`

Read-only
Called when all modules have been built without errors.

- **Type:** `AsyncSeriesHook<[Iterable<Module>]>`
- **Arguments:**
  - `Iterable<Module>`: iterable of module instances


Module.ts

## `seal`

Called when the compilation stops accepting new modules and starts to optimize modules.

- **Type:** `SyncHook<[]>`

## `optimizeModules`

Read-only
Called at the beginning of the module optimization phase.

- **Type:** `SyncBailHook<[Iterable<Module>]>`
- **Arguments:**
  - `Iterable<Module>`: iterable of module instances


Module.ts

## `afterOptimizeModules`

Read-only
Called after modules optimization has completed.

- **Type:** `SyncHook<[Iterable<Module>]>`
- **Arguments:**
  - `Iterable<Module>`: iterable of module instances


Module.ts

## `optimizeTree`

Read-only
Called before optimizing the dependency tree.

- **Type:** `AsyncSeriesHook<[Iterable<Chunk>, Iterable<Module>]>`
- **Arguments:**
  - `Iterable<Chunk>`: iterable of chunk instances
  - `Iterable<Module>`: iterable of module instances


Chunk.ts

Module.ts

## `optimizeChunkModules`

Read-only
Called after the tree optimization, at the beginning of the chunk modules optimization.

- **Type:** `AsyncSeriesBailHook<[Iterable<Chunk>, Iterable<Module>]>`
- **Arguments:**
  - `Iterable<Chunk>`: iterable of chunk instances
  - `Iterable<Module>`: iterable of module instances


Chunk.ts

Module.ts

## `additionalTreeRuntimeRequirements`

Called after the tree runtime requirements collection.

- **Type:** `SyncHook<[Chunk, Set<RuntimeGlobals>]>`
- **Arguments:**
  - `Chunk`: chunk instance
  - `Set<RuntimeGlobals>`: runtime requirements

Additional builtin runtime modules can be added here by modifying the runtime requirements set.

```js title="rspack.config.mjs"
export default {
  entry: './index.js',
  plugins: [
    {
      apply(compiler) {
        const { RuntimeGlobals } = compiler.rspack;
        compiler.hooks.thisCompilation.tap('CustomPlugin', (compilation) => {
          compilation.hooks.additionalTreeRuntimeRequirements.tap(
            'CustomPlugin',
            (_, set) => {
              // add a runtime module which define `__webpack_require__.h`
              set.add(RuntimeGlobals.getFullHash);
            },
          );
        });
      },
    },
  ],
};
```

```js title="index.js"
// will print hash of this compilation
console.log(__webpack_require__.h);
```

## `runtimeRequirementInTree`

Called during adding runtime modules to the compilation.

- **Type:** `HookMap<SyncBailHook<[Chunk, Set<RuntimeGlobals>]>>`
- **Arguments:**
  - `Chunk`: chunk instance
  - `Set<RuntimeGlobals>`: runtime requirements

Additional builtin runtime modules can be added here by modifying the runtime requirements set or calling [`compilation.addRuntimeModule`](/api/javascript-api/compilation.md#addruntimemodule) to add custom runtime modules.

```js title="rspack.config.mjs"
export default {
  entry: './index.js',
  plugins: [
    {
      apply(compiler) {
        const { RuntimeGlobals, RuntimeModule } = compiler.rspack;
        class CustomRuntimeModule extends RuntimeModule {
          constructor() {
            super('custom');
          }

          generate() {
            const compilation = this.compilation;
            return `
            __webpack_require__.mock = function(file) {
              return ${RuntimeGlobals.publicPath} + "/subpath/" + file;
            };
          `;
          }
        }

        compiler.hooks.thisCompilation.tap('CustomPlugin', (compilation) => {
          compilation.hooks.runtimeRequirementInTree
            .for(RuntimeGlobals.ensureChunkHandlers)
            .tap('CustomPlugin', (chunk, set) => {
              // add a runtime module to access public path
              set.add(RuntimeGlobals.publicPath);
              compilation.addRuntimeModule(chunk, new CustomRuntimeModule());
            });
        });
      },
    },
  ],
};
```

```js title="index.js"
// will print "/subpath/index.js"
console.log(__webpack_require__.mock('index.js'));
```

## `runtimeModule`

Called after a runtime module is added into the compilation.

- **Type:** `SyncHook<[RuntimeModule, Chunk]>`
- **Arguments:**
  - `RuntimeModule`: runtime module instance
  - `Chunk`: chunk instance

Generated code of this runtime module can be modified through its `source` property.

```js title="rspack.config.mjs"
export default {
  plugins: [
    {
      apply(compiler) {
        const { RuntimeGlobals } = compiler.rspack;
        compiler.hooks.compilation.tap('CustomPlugin', (compilation) => {
          compilation.hooks.runtimeModule.tap(
            'CustomPlugin',
            (module, chunk) => {
              if (module.name === 'public_path' && chunk.name === 'main') {
                const originSource = module.source.source.toString('utf-8');
                module.source.source = Buffer.from(
                  `${RuntimeGlobals.publicPath} = "/override/public/path";\n`,
                  'utf-8',
                );
              }
            },
          );
        });
      },
    },
  ],
};
```

```js title="index.js"
// will print "/override/public/path"
console.log(__webpack_require__.p);
```


RuntimeModule.ts

## `processAssets`

Process the assets before emit.

- **Type:** `AsyncSeriesHook<Assets>`
- **Hook parameters:**
  - `name: string` — a name of the plugin
  - `stage: Stage` — a stage to tap into (see the [process assets stages](#process-assets-stages) below)
- **Arguments:**
  - `Assets: Record<string, Source>`: a plain 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).


Source.ts

### Process assets examples

- Emit a new asset in the `PROCESS_ASSETS_STAGE_ADDITIONAL` stage:

```js
compiler.hooks.thisCompilation.tap('MyPlugin', (compilation) => {
  const { Compilation } = compiler.rspack;
  compilation.hooks.processAssets.tap(
    {
      name: 'MyPlugin',
      stage: Compilation.PROCESS_ASSETS_STAGE_ADDITIONAL,
    },
    (assets) => {
      const { RawSource } = compiler.rspack.sources;
      const source = new RawSource('This is a new asset!');
      compilation.emitAsset('new-asset.txt', source);
    },
  );
});
```

- Updating an existing asset:

```js
compiler.hooks.thisCompilation.tap('MyPlugin', (compilation) => {
  const { Compilation } = compiler.rspack;
  compilation.hooks.processAssets.tap(
    {
      name: 'MyPlugin',
      stage: Compilation.PROCESS_ASSETS_STAGE_ADDITIONS,
    },
    (assets) => {
      const asset = assets['foo.js'];
      if (!asset) {
        return;
      }

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

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

- Removing an asset:

```js
compiler.hooks.thisCompilation.tap('MyPlugin', (compilation) => {
  const { Compilation } = compiler.rspack;
  compilation.hooks.processAssets.tap(
    {
      name: 'MyPlugin',
      stage: Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE,
    },
    (assets) => {
      const assetName = 'unwanted-script.js';
      if (assets[assetName]) {
        compilation.deleteAsset(assetName);
      }
    },
  );
});
```

### 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.

- `PROCESS_ASSETS_STAGE_ADDITIONAL` — add additional assets to the compilation.
- `PROCESS_ASSETS_STAGE_PRE_PROCESS` — basic preprocessing of the assets.
- `PROCESS_ASSETS_STAGE_DERIVED` — derive new assets from the existing assets.
- `PROCESS_ASSETS_STAGE_ADDITIONS` — add additional sections to the existing assets e.g. banner or initialization code.
- `PROCESS_ASSETS_STAGE_OPTIMIZE` — optimize existing assets in a general way.
- `PROCESS_ASSETS_STAGE_OPTIMIZE_COUNT` — optimize the count of existing assets, e.g. by merging them.
- `PROCESS_ASSETS_STAGE_OPTIMIZE_COMPATIBILITY` — optimize the compatibility of existing assets, e.g. add polyfills or vendor prefixes.
- `PROCESS_ASSETS_STAGE_OPTIMIZE_SIZE` — optimize the size of existing assets, e.g. by minimizing or omitting whitespace.
- `PROCESS_ASSETS_STAGE_DEV_TOOLING` — add development tooling to the assets, e.g. by extracting a source map.
- `PROCESS_ASSETS_STAGE_OPTIMIZE_INLINE` — optimize the numbers of existing assets by inlining assets into other assets.
- `PROCESS_ASSETS_STAGE_SUMMARIZE` — summarize the list of existing assets.
- `PROCESS_ASSETS_STAGE_OPTIMIZE_HASH` — optimize the hashes of the assets, e.g. by generating real hashes of the asset content.
- `PROCESS_ASSETS_STAGE_OPTIMIZE_TRANSFER` — optimize the transfer of existing assets, e.g. by preparing a compressed (gzip) file as separate asset.
- `PROCESS_ASSETS_STAGE_ANALYSE` — analyze the existing assets.
- `PROCESS_ASSETS_STAGE_REPORT` — creating assets for the reporting purposes.

## `afterProcessAssets`

Read-only
Called after the [processAssets](#processassets) hook had finished without error.

- **Type:** `SyncHook<Assets>`
- **Arguments:**
  - `Assets: Record<string, Source>`: list of asset instances


Source.ts

- **Example:**

```js
compilation.hooks.afterProcessAssets.tap('MyPlugin', (assets) => {
  console.log('assets', Object.keys(assets));
});
```

## `afterSeal`

Read-only
Called after the seal phase.

- **Type:** `AsyncSeriesHook<[]>`

## `chunkHash`

Read-only
Triggered to emit the hash for each chunk.

- **Type:** `SyncHook<[Chunk, Hash]>`
- **Arguments:**
  - `Chunk`: chunk instance
  - `Hash`: chunk hash instance


Chunk.ts

Hash.ts

## `chunkAsset`

Read-only
Triggered when an asset from a chunk was added to the compilation.

- **Type:** `SyncHook<[Chunk, string]>`
- **Arguments:**
  - `Chunk`: chunk instance
  - `string`: asset filename


Chunk.ts

## `childCompiler`

Read-only
Executed after setting up a child compiler.

- **Type:** `SyncHook<[Compiler, string, number]>`
- **Arguments:**
  - `Compiler`: child compiler instance
  - `string`: child compiler name
  - `number`: child compiler index


Compiler.ts

## `statsPreset`

Read-only
This hook is like a list of actions that gets triggered when a preset is used. It takes in an options object. When a plugin manages a preset, it should change settings in this object carefully without replacing existing ones.

- **Type:** `SyncHook<[Partial<StatsOptions>, CreateStatsOptionsContext]>`
- **Arguments:**
  - `Partial<StatsOptions>`: stats options
  - `CreateStatsOptionsContext`: stats context

Here's an illustrative plugin example:

```js
compilation.hooks.statsPreset.for('my-preset').tap('MyPlugin', (options) => {
  if (options.all === undefined) options.all = true;
});
```

This plugin ensures that for the preset `"my-preset"`, if the `all` option is undefined, it defaults to `true`.


StatsOptions.ts

CreateStatsOptionsContext.ts

## `statsNormalize`

Read-only
This hook is used to transform an options object into a consistent format that can be easily used by subsequent hooks. It also ensures that missing options are set to their default values.

- **Type:** `SyncHook<[Partial<StatsOptions>, CreateStatsOptionsContext]>`
- **Arguments:**
  - `Partial<StatsOptions>`: stats options
  - `CreateStatsOptionsContext`: stats context

Here's an illustrative plugin example:

```js
compilation.hooks.statsNormalize.tap('MyPlugin', (options) => {
  if (options.myOption === undefined) options.myOption = [];

  if (!Array.isArray(options.myOption)) options.myOptions = [options.myOptions];
});
```

In this plugin, if the `myOption` is missing, it sets it to `[]`. Additionally, it ensures that `myOption` is always an array even if it was originally defined as a single value.


StatsOptions.ts

CreateStatsOptionsContext.ts

## `statsFactory`

Read-only
This hook provides access to the StatsFactory class for specific options.

- **Type:** `SyncHook<[StatsFactory, StatsOptions]>`
- **Arguments:**
  - `StatsFactory`: stats factory instance, see [Stats Factory Hooks](/api/plugin-api/stats-hooks.md#statsfactory) for more details
  - `StatsOptions`: stats options


StatsFactory.ts

StatsOptions.ts

## `statsPrinter`

Read-only
This hook provides access to the StatsPrinter class for specific options.

- **Type:** `SyncHook<[StatsPrinter, StatsOptions]>`
- **Arguments:**
  - `StatsPrinter`: stats printer instance, see [Stats Printer Hooks](/api/plugin-api/stats-hooks.md#statsprinter) for more details.
  - `StatsOptions`: stats options


StatsPrinter.ts

StatsOptions.ts


---
url: /api/plugin-api/normal-module-factory-hooks.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# NormalModuleFactory

`NormalModuleFactory` is used by the [Compiler](/api/javascript-api/compiler.md) to generate modules (`NormalModule`). Starting from each entry module (`entry`), it resolves the dependency requests of the modules to obtain the final paths of the dependencies. Based on these final paths, it creates `NormalModule` instances. It then further resolves the dependency requests of the newly created modules. This process is recursive, creating each module as a `NormalModule` through `NormalModuleFactory`.

`NormalModuleFactory` provides the following lifecycle hooks. These can be used just like `Compiler` hooks:

```js
NormalModuleFactory.hooks.someHook.tap(/* ... */);
```

All hooks inherit from `Tapable`. In addition to `tap()`, you can also use `tapAsync()` and `tapPromise()`, depending on the type of the hook.

## Import attributes


[Added in v2.2.3](https://github.com/web-infra-dev/rspack/releases/tag/v2.2.3)

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

`ResolveData.attributes` holds the [import attributes](https://github.com/tc39/proposal-import-attributes) of the dependency that triggered the resolution, for example `{ type: 'json' }` for `import data from './data.json' with { type: 'json' }`. It is available on the [`beforeResolve`](#beforeresolve), [`factorize`](#factorize), [`resolve`](#resolve) and [`afterResolve`](#afterresolve) hooks, and is `undefined` when the request carries no attributes.

```js
compiler.hooks.compilation.tap(
  'MyPlugin',
  (compilation, { normalModuleFactory }) => {
    normalModuleFactory.hooks.beforeResolve.tap('MyPlugin', (resolveData) => {
      if (resolveData.attributes?.type === 'json') {
        // ...
      }
    });
  },
);
```

## `beforeResolve`

`AsyncSeriesBailHook<[ResolveData]>`

Called when a new dependency request is encountered. A dependency can be ignored by returning `false`. Otherwise, it should return `undefined` to proceed.

The `beforeResolve` hook is called at the very beginning of the module resolution process, allowing the module's request information to be intercepted and modified before the resolution takes place. This hook can be used to pre-process, filter or block the resolution of certain modules.

```js
compiler.hooks.compilation.tap(
  'MyPlugin',
  (compilation, { normalModuleFactory }) => {
    normalModuleFactory.hooks.beforeResolve.tap('MyPlugin', (resolveData) => {
      // access and modify module request information
      console.log(JSON.stringify(resolveData, null, 2));
    });
  },
);
```


ResolveData.ts

## `factorize`

`AsyncSeriesBailHook<[ResolveData]>`

Called before initiating resolve. It should return undefined to proceed.

The `factorize` hook is used to add custom logic before a module is instantiated, modifying the module creation process.

```js
compiler.hooks.compilation.tap(
  'MyPlugin',
  (compilation, { normalModuleFactory }) => {
    normalModuleFactory.hooks.factorize.tap('MyPlugin', (resolveData) => {
      // access and modify module request information
      console.log(JSON.stringify(resolveData, null, 2));
    });
  },
);
```


ResolveData.ts

:::warning
Returning module instance is not supported for now. This hook will affect the module creation process, so use it with caution.
:::

## `resolve`

`AsyncSeriesBailHook<[ResolveData]>`

Called before the request is resolved, it should return `undefined` to continue. The `resolve` hook can be used to intercept and modify module request information before module resolution begins. This hook allows for preprocessing of module requests.

```js
compiler.hooks.compilation.tap(
  'MyPlugin',
  (compilation, { normalModuleFactory }) => {
    normalModuleFactory.hooks.resolve.tap('MyPlugin', (resolveData) => {
      // access and modify module request information
      console.log(JSON.stringify(resolveData, null, 2));
    });
  },
);
```


ResolveData.ts

:::warning
Returning module instance or `false` is not supported for now.
:::

## `afterResolve`

`AsyncSeriesBailHook<[ResolveData]>`

Called after the module specifier is resolved.

The `afterResolve` hook is used to further process or modify the results after the module has been resolved. It is called at the end of the module resolution process, which means that at this stage, the module's path, request information, etc., have already been determined.

```js
compiler.hooks.compilation.tap(
  'MyPlugin',
  (compilation, { normalModuleFactory }) => {
    normalModuleFactory.hooks.afterResolve.tap('MyPlugin', (resolveData) => {
      // access and modify the resolved module information
      console.log(JSON.stringify(resolveData, null, 2));
    });
  },
);
```


ResolveData.ts

## `createModule`

`AsyncSeriesBailHook<[NormalModuleCreateData, {}]>`

Called after a request has been resolved and before Rspack creates the normal module instance. Return `undefined` to continue with the default module creation flow.

```js
compiler.hooks.compilation.tap(
  'MyPlugin',
  (compilation, { normalModuleFactory }) => {
    normalModuleFactory.hooks.createModule.tap('MyPlugin', (createData) => {
      // inspect module creation data
      console.log(createData.resourceResolveData.resource);
    });
  },
);
```

## `resolveForScheme`

`AsyncSeriesBailHook<[ResourceDataWithData]>`

Called before a module specifier with scheme (URI) is resolved.

The `resolveForScheme` is typically used to handle module specifiers that have a specific protocol, such as `file://`, `https://`, etc.

```js
compiler.hooks.compilation.tap(
  'MyPlugin',
  (compilation, { normalModuleFactory }) => {
    normalModuleFactory.hooks.resolveForScheme
      .for('https')
      .tap('MyPlugin', (resourceData) => {
        console.log(JSON.stringify(resourceData, null, 2));
      });
  },
);
```


ResourceDataWithData.ts


---
url: /api/plugin-api/context-module-factory-hooks.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# ContextModuleFactory

The `ContextModuleFactory` module is used by the `Compiler` to generate dependencies from [require.context](/api/runtime-api/module-methods.md#requirecontext) API. It resolves the requested directory, generates requests for each file and filters against passed regExp. Matching dependencies then passes through [NormalModuleFactory](/api/plugin-api/normal-module-factory-hooks.md).

## `beforeResolve`

`AsyncSeriesWaterfallHook<[BeforeResolveResult]>`

Called before resolving the requested directory. The request can be ignored by returning `false`.


BeforeResolveResult.ts

## `afterResolve`

`AsyncSeriesWaterfallHook<[AfterResolveResult]>`

Called after the requested directory resolved.


AfterResolveResult.ts


---
url: /api/plugin-api/javascript-modules-plugin-hooks.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# JavascriptModulesPlugin

## `chunkHash`

`SyncHook<[Chunk, Hash]>`

Called when computing the chunk hash for JavaScript chunks.


Chunk.ts

Hash.ts


---
url: /api/plugin-api/stats-hooks.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Stats hooks

## StatsFactory

### StatsFactory.hooks.extract

A HookMap that is called when generating the specified stats item.

- **Type:** `HookMap<SyncBailHook<[Object, any, StatsFactoryContext], undefined>>`
- **Arguments:**
  - `object`: result stats item object to which properties should be added
  - `data`: original data of the stats item
  - `StatsFactoryContext`: generating context

```ts
// Only common context fields are listed here. Different stats item types may provide additional fields.
type StatsFactoryContext = {
  type: string;
  compilation: Compilation;
  makePathsRelative?: (value: string) => string;
  [key: string]: any;
};
```

For the following example, the `customProperty` attribute is added in the finally generated `stats.compilation` through `MyPlugin`:

```js
compilation.hooks.statsFactory.tap('MyPlugin', (statsFactory, options) => {
  statsFactory.hooks.extract
    .for('compilation')
    .tap('MyPlugin', (object, compilation) => {
      object.customProperty = MyPlugin.getCustomValue(compilation);
    });
});
```

### StatsFactory.hooks.result

A HookMap that is called after generating the specified stats item.

- **Type:** `HookMap<SyncWaterfallHook<[any, StatsFactoryContext]>>`
- **Arguments:**
  - `any`: generated stats item result
  - `StatsFactoryContext`: generating context

## StatsPrinter

### StatsPrinter.hooks.print

A HookMap that is called when generating the printed string of the specified stats item.

- **Type:** `HookMap<SyncBailHook<[{}, StatsPrinterContext], string>>`
- **Arguments:**
  - `object`: stats item object
  - `StatsPrinterContext`: printing context

```ts
// Only common context fields are listed here. Different stats item types may provide additional fields.
type StatsPrinterContext = {
  type?: string;
  compilation?: StatsCompilation;
  chunkGroup?: StatsChunkGroup;
  asset?: StatsAsset;
  module?: StatsModule;
  chunk?: StatsChunk;
  moduleReason?: StatsModuleReason;
  bold?: (str: string) => string;
  yellow?: (str: string) => string;
  red?: (str: string) => string;
  green?: (str: string) => string;
  magenta?: (str: string) => string;
  cyan?: (str: string) => string;
  formatFilename?: (file: string, oversize?: boolean) => string;
  formatModuleId?: (id: string) => string;
  formatChunkId?:
    | ((id: string, direction?: 'parent' | 'child' | 'sibling') => string)
    | undefined;
  formatSize?: (size: number) => string;
  formatDateTime?: (dateTime: number) => string;
  formatFlag?: (flag: string) => string;
  formatTime?: (time: number, boldQuantity?: boolean) => string;
  chunkGroupKind?: string;
  [key: string]: any;
};
```

### StatsPrinter.hooks.result

A HookMap that is called after generating the printed string of the specified stats item.

- **Type:** `HookMap<SyncWaterfallHook<[string, StatsPrinterContext]>>`
- **Arguments:**
  - `string`: printed string of the stats item
  - `StatsPrinterContext`: printing context



---
url: /api/plugin-api/runtime-plugin-hooks.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# RuntimePlugin hooks

`RuntimePlugin` is used to generate the code for the Rspack startup. It provides the following hooks that can be used to modify these runtime codes.

You can obtain these hooks like below:

```js title="rspack.config.mjs"
export default {
  //...
  plugins: [
    {
      apply: (compiler) => {
        const { RuntimePlugin } = compiler.rspack;
        compiler.hooks.compilation.tap('MyPlugin', (compilation) => {
          const hooks = RuntimePlugin.getCompilationHooks(compilation);
          //...
        });
      },
    },
  ],
};
```

## `createScript`

`SyncWaterfallHook<[string, Chunk]>`

Can modify the code executed when creating the `<script>` tag.

As in the following code, the `crossorigin` attribute can be added to the `<script>` tag:

```js
hooks.createScript.tap('MyPlugin', (code, chunk) => {
  return `
    ${code}
    script.crossOrigin = 'anonymous';
  `;
});
```


Chunk.ts

## `createLink`

`SyncWaterfallHook<[string, Chunk]>`

Can modify the code executed when creating a generic `<link>` tag.

```js
hooks.createLink.tap('MyPlugin', (code, chunk) => {
  return `
    ${code}
    link.crossOrigin = 'anonymous';
  `;
});
```


Chunk.ts

## `linkPrefetch`

`SyncWaterfallHook<[string, Chunk]>`

Can modify the code executed when creating the [prefetch](/guide/optimization/code-splitting.md#prefetchingpreloading-modules) `<link rel="prefetch">` tag.

As in the following code, the `crossorigin` attribute can be added to the `<link>` tag for prefetching:

```js
hooks.linkPrefetch.tap('MyPlugin', (code, chunk) => {
  return `
    ${code}
    link.crossOrigin = 'anonymous';
  `;
});
```


Chunk.ts

## `linkPreload`

`SyncWaterfallHook<[string, Chunk]>`

Can modify the code executed when creating the [preload](/guide/optimization/code-splitting.md#prefetchingpreloading-modules) `<link rel="preload">` tag.

As in the following code, the `crossorigin` attribute can be added to the `<link>` tag for preloading:

```js
hooks.linkPreload.tap('MyPlugin', (code, chunk) => {
  return `
    ${code}
    link.crossOrigin = 'anonymous';
  `;
});
```


Chunk.ts


---
url: /api/plugin-api/external-module-hooks.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# ExternalModule hooks

`ExternalModule` represents a dependency whose implementation is provided by the runtime environment instead of being bundled by Rspack. It provides hooks for controlling how external modules are assigned to chunks.

You can obtain these hooks as follows:

```js title="rspack.config.mjs"
export default {
  plugins: [
    {
      apply(compiler) {
        const { ExternalModule } = compiler.rspack;
        compiler.hooks.compilation.tap('MyPlugin', (compilation) => {
          const hooks = ExternalModule.getCompilationHooks(compilation);
          // ...
        });
      },
    },
  ],
};
```

## `chunkCondition`

`SyncBailHook<[Chunk, Compilation], boolean | undefined>`

Controls whether an external module can be included in a chunk. Return `true` to allow the external module in the chunk, `false` to disallow it, or `undefined` to continue to subsequent taps and then use Rspack's default behavior.

The following example only allows external modules to be included in entry chunks:

```js
hooks.chunkCondition.tap('MyPlugin', (chunk, compilation) => {
  return compilation.chunkGraph.getNumberOfEntryModules(chunk) > 0;
});
```


Chunk.ts

Compilation.ts


---
url: /blog/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Rspack blogs

Browse release notes, ecosystem updates, and technical deep dives from the Rspack team [@rspack\_dev](https://x.com/rspack_dev).

## [Announcing Rspack 2.2](/blog/announcing-2-2)

> August 26, 2026 · Pengfei Shu, Jiahan Chen, Chenwei Dai, Zhixin Jin, 9aoy, Sooniter, LingyuCoder

Rspack 2.2 is now available, featuring performance and HMR improvements, shorter module IDs, import.meta enhancements, and support for more platforms.

## [Announcing Rspack 2.1](/blog/announcing-2-1)

> June 26, 2026 · Gengkun He, Yu Feng, Congcong Pan, Jiahan Chen, Zhiyong Chen, Zhixin Jin, Chenwei Dai, Lingyu Wang

Rspack 2.1 is now available, featuring support for the Rust version of React Compiler, import.meta.glob, Source Phase Imports, persistent cache cleanup, and multiple performance and output optimizations.

## [Announcing Rspack 2.0](/blog/announcing-2-0)

> April 22, 2026 · Rspack Team

Rspack 2.0 is out! It introduces more modern defaults, API design, and build outputs while remaining compatible with the webpack ecosystem.

## [Announcing Rspack 1.7](/blog/announcing-1-7)

> December 31, 2025 · Rspack Team

Rspack 1.7 has been released, improving SWC Wasm plugin compatibility, importing assets as bytes, and stabilizing multiple experimental features.

## [Announcing Rspack 1.6](/blog/announcing-1-6)

> October 30, 2025 · Rspack Team

Rspack 1.6 has been released with better ESM output, enhanced tree shaking, support for the import defer syntax, stabilized layers feature, and default barrel file optimization.

## [Announcing Rspack 1.5](/blog/announcing-1-5)

> August 26, 2025 · Rspack Team

Rspack 1.5 has been released, introducing barrel file optimization and constant inlining optimization, also adding a built-in file system watcher, a virtual modules plugin, and a Rust extension mechanism, while dropping support for Node.js 16.

## [Bundler tree shaking principles and differences](https://github.com/orgs/web-infra-dev/discussions/29)

> July 31, 2025 · ahabhgk

Tree shaking has become an essential part of modern front-end bundling. This article provides a brief overview of tree shaking principles across different bundlers and explores their key differences.

## [How to embed a HashMap with lots of strings in program](https://github.com/orgs/web-infra-dev/discussions/27)

> July 2, 2025 · quininer

This article introduces techniques for constructing a completely static and efficient Map using MPHF and string packing, avoiding initialization, parsing, and memory allocation while improving binary size and compile speed.

## [Announcing Rspack 1.4](/blog/announcing-1-4)

> June 26, 2025 · Rspack Team

Rspack 1.4 has been released with support for running in the browser, incremental builds enabled by default, faster SWC, smaller bundles, and new features including the `CssChunkingPlugin`.

## [Rspack joins the Next.js ecosystem](/blog/rspack-next-partner)

> April 10, 2025 · Rspack Team

Today, we’re excited to introduce next-rspack, a community-driven plugin bringing direct Rspack support to Next.js. This integration offers a fast, webpack-compatible alternative for teams not yet ready to adopt Turbopack.

## [Announcing Rspack 1.3](/blog/announcing-1-3)

> March 28, 2025 · Rspack Team

Rspack 1.3 has been released with support for detecting circular dependencies, building HTTP imports, and referencing AMD modules. It introduces a new lazy compilation middleware, while also improving code splitting performance, output bundle size, and memory usage.

## [Announcing Rspack 1.2](/blog/announcing-1-2)

> January 21, 2025 · jerrykingxyz, chenjiahan, JSerFeng, ahabhgk

Rspack 1.2 has been released, introducing experimental persistent caching, a faster code splitting algorithm, and Yarn PnP support.

## [Build systems and bundlers](https://github.com/orgs/web-infra-dev/discussions/24)

> January 7, 2025 · ahabhgk

This article will briefly introduce the content of the "Build Systems à la Carte: Theory and Practice" paper and attempt to summarize bundlers from the perspective of build systems.

## [RSC and Server Action bundle practice](https://github.com/orgs/web-infra-dev/discussions/23)

> January 6, 2025 · ahabhgk

This article introduces the construction practices of RSC (React Server Components) and Server Action in React, including their concepts, rendering methods, bundling process in webpack, and how Turbopack bundles multiple environment modules in a module diagram.

## [Announcing Rspack 1.1](/blog/announcing-1-1)

> November 7, 2024 · LingyuCoder, ahabhgk, GiveMe-A-Name, 9aoy, chenjiahan

Rspack and Rsbuild 1.1 has been released, significantly improve the performance of cold starts and incremental builds. It also improve the built-in HTML plugin and types of configuration options.

## [Announcing Rspack 1.0](/blog/announcing-1-0)

> August 28, 2024 · Rspack Team

Today Rspack has reached a new milestone - 1.0. This means that Rspack is production-ready, covers most of webpack's APIs and features, and is now prepared to support more users.

## [Announcing Rspack 1.0 alpha](/blog/announcing-1-0-alpha)

> June 29, 2024 · Rspack Team

Rspack 1.0 alpha is now available on npm! Before releasing Rspack 1.0 stable version, we will test for 1~2 months to improve the API stability and reliability of v1.0 and to verify its impact on downstream projects.

## [Announcing Rspack 0.7](/blog/announcing-0-7)

> May 28, 2024 · Rspack Team

Rspack 0.7 has been released, featuring support for lazy compilation, which can significantly improve the dev startup performance of large applications. It also introduces a brand-new css-module-lexer, increasing CSS bundling speed by 4 times.

## [Deep dive into Rspack tree shaking](https://github.com/orgs/web-infra-dev/discussions/17)

> April 17, 2024 · hardfist

This article primarily focuses on understanding the concept of Rspack & webpack tree shaking.

## [Announcing Rspack 0.6](/blog/announcing-0-6)

> April 10, 2024 · Rspack Team

Rspack 0.6 is out, with built-in support for mini-css-extract-plugin and new tree-shaking enabled by default.

## [Webpack chunk graph algorithm](https://github.com/orgs/web-infra-dev/discussions/15)

> January 12, 2024 · JSerFeng

This article introduces the chunk strategy of webpack. Through this article, you can understand when a chunk will be generated in the code and how to reduce the chunk size, etc.

## [Announcing Rspack 0.5](/blog/announcing-0-5)

> January 9, 2024 · Rspack Team

Rspack 0.5 is out, supporting Module Federation and removing the default SWC transformation.

## [Module Federation added to Rspack](/blog/module-federation-added-to-rspack)

> January 9, 2024 · Rspack Team

The latest Rspack 0.5.0 introduces the highly anticipated Module Federation, which is detailed in this article.

## [Webpack CSS order issue](https://github.com/orgs/web-infra-dev/discussions/12)

> November 29, 2023 · JSerFeng

This article shows how the CSS order problem occurs in webpack and how to solve it.

## [Announcing Rspack 0.4](/blog/announcing-0-4)

> November 22, 2023 · Rspack Team

Rspack 0.4 is out, removing support for some builtin features.

## [Deep dive into Top-level await](https://github.com/orgs/web-infra-dev/discussions/9)

> October 26, 2023 · ulivz

In this article, we will take a closer look at aspects such as the specification, toolchain support, webpack runtime, and profiling of Top-level await.

## [Design trade-offs in bundler](https://github.com/orgs/web-infra-dev/discussions/1)

> August 30, 2023 · hardfist

This article explains why we decided to develop Rspack and what trade-offs we made during the design process.

## [Announcing Rspack 0.3](/blog/announcing-0-3)

> August 24, 2023 · Rspack Team

Rspack 0.3 is out, adding support for web workers and the builtin:swc-loader.

## [Announcing Rspack 0.2](/blog/announcing-0-2)

> June 2, 2023 · Rspack Team

Rspack 0.2 is out, introducing many new features, such as support for realContentHash, DataURI, and the ESM format, and more.

## [Announcing Rspack 0.1](/blog/announcing-0-1)

> March 6, 2023 · Rspack Team

Rspack has officially been released!



---
url: /blog/announcing-2-2.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 2.2

_August 26, 2026_


![Pengfei Shu](https://github.com/stormslowly.png)

Pengfei Shu

[](https://github.com/stormslowly)

@stormslowly

![Jiahan Chen](https://github.com/chenjiahan.png)

Jiahan Chen

[](https://github.com/chenjiahan)

@chenjiahan

![Chenwei Dai](https://github.com/Timeless0911.png)

Chenwei Dai

[](https://github.com/Timeless0911)

@Timeless0911

![Zhixin Jin](https://github.com/intellild.png)

Zhixin Jin

[](https://github.com/intellild)

@intellild

![9aoy](https://github.com/9aoy.png)

9aoy

[](https://github.com/9aoy)

@9aoy

![Sooniter](https://github.com/sooniter.png)

Sooniter

[](https://github.com/sooniter)

@sooniter

![LingyuCoder](https://github.com/LingyuCoder.png)

LingyuCoder

[](https://github.com/LingyuCoder)

@LingyuCoder

![Rspack 2.2 banner](https://assets.rspack.rs/rspack/rspack-banner-v2.2.png)

We are excited to announce that Rspack 2.2 is now available!

***

Notable changes include:

- Performance
  - [Performance improvements](#performance-improvements)
  - [Better HMR](#better-hmr)
  - [Shorter module IDs](#compact-hashed-ids)
- New features
  - [`import.meta` improvements](#import-meta-improvements)
  - [Browserslist Baseline support](#browserslist-baseline)
  - [Support for more platforms](#more-linux-platforms)
- Ecosystem
  - [Rsbuild](#rsbuild)
  - [Rstest](#rstest)
  - [Rslint](#rslint)
  - [Rslib](#rslib)
  - [Rspress](#rspress)
  - [Agent plugin](#rstack-agent-plugin)
- [Upgrade guide](#upgrade-guide)

## Performance

### Performance improvements \{#performance-improvements}

Rspack 2.2 includes more than 30 performance optimizations, including:

- Sped up module concatenation, chunk splitting, source map generation, and other core processes. In our benchmark, these changes cut production build time by around 5%, from 1822 ms to 1725 ms.
- Made [CopyRspackPlugin](/plugins/copy-rspack-plugin.md) around 3-4x faster when copying a large number of files.
- Reduced the Wasm build size from 29.5 MB to 28.4 MB, saving around 1.1 MB.
- Parallelized SWC Wasm plugin compilation to reduce plugin load times. For example, this cut load time for the [coverage-instrument](https://npmx.dev/package/swc-plugin-coverage-instrument) plugin by around 80%.
- Made built-in CSS parsing around 3x faster:

| Scenario              | Before   | After   | Improvement |
| --------------------- | -------- | ------- | ----------- |
| CSS development build | 320.3 ms | 87.2 ms | **3.7x**    |
| CSS production build  | 354.1 ms | 121 ms  | **2.9x**    |

### Better HMR \{#better-hmr}

Rspack 2.2 avoids unnecessary CSS requests during HMR. Previously, even a JavaScript-only change made the browser request and compare related CSS files to check for style updates. This overhead grew with the size of the stylesheet.

With [#14682](https://github.com/web-infra-dev/rspack/pull/14682), Rspack now checks for CSS changes during the build. The browser requests CSS assets only when needed, avoiding unnecessary HTTP requests. As a result, JavaScript hot update times no longer grow significantly with stylesheet size:

| Stylesheet size | Before   | After  |
| --------------- | -------- | ------ |
| 0.5 MB          | \~50 ms  | \~5 ms |
| 2.1 MB          | \~170 ms | \~5 ms |
| 4.1 MB          | \~385 ms | \~6 ms |

In addition, [#14580](https://github.com/web-infra-dev/rspack/pull/14580) prevents page flicker caused by styles briefly disappearing during hot updates with `mini-css-extract-plugin`.

### Shorter module IDs \{#compact-hashed-ids}

Rspack can now generate shorter module and chunk IDs. The new `compact-hashed` strategy selects the shortest available prefix from a stable hash. Compared with `deterministic`, it reduces output size while preserving stable IDs and efficient runtime indexing.

In a real-world project, the output size changed as follows:

| **Metric**      | **`deterministic`** | **`compact-hashed`** | **Size reduction**  |
| --------------- | ------------------- | -------------------- | ------------------- |
| Minified JS     | 25,795.2 KB         | 25,710.6 KB          | **84.6 KB (0.33%)** |
| Minified + gzip | 7,103.3 KB          | 7,041.7 KB           | **61.6 KB (0.87%)** |

Enable this strategy with [`optimization.chunkIds`](/config/optimization.md#optimizationchunkids) and [`optimization.moduleIds`](/config/optimization.md#optimizationmoduleids):

```js title="rspack.config.mjs"
export default {
  optimization: {
    chunkIds: 'compact-hashed',
    moduleIds: 'compact-hashed',
  },
};
```

## New features

### `import.meta` improvements \{#import-meta-improvements}

Rspack now exposes Rspack-specific module variables through [`import.meta`](/api/runtime-api/module-variables.md#import-meta). This aligns more closely with ESM conventions than CommonJS-style variables, so we recommend it for ESM modules:

```js
// Before
__webpack_public_path__ = '/assets/';

// After
import.meta.rspackPublicPath = '/assets/';
```

[`import.meta.glob`](/api/runtime-api/module-variables.md#importmetaglob) now supports a `caseSensitive` option. Set it to `false` to match file paths case-insensitively:

```js
const modules = import.meta.glob('./pages/**/*.js', {
  caseSensitive: false,
});
```

### Browserslist Baseline support \{#browserslist-baseline}

Rspack now supports [Baseline queries in Browserslist](https://web.dev/articles/use-baseline-with-browserslist). These queries let you target browser versions by Baseline feature set. For example, to target [**Baseline Widely available features**](https://web.dev/baseline), use:

```js title="rspack.config.mjs"
export default {
  target: 'browserslist:baseline widely available',
};
```

You can also target features that were widely available on a specific date with `baseline widely available on 2025-05-01`. See the [`target` configuration documentation](/config/target.md#baseline-queries) for details.

### Support for more platforms \{#more-linux-platforms}

Rspack now provides precompiled native bindings for more Linux platforms:

- RISC-V 64-bit: `linux-riscv64-gnu` and `linux-riscv64-musl`
- ppc64le and s390x architectures: `linux-ppc64-gnu` and `linux-s390x-gnu`

On these platforms, Rspack can use the corresponding native binding instead of falling back to Wasm. See [Environment preparation](/guide/start/quick-start.md#environment-preparation) for the complete list of supported platforms.

## Ecosystem

### Rsbuild \{#rsbuild}

Rsbuild 2.2 has been released alongside Rspack 2.2.

#### Importing source text \{#import-text}

Rsbuild now supports [import attributes](https://rsbuild.rs/guide/basic/static-assets#with-import-attributes) for importing a file's raw contents as a string:

```ts
import rawCSS from './example.css' with { type: 'text' };
```

> This aligns with the TC39 [Import Text proposal](https://github.com/tc39/proposal-import-text).

#### Node.js split chunks \{#node-split-chunks}

For Node.js builds, [chunk splitting](https://rsbuild.rs/config/split-chunks) is now enabled by default. It extracts shared modules into separate chunks, reducing duplicate code and SSR memory usage.

The following [real-world results](https://github.com/TanStack/router/issues/8113#issuecomment-5366808113) were provided by a TanStack Start user:

| Metric                                 | Rsbuild 2.1 | Rsbuild 2.2 | Change            |
| -------------------------------------- | ----------- | ----------- | ----------------- |
| Server output size                     | 298 MB      | 4.1 MB      | **98% reduction** |
| Memory usage after visiting all routes | 486 MB      | 129 MB      | **73% reduction** |
| Average route access time              | 7.2 ms      | 1.6 ms      | **78% reduction** |
| HMR time for shared components         | 7.1 s       | 0.98 s      | **86% reduction** |

> The test application contains 300 routes and 400 shared components. Actual improvements depend on your project's size and module structure.

#### Solid v2 support \{#solid-v2}

Rsbuild now supports [Solid v2 RC](https://www.solidjs.com/blog/solid-2-0-rc-the-big-reveal) and uses Solid's new Rust compiler by default. In Solid's official benchmark, the Rust compiler is **more than 20x faster** than the previous Babel implementation.

To try it, upgrade [@rsbuild/plugin-solid](https://rsbuild.rs/plugins/list/plugin-solid) to the v2 beta and remove the Babel plugin:

```diff
-import { pluginBabel } from '@rsbuild/plugin-babel';
import { pluginSolid } from '@rsbuild/plugin-solid';

export default {
  plugins: [
-   pluginBabel({
-     include: /\.(?:jsx|tsx)$/,
-   }),
    pluginSolid(),
  ],
};
```

#### Octane template \{#octane-template}

`create-rsbuild` now supports creating Octane projects. [Octane](https://octanejs.dev/) is a high-performance JavaScript UI framework. You write components with React APIs, and Octane compiles them into code that updates the DOM directly.

Run this command to create an Octane project:

```bash
npx -y create-rsbuild@latest my-app -t octane-ts
```

#### Dynamic ports \{#dynamic-port}

Rsbuild now lets you set [`server.port`](https://rsbuild.rs/config/server/port#dynamic-port) to `0`, so the operating system assigns an available port automatically:

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

This is useful in tests because it prevents port conflicts when multiple Rsbuild servers start at once.

#### Custom minifier configurations \{#custom-minimizer-configs}

Rsbuild now supports multiple minification configurations. Pass an array to [`minify.jsOptions`](https://rsbuild.rs/config/output/minify#minifyjsoptions) to apply different strategies to different outputs. This example removes `console` calls only from the main bundle:

```ts title="rsbuild.config.ts"
export default {
  output: {
    minify: {
      jsOptions: [
        {
          include: /main\./,
          minimizerOptions: {
            compress: { drop_console: true },
          },
        },
        {
          exclude: /main\./,
          minimizerOptions: {
            compress: { drop_console: false },
          },
        },
      ],
    },
  },
};
```

#### Custom restart handling \{#restart-api}

Frameworks and tools built on Rsbuild can now manage restarts themselves.

The Rsbuild JavaScript API now provides a [`restart`](https://rsbuild.rs/api/javascript-api/core#restart-handling) option. Use it to handle restart requests from the development server (`rsbuild dev`) or watch builds (`rsbuild build --watch`):

```ts
import { createRsbuild } from '@rsbuild/core';

await createRsbuild({
  restart: (restart) => {
    // Custom restart logic
  },
});
```

Rsbuild plugins can also run custom logic by listening to the [`onRestart`](https://rsbuild.rs/plugins/dev/hooks#onrestart) hook.

### Rstest \{#rstest}

#### Module Federation testing \{#rstest-module-federation}

Rstest now supports testing real remote modules exposed through Module Federation in Node.js, JSDOM, and Browser Mode.

Add `@module-federation/rstest` to your Rstest configuration:

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

export default defineConfig({
  plugins: [
    federation({
      name: 'host',
      // options
    }),
  ],
});
```

> See the [Module Federation × Rstest integration documentation](https://module-federation.io/integrations/build-tool/rstest.html) for details.

#### Playwright E2E testing \{#rstest-playwright}

Rstest now provides [`@rstest/playwright`](https://rstest.rs/guide/advanced/playwright), bringing its test runner, configuration, and reporting to E2E testing.

It provides Playwright-style assertions for local development servers, preview servers, and deployed applications. This lets E2E tests use the same workflow as unit tests:

```ts
import { expect, test } from '@rstest/playwright';

test('home page', async ({ page, serve }) => {
  const { url } = await serve('./dist/index.html');

  await page.goto(url);
  await expect(page.locator('h1')).toHaveText('Home');
});
```

#### Prebundled test environments \{#rstest-environment-prebundle}

Rstest now supports prebundling DOM test environments. When enabled, it prebundles `jsdom` or `happy-dom` and reuses the output across workers. This avoids repeated parsing and initialization for each test file. It can significantly reduce test time in projects with many DOM tests.

In a [benchmark](https://github.com/web-infra-dev/rstest/releases/tag/v0.11.6), a project with 1,000 test cases saw the following improvements:

| Test environment    | Native loading | Prebundled | Time reduction |
| ------------------- | -------------- | ---------- | -------------- |
| `jsdom` 30.0.1      | 16.99 s        | 10.57 s    | **37.8%**      |
| `happy-dom` 20.11.1 | 6.35 s         | 2.98 s     | **53.0%**      |

This feature is disabled by default. Enable it with [`testEnvironment.prebundle`](https://rstest.rs/config/test/test-environment#environment-prebundle):

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

export default defineConfig({
  testEnvironment: {
    name: 'jsdom',
    prebundle: 'auto',
  },
});
```

With `'auto'`, Rstest prebundles only versions of `jsdom` and `happy-dom` verified as compatible. If it cannot build, load, or verify the output, it falls back to native loading. Actual improvements depend on project size and runtime environment.

### Rslint \{#rslint}

#### More lint rules \{#typescript-eslint-support}

Rslint now includes more than 500 built-in lint rules and implements [all rules and presets](https://rslint.rs/api/presets/ts) from `@typescript-eslint`.

For example, you can enable all recommended type-aware rules through the `recommendedTypeChecked` preset:

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

export default defineConfig([
  js.configs.recommended,
  ts.configs.recommendedTypeChecked,
]);
```

#### Configuration type hints \{#config-type-hints}

`defineConfig` now provides complete type hints for ESLint core rules and `@typescript-eslint` rules, including rule names and option types.

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

export default defineConfig([
  {
    rules: {
      '@typescript-eslint/no-floating-promises': 'error',
      '@typescript-eslint/no-unused-vars': [
        'error',
        { argsIgnorePattern: '^_' },
      ],
    },
  },
]);
```

#### Built-in common globals \{#built-in-globals}

`@rslint/core` now provides a built-in [`globals`](https://rslint.rs/api/configuration/globals) object containing global variable definitions for common environments such as browsers, Node.js, and Rstest:

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

export default defineConfig([
  {
    languageOptions: {
      globals: globals.browser,
    },
  },
]);
```

#### JavaScript API \{#rslint-js-api}

`@rslint/core` now provides a [JavaScript API](https://rslint.rs/guide/js-api) aligned with ESLint v10:

```ts
import { Rslint } from '@rslint/core';

const rslint = new Rslint({ fix: true });
const results = await rslint.lintFiles(['src/**/*.ts']);

await Rslint.outputFixes(results);
```

The JavaScript API also lets you lint source code in memory with `lintText`. You can provide configuration, `tsconfig.json`, and project files through `virtualFiles`. This is useful for editor and playground integrations that work without direct file system access.

### Rslib \{#rslib}

#### TypeScript 7 support \{#typescript-7}

Rslib 0.23.2 can generate declaration files with [TypeScript 7](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/). After installing TypeScript 7, Rslib enables native TypeScript automatically. This makes declaration file generation around **5-10x faster**.


```sh [npm]
npm add typescript@latest -D
```

```sh [yarn]
yarn add typescript@latest -D
```

```sh [pnpm]
pnpm add typescript@latest -D
```

```sh [bun]
bun add typescript@latest -D
```

```sh [deno]
deno add npm:typescript@latest -D
```

#### Rslib 1.0 is coming soon \{#rslib-v1}

[Rslib 1.0 RC](https://github.com/web-infra-dev/rslib/releases/tag/v1.0.0-rc.1) is now available, with the stable release coming soon. If you use Rslib 0.x, see the [Upgrade from 0.x to v1](https://v1.rslib.rs/guide/upgrade/v0-to-v1) guide for details about the breaking changes.

### Rspress \{#rspress}

Rspress earned an Agent-friendly score of 100/100 from [AFDocs](https://afdocs.dev/).

Rspress features such as `llms.txt`, [SSG-MD](https://rspress.rs/guide/basic/ssg-md), `Accept: text/markdown`, and `injectLlmsHint` help Agents discover, read, and understand its documentation. See [How to build an Agent-friendly website](https://rspress.rs/blog/agent-friendly-website) for the design and practices behind these features.

![Rspress AFDocs scorecard](https://assets.rspack.rs/rspress/assets/rspress-afdocs-scorecard.png)

### Agent plugin \{#rstack-agent-plugin}

Rstack has released the Rstack Agent Plugin, built on [Agent Plugins 1.0](https://agent-plugins.org/). It works with any Agent client that supports the specification, including GitHub Copilot, Codex, and Cursor.

The plugin provides the complete collection of Rstack Skills, helping Agents develop and maintain Rstack projects more effectively.

![Rstack Agent Plugin](https://assets.rspack.rs/rstack/assets/rstack-agent-plugin.png)

To install the plugin:


For your Agent

Install the Rstack Agent Plugin

Copy this prompt and send it to your Agent to install the plugin.

Copy Prompt

Install the Rstack Agent Plugin from https://github.com/rstackjs/agent-skills.

> See [Rstack Agent Skills](https://github.com/rstackjs/agent-skills) to learn more.

## Upgrade guide \{#upgrade-guide}

### Wasm plugins \{#wasm-plugin-breaking}

Rspack 2.2 upgrades `swc_core` from 76 to 77. This changes the AST serialization format at the SWC Wasm plugin boundary. Wasm plugins built with an older version of SWC will no longer load, causing builds to fail with this error:

```text
The version of the SWC Wasm plugin you're using might not be compatible with 'builtin:swc-loader'.
```

If you use an SWC Wasm plugin, rebuild it with SWC 77 or upgrade to a compatible version. Find plugin versions that match your current Rspack version at [plugins.swc.rs](https://plugins.swc.rs/).

> See [FAQ - SWC plugin version mismatch](/errors/swc-plugin-version.md) for details.

### RSC plugin \{#rsc-plugin-use-preinit}

Previously, the RSC plugin wrapped Client References to insert CSS `<link>` tags during rendering. The wrapped exports were no longer the original Client References, so some export forms could lose the Client Reference marker.

Rspack 2.2 no longer wraps Client References. Instead, it uses React's [`preinit`](https://react.dev/reference/react-dom/preinit) to load CSS for client components.

This is a breaking change for RSC framework integrations because it changes how client component CSS is loaded. If you maintain an integration with the Rspack RSC plugin, also upgrade [`react-server-dom-rspack`](https://www.npmjs.com/package/react-server-dom-rspack) to `0.1.0`.



---
url: /blog/announcing-2-1.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 2.1

_June 26, 2026_


![Gengkun He](https://github.com/ahabhgk.png)

Gengkun He

[](https://github.com/ahabhgk)

@ahabhgk

![Yu Feng](https://github.com/JSerFeng.png)

Yu Feng

[](https://github.com/JSerFeng)

@JSerFeng

![Congcong Pan](https://github.com/SyMind.png)

Congcong Pan

[](https://github.com/SyMind)

@SyMind

![Jiahan Chen](https://github.com/chenjiahan.png)

Jiahan Chen

[](https://github.com/chenjiahan)

@chenjiahan

![Zhiyong Chen](https://github.com/CPunisher.png)

Zhiyong Chen

[](https://github.com/CPunisher)

@CPunisher

![Zhixin Jin](https://github.com/intellild.png)

Zhixin Jin

[](https://github.com/intellild)

@intellild

![Chenwei Dai](https://github.com/Timeless0911.png)

Chenwei Dai

[](https://github.com/Timeless0911)

@Timeless0911

![Lingyu Wang](https://github.com/LingyuCoder.png)

Lingyu Wang

[](https://github.com/LingyuCoder)

@LingyuCoder

![Rspack 2.1 banner](https://assets.rspack.rs/rspack/rspack-banner-v2.1.png)

We are excited to announce the official release of Rspack 2.1!

***

Notable changes include:

- Performance improvements
  - [Rust version of React Compiler](#react-compiler)
  - [Build performance improvements](#build-performance)
  - [TypeScript 7 support](#tsgo-support)
  - [Faster circular dependency checks](#circular-check)
- New features
  - [Support for `import.meta.glob`](#import-meta-glob)
  - [Improved built-in CSS support](#builtin-css-features)
  - [Support for parsing `createRequire`](#create-require)
  - [Rspack magic comments](#magic-comments)
  - [Support for source phase imports](#source-phase-imports)
  - [Automatic persistent cache cleanup](#cache-cleanup)
- Output optimization
  - [`pureFunctions` stabilized](#pure-functions)
  - [Branch-aware dependency pruning](#branch-aware-dependency-pruning)
  - [Branch-aware ESM export presence checks](#branch-aware-export-presence)
  - [`export const` value binding optimization](#export-const-getter)
- Ecosystem
  - [TanStack RSC support](#tanstack-rsc-support)
  - [Rsbuild](#rsbuild)
  - [Rslib](#rslib)
  - [Rstest](#rstest)
  - [Rslint](#rslint)
  - [Rspress](#rspress)
  - [Rsdoctor](#rsdoctor)
  - [rspack-merge](#rspack-merge)

## Performance improvements

### Rust version of React Compiler \{#react-compiler}

[React Compiler](https://react.dev/learn/react-compiler/introduction) is an official build-time optimization tool for React. It automatically adds appropriate memoization logic for components and Hooks during compilation, reducing the need to manually use `useMemo`, `useCallback`, and `React.memo`.

In the past, React Compiler was mainly integrated through `babel-loader`, which introduced additional Babel transform overhead and increased project build time. Now that [React Compiler has been ported to Rust](https://github.com/facebook/react/pull/36173), SWC has also completed its integration. In Rspack 2.1, you can now enable React Compiler directly through the built-in SWC loader.

In our benchmark, the Rust version of React Compiler is around **7-13x faster** than the Babel version:

| Command        | React Compiler (Rust) | React Compiler (Babel) | Improvement |
| -------------- | --------------------- | ---------------------- | ----------- |
| `rspack dev`   | **0.7 s**             | **10.6 s**             | **13.5x**   |
| `rspack build` | **1.2 s**             | **9.3 s**              | **7.4x**    |

Enable React Compiler through `jsc.transform.reactCompiler` in `builtin:swc-loader`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              transform: {
                react: {
                  runtime: 'automatic',
                },
                reactCompiler: true, // [!code highlight]
              },
            },
          },
        },
      },
    ],
  },
};
```

For more configuration options, see the [Rspack React Compiler guide](/guide/integrations/react.md#react-compiler).

### Build performance improvements \{#build-performance}

Build performance has always been one of Rspack's core priorities. In our benchmark, **Rspack 2.1 improves production build performance by around 16% and HMR performance by around 5%** compared with Rspack 2.0.

| Version       | Production build (no cache) | Production build (with cache) | HMR        |
| ------------- | --------------------------- | ----------------------------- | ---------- |
| Rspack 1.7.11 | **3.12 s**                  | **2.09 s**                    | **129 ms** |
| Rspack 2.0.0  | **2.66 s**                  | **1.36 s**                    | **113 ms** |
| Rspack 2.1.0  | **2.22 s**                  | **1.20 s**                    | **107 ms** |

> Data source: [rspack-react-10k-benchmark](https://github.com/LingyuCoder/rspack-react-10k-benchmark/actions/runs/28093280576)

These improvements mainly come from three areas: a large number of micro-optimizations in the main build pipeline, optimized low-level data structures for the module graph and dependency relationships, and improvements to SWC parsing and transformation.

### TypeScript 7 support \{#tsgo-support}

TypeScript type checking is often one of the most time-consuming parts of the build pipeline. [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin) now supports type checking with TypeScript 7 (TypeScript Go). In builds with type checking enabled, the overall time can be reduced by around **60%**.

Install the TypeScript 7 RC version in your project to use it:


```sh [npm]
npm add typescript@rc -D
```

```sh [yarn]
yarn add typescript@rc -D
```

```sh [pnpm]
pnpm add typescript@rc -D
```

```sh [bun]
bun add typescript@rc -D
```

```sh [deno]
deno add npm:typescript@rc -D
```

```js title="rspack.config.mjs"
import { TsCheckerRspackPlugin } from 'ts-checker-rspack-plugin';

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

### Faster circular dependency checks \{#circular-check}

Rspack 2.1 adds [`CircularCheckRspackPlugin`](/plugins/circular-check-rspack-plugin.md), which replaces the deprecated [`CircularDependencyRspackPlugin`](/plugins/circular-dependency-rspack-plugin.md).

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.CircularCheckRspackPlugin()],
};
```

Compared with the old plugin, the new CircularCheckRspackPlugin brings two main improvements:

- **Better performance**: the old plugin's detection approach was closer to expanding circular paths from entries, which could cause repeated traversal in large module graphs. The new plugin uses a graph algorithm that is better suited for cycle detection. It can find circular components in a single analysis pass and generate readable circular paths for each component, reducing detection overhead in large projects.
- **More reasonable API design**: the old plugin's API design was less intuitive and inconsistent with the commonly used `circular-dependency-plugin` API in the webpack ecosystem. The new plugin returns to a more direct "detect and report circular dependencies" model, provides options that are more consistent with the webpack ecosystem, and is easier to understand and migrate to.

If you are using `CircularDependencyRspackPlugin`, we recommend migrating to `CircularCheckRspackPlugin`. If you only need to ignore certain warnings, you can use [`ignoreWarnings`](/config/other-options.md#ignorewarnings).

## New features

### Support for `import.meta.glob` \{#import-meta-glob}

Rspack now supports [`import.meta.glob`](/api/runtime-api/module-variables.md#importmetaglob). You can collect modules by glob pattern and load them only when needed:

```js
const pages = import.meta.glob('./pages/**/*.js');

for (const path in pages) {
  const mod = await pages[path]();
}
```

This feature is already available in Vite and Turbopack. With support in Rspack, developers can use a more consistent and familiar syntax across different ecosystem tools, reducing the cognitive cost of switching between them. It also lets framework and library authors who support multiple build tools reuse more similar implementation patterns.

> See the [`import.meta.glob` documentation](/api/runtime-api/module-variables.md#importmetaglob) for complete usage details.

### Improved built-in CSS support \{#builtin-css-features}

Rspack 2.1 further improves [built-in CSS support](/guide/languages/css.md#built-in-css-support). The new `css/global` module type allows CSS Modules to work in a "global by default, opt into `:local` when needed" mode. Together with `css/module` and `css/auto`, it covers more scope organization patterns.

CSS Modules support also continues to improve, with more CSS Modules syntax and behavior now supported.

For related configuration, see the CSS options in [`module.generator`](/config/module-generator.md#cssauto) and [`module.parser`](/config/module-parser.md#cssauto).

### Support for parsing `createRequire` \{#create-require}

ESM modules do not have a built-in `require`, so Node.js provides [`module.createRequire()`](https://nodejs.org/api/module.html#modulecreaterequirefilename), which lets you create a `require` function inside ESM to load CommonJS modules. In previous versions, Rspack could not statically analyze the `require` created this way, so modules loaded by it could not be bundled correctly.

Rspack 2.1 adds the [`module.parser.javascript.createRequire`](/config/module-parser.md#javascriptcreaterequire) option. When enabled, Rspack recognizes `createRequire` imported from Node.js `module` and converts the created `require` into a statically analyzable dependency context. Modules loaded through it can then be bundled just like modules loaded by ordinary `require` or `import`.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        createRequire: true,
      },
    },
  },
};
```

```js title="index.js"
import { createRequire } from 'module';

const require = createRequire(import.meta.url);
const value = require('./value.cjs');
```

This option also supports:

- **Multiple import forms**: named imports, default imports, and namespace imports are supported, and imports from both `module` and `node:module` are recognized.
- **Custom sources**: in addition to `true`, you can customize the specifier and module source using a string in the `"<specifier> from <module>"` form, such as `"createRequire from module"`.
- **Statically analyzable arguments**: the argument of `createRequire()` must be statically analyzable as a file URL or an absolute path, such as `import.meta.url`, `new URL('./dir/file.js', import.meta.url)`, or an absolute `file:` URL.

This option is disabled by default. See [`module.parser.javascript.createRequire`](/config/module-parser.md#javascriptcreaterequire) for details.

### Rspack magic comments \{#magic-comments}

Rspack 2.1 adds support for the `rspack` prefix in [magic comments](/api/runtime-api/module-methods.md#magic-comments). You can now use the `rspack` prefix to declare compilation hints:

```js
import(/* rspackChunkName: "dashboard" */ './dashboard');
```

The existing `webpack` prefix remains compatible, so existing projects do not need to migrate.

> See the [magic comments documentation](/api/runtime-api/module-methods.md#magic-comments) for details.

### Support for source phase imports \{#source-phase-imports}

Rspack 2.1 supports the WebAssembly use case in the TC39 [Source Phase Imports](https://github.com/tc39/proposal-source-phase-imports) proposal. After enabling [`experiments.sourceImport`](/config/experiments.md#experimentssourceimport), you can import `.wasm` modules through static `import source` or dynamic `import.source()`.

Unlike normal WebAssembly imports, a source phase import does not instantiate the Wasm module during import. Instead, it returns a compiled [`WebAssembly.Module`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Module). This lets you control instantiation yourself, such as instantiating the same Wasm module multiple times with different imports, or reusing the same compiled result across multiple Web Workers to avoid the cost of repeated compilation.

```js title="rspack.config.mjs"
export default {
  experiments: {
    sourceImport: true,
  },
};
```

```js title="index.js"
import source wasmModule from './module.wasm';

const instance = await WebAssembly.instantiate(wasmModule, {
  // imports...
});
```

You can also use dynamic import:

```js
const wasmModule = await import.source('./module.wasm');
const instance = await WebAssembly.instantiate(wasmModule);
```

Rspack also adds [`module.rules[].phase`](/config/module-rules.md#rulesphase), which lets rules match modules by import phase. You can distinguish normal `evaluation` imports, `import defer` with the `defer` phase, and Source Phase Imports with the `source` phase, so the same resource can use different loaders, parser options, or module types depending on how it is imported.

### Automatic persistent cache cleanup \{#cache-cleanup}

Rspack's persistent cache is isolated by version. When `cache.version`, cache-related configuration, or the Rspack version changes, Rspack creates a new cache version to avoid reusing an incompatible cache. During long-term development, frequent branch switching, or CI workflows that reuse the working directory, old cache versions may continue to accumulate and take up disk space.

Rspack 2.1 adds an automatic cleanup mechanism for persistent cache. It uses `cache.maxAge` and `cache.maxVersions` to control old versions retained in the cache directory:

- [`cache.maxAge`](/config/cache.md#maxage): the maximum time a cache version can remain unaccessed. The default value is `7 * 24 * 60 * 60` (7 days).
- [`cache.maxVersions`](/config/cache.md#maxversions): the maximum number of cache versions retained in the current cache directory. The default value is `3`.

```js title="rspack.config.mjs"
export default {
  cache: {
    type: 'persistent',
    maxAge: 7 * 24 * 60 * 60,
    maxVersions: 3,
  },
};
```

When the number of cache versions exceeds the retention limit, or when versions have not been accessed for a long time, Rspack prioritizes cleaning up older and less recently accessed cache versions. This keeps recent reusable caches while preventing the persistent cache directory from growing without bound. For scenarios where you need to manage caches manually, set `maxAge` or `maxVersions` to `Infinity` to disable age-based or version-count-based cleanup respectively.

## Output optimization

### `pureFunctions` stabilized \{#pure-functions}

Rspack 2.0 introduced the experimental [`pureFunctions`](/config/experiments.md#experimentspurefunctions) capability for finer-grained tree shaking of side-effect-free function calls across modules. After a period of iteration and validation, Rspack 2.1 enables this capability by default in production mode, so you no longer need to manually set `experiments.pureFunctions: true`.

This capability mainly covers two scenarios: adding the [`/*#__NO_SIDE_EFFECTS__*/`](/guide/optimization/tree-shaking.md#no_side_effects-annotation) annotation at function definitions, and marking side-effect-free functions through [`module.parser.javascript.pureFunctions`](/config/module-parser.md#javascriptpurefunctions). When the result of a marked function call is unused, Rspack can safely remove the call during tree shaking.

For example, the following `join` function is declared as side-effect-free. If the return value of the call is not used, the call is removed automatically:

```js title="utils.js"
/*#__NO_SIDE_EFFECTS__*/
export function join(a, b) {
  return `${a}-${b}`;
}
```

```js title="index.js"
import { join } from './utils';

// The return value is unused, so this call is removed automatically.
join('btn', 'primary');
```

If you want to disable this analysis, you can disable `experiments.pureFunctions`:

```js title="rspack.config.mjs"
export default {
  experiments: {
    pureFunctions: false,
  },
};
```

See the [tree shaking guide](/guide/optimization/tree-shaking.md#purefunctions) for details.

### Branch-aware dependency pruning \{#branch-aware-dependency-pruning}

Rspack 2.1 improves dependency analysis for inline constant scenarios. When the condition of an `if` statement or ternary expression depends on an inlined boolean export, Rspack now associates the branch condition with dependencies inside that branch. If Rspack later determines that a branch will not be executed, dependencies in that branch are marked as inactive, allowing them to participate in tree shaking and chunk pruning.

```js title="env.js"
export const IS_DEV = false;
```

```js title="index.js"
import { IS_DEV } from './env';

if (IS_DEV) {
  import('./debug-tools');
} else {
  import('./app');
}
```

In the example above, `IS_DEV` can be inlined as `false`, so the `./debug-tools` dependency in the `if` branch is no longer treated as an active dependency. Compared with the previous behavior where dependencies from both branches were retained, this can reduce invalid modules in the output and avoid generating unnecessary dynamic import chunks for unreachable branches.

This optimization also supports simple boolean expressions composed with `!`, `&&`, and `||`, as well as dependencies inside ternary expression branches. For conditions that cannot be statically determined, Rspack keeps the original behavior to ensure runtime semantics remain unchanged.

### Branch-aware ESM export presence checks \{#branch-aware-export-presence}

Rspack checks during compilation whether ESM imports access exports that do not exist and emits warnings such as `export ... was not found`. Previously, this check could not understand runtime existence checks such as `if ("name" in ns)`, so even when code checked whether an export existed first, accesses inside the branch could still produce false positives.

Rspack 2.1 improves analysis for `in` expressions on ESM namespaces. When an export access is guarded by the same `in` check, Rspack recognizes the branch condition and no longer reports a missing export warning for that access.

```js title="index.js"
import * as feature from './feature';

if ('debug' in feature) {
  feature.debug();
}
```

In the example above, if `./feature` does not export `debug`, `'debug' in feature` returns `false` at runtime and `feature.debug()` inside the branch will not be executed. Rspack can now understand this and no longer emits a missing export warning for the guarded access.

This check also applies to branch conditions composed with `!`, `&&`, `||`, and ternary expressions. It supports namespace imports, namespace objects from named exports, and nested member access. For accesses that are not guarded by the same `in` check, Rspack continues to report warnings so real missing export issues are not hidden.

### `export const` value binding optimization \{#export-const-getter}

Rspack 2.1 simplifies the generated code for ESM `export const`. In previous versions, Rspack generated getter functions for ESM exports uniformly to preserve ESM live binding semantics:

```js
__webpack_require__.d(__webpack_exports__, {
  value: () => value,
});
```

For `export const` in non-cyclic modules, however, the exported value will not change after module initialization, so it does not need to be read through a getter every time. In production builds, Rspack 2.1 uses circular module information: when Rspack confirms that the current module is not part of a circular dependency, `export const` is defined on the namespace object as a read-only value, reducing generated code and runtime getter call overhead.

```js title="Output sketch"
// Before: accessing namespace.value executes a getter function.
__webpack_require__.d(__webpack_exports__, {
  value: () => value,
});

// Rspack 2.1: const exports in non-cyclic modules are defined as read-only values.
// Accessing namespace.value no longer needs to execute a getter function.
__webpack_require__.d(
  __webpack_exports__,
  {},
  {
    value: value,
  },
);
```

```js title="constants.js"
export const answer = 42;

const message = 'hello';
export { message };

export default 'default value';
```

The named `const` exports above, as well as constant values in default exports, can benefit from this optimization. For `let`, function exports, and `const` exports in cyclic modules, Rspack still keeps the getter form to ensure mutable exports and circular dependency scenarios preserve correct semantics. In the future, we will continue exploring reassignment analysis to identify more stable exports, so more scenarios can use the lighter value-binding form.

## Ecosystem

### TanStack RSC support \{#tanstack-rsc-support}

We are working with the TanStack team to improve Rsbuild support in TanStack Start, and we have already made concrete progress: [TanStack Start now officially supports Rsbuild](https://tanstack.com/blog/start-adds-rsbuild-support). Developers can now use Rsbuild to build TanStack Start applications and access framework capabilities including RSC.

Our core goal for RSC is to provide general-purpose RSC build capabilities, allowing higher-level frameworks to integrate RSC based on their own routing, rendering, and server runtime solutions while reusing unified build infrastructure.

If you want to try RSC in the Rspack stack, see:

- [TanStack Start guide](https://rsbuild.rs/guide/framework/react#tanstack-start): learn how to use Rsbuild in TanStack Start.
- [rsbuild-plugin-rsc](https://github.com/rstackjs/rsbuild-plugin-rsc): an RSC plugin based on Rsbuild.

### Rsbuild \{#rsbuild}

Rsbuild 2.1 has been released alongside Rspack 2.1. See the [Rsbuild 2.1 blog](https://rsbuild.rs/blog/v2-1) for details.

### Rslib \{#rslib}

Rslib adds a fast type generation mode based on `isolatedDeclarations`. After enabling [dts.isolated](https://rslib.rs/config/lib/dts#dtsisolated), Rslib uses SWC's type generation capability during the Rspack build to directly emit declaration files for TypeScript modules in the dependency graph.

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

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

This capability is suitable for daily builds in monorepos or multi-package libraries. You can split declaration generation and type checking into two steps:

- Daily builds: Rslib quickly emits declaration files.
- Global checks: run unified type checking in CI or a pre-commit hook through [rslint --type-check](https://rslint.rs/guide/type-checking).

Taking the Rsbuild repository as an example, the time required to generate declaration files with different approaches is as follows:

| Approach              | Time     |
| --------------------- | -------- |
| TypeScript 6          | **9.7s** |
| TypeScript 7          | **4.1s** |
| Isolated Declarations | **2.3s** |

> For more details, see [dts.isolated](https://rslib.rs/config/lib/dts#dtsisolated).

### Rstest \{#rstest}

Rstest 0.10 focuses on test efficiency and stability. The biggest update is the new `--changed` / `--related` test filtering capability, which can run only the tests affected by source changes and significantly shorten feedback loops in local development and CI for large projects.

`--changed` automatically detects changed source files from the Git working tree, including unstaged, staged, and untracked files, then runs only the related tests:

```bash
rstest run --changed
```

You can also compare against a specific commit or branch:

```bash
rstest run --changed=HEAD~1
rstest run --changed=origin/main
```

`--related` lets you explicitly pass source files and run only tests that depend on them. It also provides the Jest-compatible `--findRelatedTests` alias:

```bash
rstest run --related src/button.ts
rstest run --findRelatedTests src/button.ts
```

If you only want to preview the affected test files, combine these flags with `rstest list`:

```bash
rstest list --changed --filesOnly
rstest list --related src/button.ts --filesOnly
```

Rstest 0.10 also includes several other improvements:

- A new `threads` pool based on `worker_threads`, reducing startup overhead for suites with many small test files.
- Persistent build cache support, improving warm-run build performance.
- Memory-aware worker scheduling, reducing OOM risk under high parallelism.
- Silent console output for passed tests, keeping failure logs useful while reducing noise.
- `--trace` profiling support, making performance investigation easier.
- Clearer worker output attribution for logs and crashes.

> See the [Rstest 0.10 blog](https://rstest.rs/blog/announcing-0-10) for details.

### Rslint \{#rslint}

**Many built-in rules**: Rslint has ported rules from ESLint core and community plugins such as `@typescript-eslint`, `react`, `jsx-a11y`, `jest`, and `promise`. It now has more than 400 [built-in rules](https://rslint.rs/rules/), covering common rules out of the box.

**ESLint plugin compatibility**: beyond built-in rules, Rslint can now directly run rules from community ESLint plugins and use them together with built-in native rules. You only need to mount the plugin under a custom prefix in the configuration. Diagnostics from the plugin are merged into the same report, autofixes can be applied together through `--fix` and the editor's `source.fixAll`, and the behavior is consistent between the CLI and the VS Code extension.

```js title="rslint.config.mjs"
import examplePlugin from 'eslint-plugin-example';

export default [
  {
    files: ['**/*.ts'],
    plugins: { example: examplePlugin },
    rules: {
      'example/some-rule': 'error',
    },
  },
];
```

For more usage and current limitations, see the [ESLint plugin compatibility guide](https://rslint.rs/guide/eslint-plugins).

### Rspress \{#rspress}

Rspress now provides more Agent Skills, including:

- `rspress-docs-generator`: generate an Rspress documentation site for the current project.
- `rspress-custom-theme`: generate a custom Rspress theme.

Here is a theme generated by `rspress-custom-theme`:

![Rspress custom theme skill](https://assets.rspack.rs/rspress/assets/rspress-custom-theme-skill.png)

These skills can be installed directly into existing projects or selected during project initialization. For more details, see the [Rspress - AI Guide](https://rspress.rs/guide/start/ai).

### Rsdoctor \{#rsdoctor}

Rsdoctor added [AI analysis](https://rsdoctor.rs/guide/start/action#ai-assisted-analysis) in GitHub Actions. When a build analysis report contains size changes, Rsdoctor can combine them with the current project's build data to analyze regressions and help locate performance bottlenecks, bundle size increases, and optimization opportunities.


![Rsdoctor AI Action analysis detail](https://assets.rspack.rs/others/assets/rsdoctor/actions-ai-detail.png)

### rspack-merge \{#rspack-merge}

We released [rspack-merge](https://github.com/rstackjs/rspack-merge), an npm package for merging Rspack configurations. It covers use cases ranging from composing base configurations to merging loader and plugin rules.

```ts title="rspack.config.ts"
import { defineConfig } from '@rspack/cli';
import { merge } from 'rspack-merge';

const sharedConfig = defineConfig({
  // ...
});

const serverConfig = merge(sharedConfig, {
  // ...
});

const clientConfig = merge(sharedConfig, {
  // ...
});

export default [serverConfig, clientConfig];
```

`rspack-merge` is written in TypeScript, ships modern ESM output, and keeps zero runtime dependencies, making configuration merging simple, reliable, and lightweight.



---
url: /blog/announcing-2-0.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 2.0

_April 22, 2026_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

![Rspack 2.0 banner](https://assets.rspack.rs/rspack/rspack-banner-v2.0.png)

We are excited to announce the official release of Rspack 2.0!

## Looking back at 1.x

When we released Rspack 1.0 in August 2024, we set a clear goal: deliver a 10x performance improvement while staying compatible with the webpack API and ecosystem.

Looking back at the 1.x cycle, we have largely achieved that goal. Rspack not only implemented webpack's core capabilities and plugin APIs, but also continued to improve developer experience, output optimization, and support for modern language features. Along the way, we introduced and refined incremental builds, lazy compilation, persistent cache, constant inlining, virtual modules, barrel file optimization, and more.

Rspack is also being adopted by a growing number of users. Compared with the 1.0 release, **Rspack's weekly downloads have grown from 100,000 to 5 million**:

![Rspack 2.0 npm downloads](https://assets.rspack.rs/rspack/assets/rspack-v2-0-npm-downloads.png)

We also built Rstack around Rspack, a unified JavaScript toolchain that includes [Rsbuild](https://github.com/web-infra-dev/rsbuild), [Rslib](https://github.com/web-infra-dev/rslib), [Rstest](https://github.com/web-infra-dev/rstest), [Rspress](https://github.com/web-infra-dev/rspress), [Rsdoctor](https://github.com/web-infra-dev/rsdoctor), and [Rslint](https://github.com/web-infra-dev/rslint). These tools serve different use cases, but they share the same mission: making web development simpler, more consistent, and more efficient.

Rspack is also becoming part of the broader JavaScript ecosystem. Many excellent tools, frameworks, and platforms in the community now support Rspack, including [Angular Rspack](https://nx.dev/docs/technologies/angular/angular-rspack), [Addfox](https://github.com/addfox/addfox), [Docusaurus](https://github.com/facebook/docusaurus), [Extension.js](https://github.com/extension-js/extension.js), [ice.js](https://github.com/alibaba/ice), [Lynx](https://github.com/lynx-family/lynx), [Meteor](https://github.com/meteor/meteor), [Modern.js](https://github.com/web-infra-dev/modern.js), [Next.js](https://github.com/vercel/next.js), [Nuxt](https://github.com/nuxt/nuxt), [Nx](https://github.com/nrwl/nx), [Kmi](https://github.com/kmijs/kmi), [Re.Pack](https://github.com/callstack/repack), [Remotion](https://github.com/remotion-dev/remotion), [Shakapacker](https://github.com/shakacode/shakapacker), [Storybook](https://github.com/storybookjs/storybook), [TanStack Router](https://tanstack.com/router), [Unplugin](https://github.com/unjs/unplugin), [Vize](https://github.com/ubugeeei/vize), [xmcp](https://github.com/basementstudio/xmcp), and [Zephyr](https://zephyr-cloud.io/). We sincerely thank all the projects and teams in the community that support Rspack.

## Toward 2.0

The JavaScript ecosystem keeps evolving, and coding agents are also changing how software is built. This prompted us to rethink how a future-ready bundler should evolve.

**Rspack's goal is not just to be a faster webpack.** During the 1.x cycle, we intentionally aligned Rspack's APIs and defaults with webpack 5 to help existing projects migrate at minimal cost. But as JavaScript modules and the surrounding ecosystem continue to evolve, some historical design choices are no longer the right defaults for modern development.

Starting in 2.0, while remaining compatible with the webpack ecosystem, Rspack will gradually introduce defaults, API design, and build outputs that are better aligned with modern JavaScript development. We will roll out these changes in stages. We will avoid packing too many breaking changes into a single major release whenever possible, and we will provide migration guides and Agent Skills to keep migration costs manageable.

## Highlights in 2.0

Rspack 2.0 brings the following updates:

- Performance improvements
  - [Faster builds](#build-performance)
  - [Fewer default dependencies](#fewer-deps)
- Output optimization
  - [Better static analysis](#better-tree-shaking)
  - [Compiler annotation support](#pure-functions)
  - [Module Federation tree shaking](#mf-share-treeshaking)
- Improved ESM support
  - [Pure ESM packages](#pure-esm)
  - [Support for `import.meta`](#import-meta)
  - [Support for `import defer`](#import-defer)
  - [Improved ESM library builds](#modern-module)
- New features
  - [React Server Components support](#rsc-support)
  - [Support for `#/` subpath alias imports](#subpath-alias-import)
  - [Simplified target configuration](#automatic-targets)
  - [Simplified `swc-loader` configuration](#detect-syntax)
  - [Control over CSS imports](#resolve-import)
  - [Use hashes as module IDs](#hashed-module-ids-plugin)
  - [Improved code splitting](#enforce-size-threshold)

## Performance improvements

### Faster builds \{#build-performance}

Build performance has always been one of Rspack's core priorities. Compared with Rspack 1.7, **Rspack 2.0 improves overall performance by around 10%**, and by as much as 100% compared with 1.0.

| Version    | Production build (no cache) | Production build (with cache) | HMR        |
| ---------- | --------------------------- | ----------------------------- | ---------- |
| Rspack 1.0 | **5.6 s**                   | **5.6 s**                     | **128 ms** |
| Rspack 1.7 | **3.6 s**                   | **2.2 s**                     | **134 ms** |
| Rspack 2.0 | **3.1 s**                   | **1.4 s**                     | **118 ms** |

> Data source: [rspack-react-10k-benchmark](https://github.com/LingyuCoder/rspack-react-10k-benchmark/actions/runs/24710780593)

These improvements mainly come from continued optimization of the core architecture. We refactored parts of the algorithms and data structures on critical performance paths, upgraded outdated dependencies, and removed unused code paths.

With [persistent cache](/config/cache.md) enabled, both build performance and memory usage improve even further:

- Rspack now supports cache reuse for the [SWC minimizer plugin](/plugins/swc-js-minimizer-rspack-plugin.md). On cache hits, **build performance improves by around 50%**.
- With optimized underlying storage, **memory usage drops by more than 20%** when cache is enabled.

### Fewer default dependencies \{#fewer-deps}

Rspack 2.0 reduces the number of npm dependencies installed by default:

- `@rspack/dev-server`: **dependency count reduced from 192 to 1**.
- `@rspack/core`: **dependency count reduced from 8 to 1**.
- `@rspack/cli`: **now has zero dependencies**.

In Rspack 1.x, `@rspack/dev-server` pulled in many dependencies indirectly through `webpack-dev-server`, which increased the installation size and made dependency management more complex. To address this, we refactored it, streamlined its features and dependencies, and **reduced the install size by more than 90%** (from 15 MB to 1.4 MB).

At the same time, `@rspack/cli` no longer depends on `@rspack/dev-server` by default. That means if you only use `rspack build`, you no longer need to install dev-server-related dependencies.

We also reduced dependencies through the following measures:

- Making non-core dependencies optional. For example, [@module-federation/runtime-tools](https://www.npmjs.com/package/@module-federation/runtime-tools) now only needs to be installed when you use the [ModuleFederationPlugin](/plugins/module-federation-plugin.md).
- Replacing heavier dependencies with lighter alternatives, such as using [connect-next](https://github.com/rstackjs/connect-next) instead of Express. For dev servers, Connect's middleware model already covers most scenarios, and using it also keeps Rspack aligned with Rsbuild's dev server implementation.
- [Bundling some dependencies into the npm package](https://e18e.dev/blog/bundling-dependencies) so that Rspack can control the versions of those dependencies and their transitive dependencies, reducing potential supply-chain risks caused by automatic upgrades.
- Preferring native Node.js 20+ APIs where possible, such as using [styleText](https://nodejs.org/api/util.html#utilstyletextformat-text-options) instead of `picocolors`.

## Output optimization

### Better static analysis \{#better-tree-shaking}

Rspack 2.0 improves static analysis so that more complex code patterns can benefit from [tree shaking](/guide/optimization/tree-shaking.md). Some patterns that were previously difficult to analyze can now participate in export-level pruning.

- **CommonJS `require` destructuring**: Rspack can now identify which exported members are actually used in a destructuring assignment and keep only the required code.

```js
const { bar } = require('./foo');
```

- **CommonJS `require` property access and calls**: Rspack can now further analyze property access and calls to determine which exports are used.

```js
const foo = require('./foo');

foo.bar;
foo.baz();
```

- **Inline property access and calls on dynamic `import()` results**: When module members are accessed directly in the expression, Rspack can also identify the used exports and prune the rest.

```js
(await import('./foo')).bar;
```

### Compiler annotation support \{#pure-functions}

Rspack 2.0 now supports [compiler annotations](https://github.com/javascript-compiler-hints/compiler-notations-spec), allowing you to use `#__NO_SIDE_EFFECTS__` to mark functions as side-effect-free. When the return value of such a function call is unused, tree shaking can automatically remove the unused code.

For example, in the following code, `join` is marked as side-effect-free. When its return value is not used, the call can be removed safely.

```js title="utils.js"
/*#__NO_SIDE_EFFECTS__*/
export function join(a, b) {
  return `${a}-${b}`;
}
```

```js title="index.js"
import { join } from './utils';

join('btn', 'primary');
```

> This feature is still experimental and currently requires [`experiments.pureFunctions`](/config/experiments.md#experimentspurefunctions) to be enabled. It will be enabled by default in a future version. See the [guide](/guide/optimization/tree-shaking.md#no_side_effects-annotation) for details.

For third-party modules whose source code you cannot modify directly, Rspack also lets you manually declare pure functions through [`module.parser.javascript.pureFunctions`](/config/module-parser.md#javascriptpurefunctions) to achieve the same effect.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        pureFunctions: ['myFunctionName'],
      },
    },
  },
};
```

### Module Federation tree shaking \{#mf-share-treeshaking}

Rspack now supports tree shaking for shared dependencies in [Module Federation](/guide/advanced/module-federation.md), allowing it to prune them at the export level, remove unused parts, and reduce the size of shared packages.

In Rspack 1.x, once a dependency was declared as `shared`, the runtime usually had to load the entire package. Even if only a few exports were used, the whole package would still be included. For large shared libraries, that could add significant overhead.

Rspack 2.0 adds `treeShaking` support to the `shared` option. When enabled, `ModuleFederationPlugin` generates a pruned build for the shared dependency and loads that result at runtime when possible. If it cannot be used, Rspack falls back to the full dependency to keep behavior consistent.

For example:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.container.ModuleFederationPlugin({
      shared: {
        'lodash-es': {
          singleton: true,
          treeShaking: {
            mode: 'runtime-infer',
            usedExports: ['debounce'],
          },
        },
      },
    }),
  ],
};
```

> See the [shared dependency tree shaking guide](https://module-federation.io/guide/performance/shared-tree-shaking) for more details.

## Improved ESM support

### Pure ESM packages \{#pure-esm}

Rspack's core packages are now published as pure ESM packages, and their CommonJS builds have been removed. This makes module loading more consistent and better aligned with current Node.js practices.

This change affects the following npm packages:

- [@rspack/core](https://www.npmjs.com/package/@rspack/core)
- [@rspack/cli](https://www.npmjs.com/package/@rspack/cli)
- [@rspack/dev-server](https://www.npmjs.com/package/@rspack/dev-server)
- [@rspack/plugin-react-refresh](https://www.npmjs.com/package/@rspack/plugin-react-refresh)

In Node.js 20 and later, the runtime already supports loading ESM modules using [require(esm)](https://nodejs.org/api/modules.html#loading-ecmascript-modules-using-require). For most projects that still use Rspack through the JavaScript API, this change has little practical impact and does not require additional code changes.

### Support for `import.meta` \{#import-meta}

Rspack 2.0 improves support for [import.meta](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta).

In Rspack 1.x, to support non-ESM output, Rspack resolved `import.meta` during compilation and replaced it with corresponding values. Unknown `import.meta` properties were usually replaced directly with `undefined`.

Starting in Rspack 2.0, when generating ESM output, Rspack preserves unknown `import.meta` properties by default instead of replacing them during compilation. This lets you use custom `import.meta` properties and makes the behavior closer to the ESM spec.

You can also control this behavior with [`module.parser.javascript.importMeta`](/config/module-parser.md#javascriptimportmeta), for example:

```js title="rspack.config.mjs"
export default {
  output: {
    module: true,
  },
  module: {
    parser: {
      javascript: {
        importMeta: 'preserve-unknown',
      },
    },
  },
};
```

Rspack 2.0 also adds support for [`import.meta.main`](/api/runtime-api/module-variables.md#importmetamain), [`import.meta.filename`](/api/runtime-api/module-variables.md#importmetafilename), and [`import.meta.dirname`](/api/runtime-api/module-variables.md#importmetadirname).

### Support for `import defer` \{#import-defer}

[import defer](https://github.com/tc39/proposal-defer-import-eval) is a JavaScript feature for deferring module evaluation, and it is also supported in [TypeScript 5.9](https://devblogs.microsoft.com/typescript/announcing-typescript-5-9-beta/#support-for-import-defer). It allows a module to be loaded without immediately evaluating it or its dependencies, giving you more control over when code runs and when side effects occur.

Rspack has supported the `import defer * as foo from './foo'` syntax since 1.6. In 2.0, we expanded that support to include `import.defer()`, allowing it to cover more real-world scenarios.

- Enable the experimental flag:

```js title="rspack.config.mjs"
export default {
  experiments: {
    deferImport: true,
  },
};
```

- Use `import.defer()` to dynamically import a module:

```js title="app.js"
const file = Math.random() > 0.5 ? 'a.js' : 'b.js';

import.defer('./dir' + file);
```

### Improved ESM library builds \{#modern-module}

When building JavaScript libraries, the quality of ESM output directly affects how well downstream tools can analyze and optimize it. Cleaner ESM output is usually better for static analysis, code splitting, and tree shaking.

In Rspack 2.0, you can set [`output.library.type`](/config/output.md#outputlibrarytype) to `'modern-module'` to generate ESM output that is better suited to published libraries.

```js title="rspack.config.mjs"
export default {
  output: {
    library: {
      type: 'modern-module',
    },
  },
};
```

Compared with [`output.module`](/config/output.md#outputmodule), which targets general ESM output, `modern-module` is specifically optimized for library builds. It evolved from the experimental [`rspack.experiments.EsmLibraryPlugin`](https://v1.rspack.rs/plugins/rspack/esm-library-plugin) introduced in Rspack 1.x and produces output that is easier for downstream tools to analyze and process. In code-splitting scenarios, it also preserves a cleaner ESM structure and reduces duplicated code in multi-entry builds.

In addition, `modern-module` supports preserving the source directory structure. See the [ESM guide](/guide/features/esm.md) for details.

## New features

### React Server Components support \{#rsc-support}

[React Server Components](https://react.dev/reference/rsc/server-components) (RSC) are becoming an important foundation for full-stack React frameworks. Rspack 2.0 now provides experimental low-level build support, including:

- **Directive support**: Handles `"use client"` as well as module-level and function-level `"use server"` directives.
- **Compile-time checks**: Detects React API usage that violates RSC rules during compilation, helping catch issues before they reach runtime.
- **CSS support**: Collects styles from server and client components during the build and injects them during rendering.
- **HMR support**: Supports hot updates for both server and client components.

You can use this capability in two ways:

- **Use Rsbuild**: We provide out-of-the-box RSC support through [rsbuild-plugin-rsc](https://github.com/rstackjs/rsbuild-plugin-rsc).
- **Configure Rspack manually**: Refer to the [React Server Components documentation](/guide/integrations/rsc.md) to add the required configuration yourself.

Across the ecosystem, Modern.js already provides RSC support built on Rspack. See the [Modern.js RSC documentation](https://modernjs.dev/guides/basic-features/render/rsc.html) for details. Rspack also supports React Router's Data Mode, with examples available in the [React Router examples](https://github.com/rstackjs/rsbuild-plugin-rsc/tree/main/examples/react-router).

We're also working with the [TanStack](https://tanstack.com/) team and plan to support [TanStack Start](https://tanstack.com/start) and [TanStack's RSC](https://tanstack.com/blog/react-server-components) in future releases. TanStack Start is a full-stack framework built on TanStack Router, and we're excited to explore more possibilities for RSC together.

### Support for `#/` subpath alias imports \{#subpath-alias-import}

Rspack 2.0 supports `#/` subpath alias imports during module resolution. This lets you use the `imports` field in `package.json` directly to organize internal path mappings, without maintaining a separate alias configuration.

```json title="package.json"
{
  "imports": {
    "#/*": "./src/*"
  }
}
```

```js title="src/index.js"
import main from '#/main.ts';
```

### Simplified target configuration \{#automatic-targets}

In Rspack 1.x, the top-level [target](/config/target.md) option did not affect the transformation targets used by loaders or minifiers. As a result, you often had to configure target environments separately in loaders and minimizer plugins, which increased configuration overhead and duplicated the same information in multiple places.

Rspack 2.0 improves this behavior. Built-in loaders and minimizer plugins now read the top-level `target` configuration by default and infer their own target environments from it. In most cases, you only need to declare the target once at the top level to keep JavaScript transforms, CSS transforms, and minification aligned.

```js title="rspack.config.mjs"
export default {
  target: 'browserslist: Chrome >= 100',
  module: {
    rules: [
      {
        test: /\.js$/,
        use: [
          {
            loader: 'builtin:swc-loader',
            options: {
              env: { targets: 'Chrome >= 100' }, // [!code --]
            },
          },
        ],
      },
    ],
  },
  optimization: {
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin(),
      new rspack.LightningCssMinimizerRspackPlugin({
        minimizerOptions: { targets: 'Chrome >= 100' }, // [!code --]
      }),
    ],
  },
};
```

> See [target - Target inheritance](/config/target.md#target-inheritance) for more details.

### Simplified swc-loader configuration \{#detect-syntax}

In earlier versions, if you wanted [builtin:swc-loader](/guide/features/builtin-swc-loader.md) to handle `.js`, `.jsx`, `.ts`, `.tsx`, and similar files in a single rule, you had to explicitly set options such as `syntax`, `jsx`, and `tsx` in `jsc.parser` based on the file type. This ensured that SWC could parse each file with the correct semantics, such as deciding whether `<` should be treated as JSX syntax or a TypeScript generic.

That added extra configuration complexity. To make SWC parse files with different extensions correctly, you often needed multiple `rules`, which made the config longer and harder to maintain.

To solve this, Rspack 2.0 introduces the [detectSyntax](/guide/features/builtin-swc-loader.md#detectsyntax) option in the built-in `swc-loader`. With `detectSyntax: 'auto'`, the loader automatically infers `parser` options such as `syntax`, `jsx`, and `tsx` from the file extension. A single rule can now cover multiple file types, making the configuration much cleaner.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
          },
        },
      },
    ],
  },
};
```

### Control over CSS imports \{#resolve-import}

Rspack 2.0's CSS parser provides the [`resolveImport`](/config/module-parser.md#cssautoresolveimport) option to control whether `@import` is resolved and inlined during the build.

By default, Rspack resolves `@import` and merges the imported content directly into the current file. You can also set `resolveImport` to `false` to preserve the original `@import` and leave it to the browser or downstream tools.

`resolveImport` also accepts a function, allowing you to decide whether each `@import` should be inlined. For example, you can inline only imports whose filename contains `style.css`, while leaving other imports unchanged:

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        resolveImport: ({ url }) => url.includes('style.css'),
      },
    },
  },
};
```

### Use hashes as module IDs \{#hashed-module-ids-plugin}

Rspack 2.0 adds a new `hashed` option to [optimization.moduleIds](/config/optimization.md#optimizationmoduleids). When enabled, Rspack generates short, stable hashes from module paths and uses them as module IDs.

This is useful when you want module IDs to remain stable while also shortening them. For large applications with many modules, it can also reduce their footprint in the output in some cases.

```js title="rspack.config.mjs"
export default {
  optimization: {
    moduleIds: 'hashed',
  },
};
```

### Improved code splitting \{#enforce-size-threshold}

Rspack 2.0 now supports [`splitChunks.enforceSizeThreshold`](/plugins/split-chunks-plugin.md#splitchunksenforcesizethreshold), which lets you define a size threshold that Rspack will enforce during code splitting.

By default, request-count limits in `splitChunks`, such as [maxAsyncRequests](/plugins/split-chunks-plugin.md#splitchunksmaxasyncrequests) and [maxInitialRequests](/plugins/split-chunks-plugin.md#splitchunksmaxinitialrequests), can prevent large chunks from being split further. With `enforceSizeThreshold` enabled, once a module group exceeds the configured threshold, Rspack ignores those limits and forces the split.

In production mode, Rspack sets a default `enforceSizeThreshold` of `50000` bytes for all module types. In other modes, the default is `30000` bytes. You can also adjust it as needed:

```js title="rspack.config.mjs"
export default {
  optimization: {
    splitChunks: {
      // Applies to all module types
      enforceSizeThreshold: 50000,
      // You can also configure it per module type
      // enforceSizeThreshold: { javascript: 50000, css: 30000 },
    },
  },
};
```

This option can also be configured separately in cache groups, so different cache groups can use different thresholds.

## Try 2.0

### Create a new project

If you are trying Rspack for the first time, we recommend creating an [Rsbuild](https://rsbuild.rs/) project directly. It is an out-of-the-box build tool powered by Rspack:

```bash
npm create rsbuild@latest
```

> See the [Quick Start](/guide/start/quick-start.md) for more details.

### Upgrade from v1

Rspack 2.0 includes some breaking changes. For existing projects, we provide an [Upgrade Guide](/guide/migration/rspack_1.x.md) that covers all breaking changes from v1 to v2 and how to migrate them.

If you use a coding agent that supports Skills, you can install the following Skill and let the agent help with the migration. In most cases, this is more efficient than upgrading manually.

```bash
npx skills add rstackjs/agent-skills --skill rspack-v2-upgrade
```

## Looking ahead

Rspack 2.0 marks a new stage in the project's evolution. Since 1.0, it has introduced a series of updates to its performance, API design, and build outputs. Looking forward, we will continue pushing Rspack forward in many directions, including output optimization, agent support, and toolchain collaboration.

- **Output optimization**: Rspack's goal is not only to speed up builds, but also to generate higher-quality outputs while keeping behavior stable. We will continue improving core capabilities such as tree shaking, code splitting, and static analysis, explore optimizations based on static type information, and provide finer-grained controls for code splitting and optimization.
- **Agent-friendly**: As coding agents become an increasingly important user group, we will incorporate these use cases more broadly into Rspack's design so agents can understand and handle build issues more easily. For example, we will expose richer debugging information, performance metrics, and other context through the CLI, so agents can analyze problems more accurately and assist with debugging and optimization.
- **Toolchain collaboration**: In real-world projects, bundling is only one part of the overall workflow. Testing, type checking, and linting can also add significant overhead. We will continue evolving the Rstack toolchain as a coordinated system and deepen its integration with typescript-go. For example, Rslint already supports [`rslint --type-check`](https://rslint.rs/guide/type-checking), which runs linting and type checking together. We also plan to add typescript-go support to [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin).

> See [Rspack Roadmap](/misc/planning/roadmap.md) for more details.

## FAQ \{#faq}

### Will Rspack 2.0 still be compatible with webpack?

Yes. In the 2.0 era, compatibility with the webpack ecosystem will remain an important goal for Rspack.

As JavaScript standards continue to evolve, Rspack will also adopt better defaults and API design more proactively. This will happen gradually.

### Will the 1.x line continue to be maintained?

Yes. After the 2.0 release, we will continue to maintain the 1.x line for a period of time, including fixes for critical issues and migration support. However, new features and optimizations will be prioritized in 2.x, so we recommend upgrading to 2.x as soon as possible.

### When will the Rspack ecosystem upgrade to 2.0?

Rsbuild 2.0 has been released alongside Rspack 2.0. See the [Rsbuild 2.0 announcement](https://rsbuild.rs/blog/v2-0) for more details.

Rslib, Rstest, and Rspress will also upgrade to Rspack 2.0 soon. At the same time, we will continue helping frameworks and tools in the community upgrade and adapt to Rspack 2.0.

## Acknowledgements

We would like like to thank all Rspack users, contributors, and partners. Every piece of feedback and every contribution has helped move the Rspack ecosystem forward. We also hope that Rspack can continue to contribute to the broader JavaScript ecosystem.

We are equally grateful to the teams behind other bundlers in the community, including esbuild, Parcel, Rollup, Rolldown, Turbopack, and webpack. Their ongoing exploration in different directions has continued to inspire new ideas across the ecosystem, and has helped turn many of them into reality.



---
url: /blog/announcing-1-7.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 1.7

_December 31, 2025_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

![Rspack 1.7](https://assets.rspack.rs/rspack/rspack-banner-v1-7.png)

***

We are excited to announce Rspack 1.7! This marks the final minor release in the Rspack 1.x series and focuses on stabilizing existing features. Next, we'll be moving toward Rspack 2.0.

Notable changes include:

- New features
  - [Improved SWC plugin compatibility](#improved-swc-plugin-compatibility)
  - [Importing assets as bytes](#importing-assets-as-bytes)
  - [Lazy compilation](#lazy-compilation)
  - [Experimental features stabilized](#experimental-features-stabilized)
- Rstack progress
  - [Rsbuild 1.7](#rsbuild-17)
  - [Rsdoctor 1.4](#rsdoctor-14)
  - [Rslib 0.19](#rslib-019)
  - [Rstest 0.7](#rstest-07)
  - [Rspress 2.0 RC](#rspress-20-rc)

## New features

### Improved SWC plugin compatibility

In previous versions, the upgrade cost for SWC Wasm plugins was relatively high. This was because the SWC AST structure evolved across versions, causing existing plugins to fail after an SWC upgrade. Plugin authors needed to adapt their plugins, and users needed to upgrade their dependencies in lockstep, which affected project stability and the upgrade experience.

To address this issue, we contributed a series of [compatibility improvements](https://swc.rs/docs/plugin/ecmascript/compatibility) to the SWC community, including:

- Using the self-describing [cbor](https://www.rfc-editor.org/rfc/rfc8949.html) serialization scheme to replace the version-sensitive [rkyv](https://rkyv.org/), allowing Wasm plugins to better adapt to AST structure changes.
- Introducing the `Unknown` variant for enum types in the AST, improving fault tolerance when encountering new fields or nodes.

In Rspack 1.7, we upgraded the SWC version in use and adopted these compatibility improvements. From now on, in most scenarios, SWC upgrades are unlikely to break existing plugins built with older SWC versions.

Currently, this approach has been adopted by most popular SWC Wasm plugins. If you are an SWC Wasm plugin author, refer to the [official guide](https://swc.rs/docs/plugin/ecmascript/compatibility#make-your-plugin-compatible) to adopt these changes and reduce maintenance costs in future version evolutions.

### Importing assets as bytes

Rspack now natively supports the [Import Bytes](https://github.com/tc39/proposal-import-bytes) proposal for importing assets as bytes. You can now import assets as `Uint8Array` and decode them with `TextDecoder`.

```js
// Static import
import fileBytes from './file.bin' with { type: 'bytes' };
const decoder = new TextDecoder('utf-8');
const text = decoder.decode(fileBytes);

// Dynamic import
const module = await import('./file.bin', { with: { type: 'bytes' } });
const decoder = new TextDecoder('utf-8');
const text = decoder.decode(module.default);
```

### Lazy compilation

In Rspack 1.5, we stabilized the [Lazy Compilation](/guide/advanced/lazy-compilation.md) feature and enabled it by default for dynamically imported modules in Rsbuild.

Starting from Rspack 1.7, the Rspack CLI also enables lazy compilation by default for dynamically imported modules when building web applications. This change reduces the number of modules in the initial build, thereby speeding up the dev server startup.

```js title="rspack.config.mjs"
export default {
  // Current default configuration
  lazyCompilation: {
    imports: true,
    entries: false,
  },
};
```

If you have special requirements, such as needing to debug the full build output or inspect the complete module graph, you can explicitly disable this feature by setting [lazyCompilation](/config/lazy-compilation.md) to `false`.

### Experimental features stabilized

In Rspack 1.7, we have stabilized several experimental features. The following capabilities have been verified in production and are now considered stable, and the corresponding experimental flags have been deprecated or enabled by default:

- **Constant Inlining Optimization**: This optimization is now stable and enabled by default in production builds.
  - The original [experiments.inlineConst](/config/optimization.md#optimizationinlineexports) option is deprecated.
  - If you need to disable this behavior, use [optimization.inlineExports](/config/optimization.md#optimizationinlineexports) to control it.
- **TypeScript Enum Inlining Optimization**: This optimization is now stable.
  - The original [experiments.inlineEnum](/config/optimization.md#optimizationinlineexports) option is deprecated.
  - Use [collectTypeScriptInfo.exportedEnum](/guide/features/builtin-swc-loader.md#collecttypescriptinfoexportedenum) to control whether to collect exported `enum` information.
  - Use [optimization.inlineExports](/config/optimization.md#optimizationinlineexports) to control whether to inline `enum`.
- **Type Re-export Check**: This optimization is now stable.
  - The original [experiments.typeReexportsPresence](/config/module-parser.md#javascripttypereexportspresence) option is deprecated.

> Refer to the [Upgrade Guide](#upgrade-guide) to learn how to adjust related configurations.

## Rstack progress

### Rsbuild 1.7

#### Error overlay improvements

Rsbuild's error overlay now supports displaying **runtime errors**. When an exception is thrown during application execution, the error will be rendered directly on the overlay, helping you identify and diagnose issues faster.

![Rsbuild 1.7 Error Overlay](https://assets.rspack.rs/rspack/assets/rspack-v1-7-rsbuild-error-overlay.png)

This feature is disabled by default and can be enabled via the [dev.client.overlay.runtime](https://rsbuild.rs/config/dev/client#overlayruntime) option:

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

#### Asset size diff reporting

Rsbuild now supports reporting size differences to see whether the build output size has changed.

![Rsbuild 1.7 Print Size Diff](https://assets.rspack.rs/rspack/assets/rspack-v1-7-rsbuild-print-size-diff.png)

When the [performance.printFileSize.diff](https://rsbuild.rs/config/performance/print-file-size#diff) option is enabled, Rsbuild records a snapshot of the asset sizes upon build completion. Subsequent builds will automatically compare with the previous result and display size deltas in the logs. You can clearly see whether each file has grown or shrunk, as well as the overall size change, making it suitable for quickly spotting size regressions during daily development.

```js title=rsbuild.config.ts
export default {
  performance: {
    printFileSize: {
      diff: true,
    },
  },
};
```

#### create-rsbuild improvements

`create-rsbuild` now includes more out-of-the-box tools.

When creating an Rsbuild project, you can now choose to automatically integrate [Rstest](https://rstest.rs/) as the testing framework or enable [Storybook](https://storybook.rsbuild.rs/) for UI component development and debugging. Related dependencies and configurations will be set up during initialization, reducing repetitive manual configuration costs.

```text
◆  Select additional tools (Use <space> to select, <enter> to continue)
│  ◼ Rstest - testing
│  ◻ Biome - linting & formatting
│  ◻ ESLint - linting
│  ◻ Prettier - formatting
│  ◻ Storybook - component development
└
```

### Rsdoctor 1.4

#### New treemap view

Rsdoctor 1.4 introduces an improved [Treemap](https://rsdoctor.rs/guide/usage/bundle-size) view. The new interaction design helps you analyze the overall composition of the bundle and the size proportion of various assets and modules more intuitively.

In this view, you can quickly locate specific modules or assets via search. Clicking on a module or asset will automatically focus and zoom in on the corresponding area. Double-clicking a module can also expand its dependency chain, allowing you to view the reference relationship between modules layer by layer, helping identify where the size comes from.

![Rsdoctor Treemap](https://assets.rspack.rs/rspack/assets/rspack-v1-7-rsdoctor-treemap.gif)

### Rslib 0.19

#### ESM output stabilization

In previous versions, Rslib enabled Rspack's [new ESM library output](https://v1.rspack.rs/plugins/rspack/esm-library-plugin) through the experimental configuration [experiments.advancedEsm](https://rslib.rs/config/lib/experiments#experimentsadvancedesm) to improve the quality of ESM output. After verification and polishing over multiple versions, this capability is now stable.

Starting from Rslib 0.19, Rslib's bundle mode enables this feature by default. Developers do not need any additional configuration to directly obtain ESM artifacts that are friendly to static analysis and fully support code splitting.

#### JavaScript API

Rslib 0.19 introduces a [JavaScript API](https://rslib.rs/api/start), allowing developers to invoke Rslib's build capabilities programmatically in JavaScript code.

Here is a basic example:

```js
import { createRslib } from '@rslib/core';

// Create Rslib instance
const rslib = await createRslib();
// Build production output
await rslib.build();
```

> For more usage, refer to the [API Documentation](https://rslib.rs/api/javascript-api/core).

### Rstest 0.7

#### Configuration adapters

Rstest 0.7 introduces the [extends](https://rstest.rs/config/test/extends) option and an adapter mechanism, allowing you to directly reuse existing tool or framework configurations. An adapter is a configuration transformation function that can convert configurations from other tools into Rstest configurations, thereby reducing the integration overhead of Rstest.

For example, in a library project using Rslib, you can directly reuse the existing Rslib configuration via the [@rstest/adapter-rslib](https://www.npmjs.com/package/@rstest/adapter-rslib) adapter:

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

export default defineConfig({
  // Automatically read rslib.config.ts and convert to Rstest configuration
  extends: withRslibConfig(),
  // Other test configurations
  coverage: {
    // ...
  },
});
```

The adapter is responsible for converting configurations of different tools into Rstest configurations (such as `define`, `alias`, etc.), while `extends` is responsible for merging the converted configuration with Rstest's configuration. By combining the two, any tool or framework based on Rspack can be integrated with Rstest at minimal cost.

Currently, the `@rstest/adapter-rslib` adapter has been officially released, and we will launch more adapters to interface with various tools in the Rstack. You can also refer to [Rstest - Adapters](https://rstest.rs/guide/integration/adapters) to write custom adapters.

#### Improved test feedback

Rstest has made several usability improvements for local development and debugging scenarios, making test feedback more intuitive:

- **Spot stuck tests earlier:** Rstest now supports marking test cases that have not completed for a long time during local runs. When the test process slows down, you can directly see which case is executing and may be stuck, instead of waiting blindly for the test to time out.

- **Clearer timeout failure feedback:** When a test fails due to timeout, Rstest now displays the number of executed assertions in the error message. This helps you quickly judge whether the test has been partially executed or is stuck in some asynchronous logic, thus locating the problem faster.

### Rspress 2.0 RC

#### SSG-MD feature

In front-end frameworks that rely on dynamic React rendering, static information is often difficult to extract, and Rspress also encountered the same problem. Rspress allows users to enhance document expressiveness through dynamic features such as [MDX fragments](https://v2.rspress.rs/guide/use-mdx/components), React components, Hooks, and TSX routes. However, these dynamic contents face several challenges when converted to Markdown text:

- Directly inputting MDX to AI will contain a lot of code syntax noise and lose React component content.
- Converting SSG-generated HTML to Markdown often yields poor results, and information quality is difficult to guarantee.

To solve this problem, Rspress 2.0 introduces the [SSG-MD](https://v2.rspress.rs/guide/basic/ssg-md) feature. This is a new rendering mode, as the name suggests, the key difference from traditional [Static Site Generation (SSG)](https://v2.rspress.rs/guide/basic/ssg) is that it renders your page into Markdown files instead of HTML files, and generates [llms.txt](https://llmstxt.org/) and llms-full.txt files. Compared to traditional approaches such as converting HTML to Markdown, SSG-MD has better information sources during rendering, such as React Virtual DOM, so it produces higher-quality static content with greater flexibility.

Enabling it is very simple:

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

export default defineConfig({
  llms: true,
});
```

The build will generate the following structure:

```
doc_build
├── llms.txt          # Summary version, containing key document index
├── llms-full.txt     # Full version, containing all document content
├── guide
│   └── start
│       └── introduction.md
└── ...
```

For custom components, you can control their rendering behavior in SSG-MD mode via environment variables:

```tsx
export function Tab({ label }: { label: string }) {
  if (import.meta.env.SSG_MD) {
    // Output plain text description in SSG-MD mode
    return <>{`**Tab: ${label}**`}</>;
  }
  // Normal interactive component rendering
  return <div className="tab">{label}</div>;
}
```

This preserves the interactive experience of the document and helps AI understand the semantic information of the components.

> For more details, refer to: [SSG-MD Guide](https://v2.rspress.rs/guide/basic/ssg-md)

## Upgrade guide

### Upgrade SWC plugins

If your project uses SWC Wasm plugins (such as `@swc/plugin-emotion`, etc.), upgrade the plugins to be compatible with `swc_core@54` or above, otherwise build failures or runtime exceptions may occur due to version incompatibility.

> For details, see [FAQ - SWC plugin version mismatch](/errors/swc-plugin-version.md).

### Remove deprecated configuration

- The following experimental options have been deprecated and can be directly removed:

```js title="rspack.config.mjs"
export default {
  // [!code --]
  experiments: {
    // [!code --]
    inlineConst: true,
    // [!code --]
    inlineEnum: true,
    // [!code --]
    typeReexportsPresence: true,
  },
};
```

- Adjust the position of the [collectTypeScriptInfo](/guide/features/builtin-swc-loader.md#collecttypescriptinfo) option in `builtin:swc-loader`, removing the `rspackExperiments` level:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.ts$/,
        loader: 'builtin:swc-loader',
        options: {
          // [!code --]
          rspackExperiments: {
            collectTypeScriptInfo: {
              exportedEnum: true,
              typeExports: true,
            },
            // [!code --]
          },
        },
      },
    ],
  },
};
```



---
url: /blog/announcing-1-6.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 1.6

_October 30, 2025_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

![Rspack 1.6](https://assets.rspack.rs/rspack/rspack-banner-v1-6.png)

***

We are excited to announce Rspack 1.6!

Notable changes include:

- New Features
  - [Enhanced tree shaking](#enhanced-tree-shaking)
  - [Support for import defer](#support-for-import-defer)
  - [Improved ESM output](#improved-esm-output)
  - [Optimized barrels by default](#optimized-barrels-by-default)
  - [Stabilized layers feature](#stabilized-layers-feature)
  - [Preserve JSX syntax](#preserve-jsx-syntax)
  - [Extract source map](#extract-source-map)
  - [Performance improvements](#performance-improvements)
- Rstack Progress
  - [Rsbuild 1.6](#rsbuild-16)
  - [Rspress v2 beta](#rspress-v2-beta)
  - [Rslib 0.16](#rslib-016)
  - [Rstest 0.6](#rstest-06)
  - [Rsdoctor 1.3](#rsdoctor-13)
- Ecosystem
  - [next-rspack](#next-rspack)

## New features

### Enhanced tree shaking

Rspack 1.6 improved tree shaking support for dynamic imports. In previous versions, Rspack could only perform tree shaking on destructured assignments within dynamic imports, while other import patterns were not analyzed.

Now, Rspack introduces comprehensive static analysis for dynamic imports. It can recognize and handle a wider range of usage patterns. This allows Rspack to precisely eliminate unused exports and further reduce the size of the final bundle.

```js
// Rspack 1.5 – Only supported destructured imports
const { value } = await import('./module');
console.log(value);

// Rspack 1.6 – Now supports the following cases
// Case 1
const mod = await import('./module');
const { value } = mod;
console.log(value);

// Case 2
const mod = await import('./module');
console.log(mod.value);

// Case 3
import('./module').then(({ value }) => {
  console.log(value);
});

// Case 4
import('./module').then((mod) => {
  const { value } = mod;
  console.log(value);
});

// Case 5
import('./module').then((mod) => {
  console.log(mod.value);
});
```

### Support for import defer

Rspack now supports the [import defer](https://github.com/tc39/proposal-defer-import-eval) syntax.

`import defer` is a new feature in JavaScript, which is also supported in [TypeScript 5.9](https://devblogs.microsoft.com/typescript/announcing-typescript-5-9-beta/#support-for-import-defer). It allows you to import a module without immediately executing the module and its dependencies, giving you better control over when code execution and side effects occur.

```js
import defer * as foo from './foo';
```

You can enable this feature through [experiments.deferImport](/config/experiments.md#experimentsdeferimport):

```js title="rspack.config.mjs"
export default {
  experiments: {
    deferImport: true,
  },
};
```

> Currently, Rspack only supports the `import defer` syntax. The function form `import.defer()` will be implemented in future versions.

### Improved ESM output

Optimizing ESM output has long been one of the key challenges faced by Rspack. Previously, we relied on [module concatenation](/config/optimization.md#optimizationconcatenatemodules) to optimize ESM outputs, but that approach had several limitations:

- **Impure output** – The generated files contained Rspack's runtime code.
- **Prone to errors** – Some modules could not be correctly concatenated, leading to unexpected runtime issues.
- **Limited code-splitting support** – Split bundles became complex and difficult to analyze or optimize statically.

To address these issues once and for all, we introduced an experimental plugin called [EsmLibraryPlugin](https://v1.rspack.rs/plugins/rspack/esm-library-plugin), purpose-built for constructing clean and efficient ESM libraries:

- **Full control over the bundling process** – All modules are linked during compilation, eliminating reliance on Rspack's runtime.
- **Code-splitting support** – Code after splitting can be statically analyzed and is tree-shaking friendly.

The image below compares the code splitting output before and after using this plugin — the left side shows the previous output, while the right side shows the cleaner output produced by EsmLibraryPlugin:

![Rspack 1.6 ESM output diff](https://assets.rspack.rs/rspack/assets/rspack-v1-6-esm-diff.png)

The EsmLibraryPlugin is now largely complete and is being integrated into Rslib to provide an out-of-the-box experience. You can also enable it manually with the following configuration:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.experiments.EsmLibraryPlugin()],
  optimization: {
    // Recommended to enable; otherwise, consumers must import runtime code from the entry.
    runtimeChunk: true,
  },
};
```

In addition, we've introduced an `preserveModules` option that preserves the original directory structure of your source files in the output:

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  plugins: [
    new rspack.experiments.EsmLibraryPlugin({
      preserveModules: path.resolve(import.meta.dirname, './src'),
    }),
  ],
};
```

### Optimized barrels by default

In Rspack 1.5, we introduced the experimental [lazyBarrel](/guide/advanced/lazy-barrel.md) optimization feature, specifically designed to improve the build performance of barrel files. After a period of production environment practice and user feedback collection, we confirmed that the lazyBarrel feature has reached a stable state, so it is enabled by default in Rspack 1.6.

:::info
What are barrel files? Barrel files are files that are primarily used to re-export content from other modules, typically used to simplify import paths and provide a unified API entry point.
:::

### Stabilized layers feature

Layer is a feature for organizing modules into different layers, which can be useful in advanced scenarios such as React Server Components. By assigning different layers to modules, you can gain finer control over their build behavior, for example:

- Compiling modules in different layers for different target environments
- Outputting them to separate build directories

Starting from Rspack 1.6, the layer feature has become stable enough that the experimental flag [experiments.layers](/guide/advanced/layer.md) has been deprecated. You can now use the layer feature directly without the experimental flag.

For more details and practical examples, check out our new [Module layers guide](/guide/advanced/layer.md).

### Preserve JSX syntax

Rspack now supports preserving JSX syntax in the build output. When this option is enabled, Rspack only parses JSX syntax without transforming it into JavaScript.

This feature is especially useful when building libraries that rely on JSX. For example, when using Rslib to build a component library, you can choose to keep the JSX code as-is in the output, allowing the consumer to handle the final JSX transformation during usage.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        jsx: true, // Enable JSX parsing
      },
    },
    rules: [
      {
        test: /\.jsx?$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: { jsx: true },
              transform: {
                // Preserve JSX syntax
                react: { runtime: 'preserve' },
              },
            },
          },
        },
      },
    ],
  },
};
```

### Extract source map

Rspack now supports extracting existing source map data from files (from their `//# sourceMappingURL` comments) through [rules\[\].extractSourceMap](/config/module-rules.md#rulesextractsourcemap). This feature is particularly useful for preserving source maps provided by third-party libraries, ensuring that debugging information remains accurate even when these libraries are bundled or transformed.

This feature was introduced as a built-in alternative to [source-map-loader](https://github.com/webpack-contrib/source-map-loader), providing better performance and tighter integration with the build process.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.m?js$/,
        extractSourceMap: true,
      },
    ],
  },
};
```

### Performance improvements

Rspack 1.6 introduces several performance optimizations. Compared with Rspack 1.5.0, you can expect the following improvements:

- CLI startup is about **50 ms faster**
- Building 10000 React components is **11% faster**
- Building multiple UI component libraries is **31% faster** (thanks to the newly enabled barrel-file optimization by default)

> Data source: [Rspack benchmark](https://github.com/rstackjs/build-tools-performance)

## Rstack progress

[Rstack](/guide/start/ecosystem.md#rstack) is a unified JavaScript toolchain centered around Rspack, featuring excellent performance and consistent architecture.

### Rsbuild 1.6

#### Forward browser logs

Rsbuild now automatically forwards error logs from the browser to the terminal, helping you conveniently view runtime errors during development. This also enables Coding Agents to obtain more complete context from terminal logs, allowing them to better analyze and locate errors.

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

If you don't need this feature, you can disable it by setting [dev.browserLogs](https://rsbuild.rs/config/dev/browser-logs) to false:

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

#### Building ESM applications

Rsbuild now supports building ES Modules format output for Web applications, simply enable [output.module: true](https://rsbuild.rs/config/output/module):

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

Once enabled, Rsbuild will no longer generate IIFE format scripts by default, but will output standard ESM format and automatically set the generated `<script>` tags to `type="module"`.

#### Faster configuration loading

Since Node.js 22 already natively supports TypeScript, Rsbuild now defaults to using Node.js's native loader to parse configuration files; if loading fails, it will automatically fall back to [Jiti](https://github.com/unjs/jiti). When using Node.js 22 and above, this mechanism ensures that module resolution behavior remains consistent with Node.js native behavior while providing better loading performance.

You can also manually specify the loading method through the Rsbuild CLI's --config-loader option:

```bash
# Force use of native loading
rsbuild build --config-loader native

# Force use of jiti loading
rsbuild build --config-loader jiti
```

### Rspress v2 beta

#### New theme preview

Rspress's new theme has entered preview phase and is now live on the v2 website. 🎉

The new theme has been comprehensively upgraded in design, bringing a better documentation reading experience. It also exposes more theme APIs and CSS class names, making it easier for developers to customize the UI.

> 👉 Visit the [Rspress v2 website](https://v2.rspress.rs/) to try it out.

![rspress-v2-theme](https://assets.rspack.rs/rspack/assets/rspack-v1-6-rspress.gif)

#### Sub-page switching

Rspress v2 introduces the [PageTabs](https://v2.rspress.rs/ui/components/page-tabs) component, allowing you to create multiple sub-tabs within a single page. This helps naturally split long content into well-structured subpages.

![Rspress sub-page switching](https://assets.rspack.rs/rspack/assets/rspack-v1-6-page-tabs.png)

### Rslib 0.16

#### Faster type generation

Rslib now supports generating type declaration files based on [typescript-go](https://github.com/microsoft/typescript-go). By simply enabling [dts.tsgo](https://rslib.rs/config/lib/dts#dtstsgo), you can boost type checking and declaration generation performance by around **300%**, with even greater benefits in large projects.

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

#### Preserve JSX syntax

Rslib now supports preserving original JSX in build output, simply set runtime to [`'preserve'`](https://rsbuild.rs/plugins/list/plugin-react#preserve). In this mode, JSX syntax will be preserved as-is without any transformation, making it convenient for subsequent processing by other bundling tools.

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

export default {
  lib: [
    {
      bundle: false,
      format: 'esm',
    },
  ],
  plugins: [
    pluginReact({
      swcReactOptions: {
        runtime: 'preserve',
      },
    }),
  ],
};
```

#### More CLI options

Rslib supports additional [CLI options](https://rslib.rs/guide/basic/cli#rslib-build) in the build command, which take precedence over configuration files.

```json title="package.json"
{
  "scripts": {
    "build": "rslib build --entry index.ts --minify --tsconfig tsconfig.build.json"
  }
}
```

This also allows you to use Rslib without a configuration file, and the CLI will automatically use a default configuration containing only a single [lib](https://rslib.rs/config/lib/) and complete the build based on command line parameters.

### Rstest 0.6

#### VS Code extension

The [Rstest VS Code Extension](https://marketplace.visualstudio.com/items?itemName=rstack.rstest) is now available. It allows you to discover, run, and debug tests directly within the editor, helping you efficiently manage test cases and quickly review test results.

![rstest-vscode-extension](https://assets.rspack.rs/rspack/assets/rspack-v1-6-rstest-vscode-ext.gif)

#### Coverage support

Rstest now supports collecting code coverage using Istanbul and generating detailed coverage reports. For more information, see [Rstest – Coverage](https://rstest.rs/config/test/coverage).

![rstest-coverage](https://assets.rspack.rs/rspack/assets/rspack-v1-6-rstest-cov.png)

### Rsdoctor 1.3

#### Rsdoctor GitHub Actions

Rsdoctor now provides a [GitHub bundle diff action](https://github.com/web-infra-dev/rsdoctor-action), which automatically detects and compares bundle size changes during the CI phase. This helps teams identify and prevent bundle size regressions early.

![Rsdoctor GitHub Actions](https://assets.rspack.rs/rspack/assets/rspack-v1-6-bundle-diff.png)

#### All-in-one JSON report

Rsdoctor now supports exporting a [all-in-one JSON report file](https://rsdoctor.rs/config/options/output#mode-brief) in Brief mode. This file can be easily stored, shared, or used for further data analysis. In addition, we’ve introduced a new [Playground page](https://rsdoctor.rs/guide/start/playground), where developers can upload the JSON report to reopen and visually explore the analysis results.

## Ecosystem

### next-rspack

In Next.js 16, next-rspack has integrated Rspack's [custom Rust binding solution](https://github.com/rstackjs/rspack-binding-template), delivering significant performance gains:

- 24% faster build performance
- 10% faster dev performance

In this customized Rspack Rust binding, the `externals` logic from Next.js has been moved to the Rust side, greatly reducing communication overhead between JavaScript and Rust.

| Tool                  | Build time (no cache) | Dev time (no cache) |
| --------------------- | --------------------- | ------------------- |
| Rspack (next\@16.0.0) | 3.8s                  | 1.7s                |
| Rspack (next\@15.4.0) | 5.0s                  | 1.9s                |
| webpack               | 14.0s                 | 7.8s                |

The benchmark is based on the [chakra-ui-docs](https://github.com/SyMind/chakra-ui-docs/tree/next-rspack) repository. Full performance data is available here: [PERF.md](https://github.com/SyMind/chakra-ui-docs/blob/next-rspack/PERF.md).

## Upgrade guide

### Upgrade SWC plugins

If your project uses SWC Wasm plugins (such as `@swc/plugin-emotion`), you need to upgrade the plugins to a version compatible with `swc_core@46`, otherwise it may cause build errors due to version incompatibility.

> For more details, see [FAQ - SWC plugin version mismatch](/errors/swc-plugin-version.md).

### Remove `experiments.layer`

`experiments.layer` option has been deprecated, you can remove it directly:

```diff title="rspack.config.mjs"
export default {
-  experiments: {
-   layer: true,
-  },
};
```



---
url: /blog/announcing-1-5.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 1.5

_August 26, 2025_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

![Rspack 1.5](https://assets.rspack.rs/rspack/rspack-banner-v1-5.png)

***

We're excited to announce Rspack 1.5!

Notable changes include:

- New features
  - [Barrel file optimization](#barrel-file-optimization)
  - [Faster file system watcher](#faster-file-system-watcher)
  - [Improved browser support](#improved-browser-support)
  - [Extending Rspack with Rust](#extending-rspack-with-rust)
  - [Const inline optimization](#const-inline-optimization)
  - [Type re-export analysis](#type-re-export-analysis)
  - [Built-in virtual modules plugin](#built-in-virtual-modules-plugin)
  - [Module Federation runtime hoisting](#module-federation-runtime-hoisting)
  - [Installation size optimization](#installation-size-optimization)
  - [Seal phase performance optimization](#seal-phase-performance-optimization)
- Misc
  - [Drop support for Node.js 16](#drop-support-for-nodejs-16)
  - [Resolver JavaScript API](#resolver-javascript-api)
- Rstack progress
  - [Rslint released](#rslint-released)
  - [Rsbuild 1.5](#rsbuild-15)
  - [Rslib 0.12](#rslib-012)
  - [Rspress 2.0 beta](#rspress-20-beta)
  - [Rsdoctor 1.2](#rsdoctor-12)
  - [Rstest 0.2](#rstest-02)

## New features

### Barrel file optimization

A **barrel file** is a common module export pattern that re-exports multiple modules through a single entry file, typically named `index.js` or `index.ts`. For example:

```js
export { Button, Tab } from './components';
export * as utils from './utils';
export * from './hooks';
```

While this pattern simplifies module imports, it can introduce performance overhead during the build process: when importing a single module from a barrel file, Rspack must resolve and build all modules referenced by the barrel file, even if only a small subset is actually used.

To address this, Rspack 1.5 introduces the experimental [lazyBarrel](/guide/advanced/lazy-barrel.md) feature. This optimization automatically detects side-effect free barrel files and defers building their re-exports until actually needed. Modules are only resolved and built when actually needed, significantly reducing unnecessary module resolution and build costs.

This is particularly effective for projects with many barrel files, significantly improving build performance.

```js title="rspack.config.mjs"
export default {
  experiments: {
    lazyBarrel: true,
  },
};
```

Real-world benchmarks show that barrel file optimization delivers substantial performance gains across applications at different scales:

- [Benchmark](https://github.com/rstackjs/build-tools-performance/tree/main/cases/ui-components):

| Metric             | Before |  After | Improvement |
| ------------------ | -----: | -----: | ----------: |
| Build Time         |  1.47s |  1.19s |      `-20%` |
| Module Resolutions | 39,675 | 20,071 |      `-49%` |
| Module Builds      |  9,358 |  5,062 |      `-46%` |

- An application from ByteDance:

| Metric             |  Before |   After | Improvement |
| ------------------ | ------: | ------: | ----------: |
| Build Time         |   17.9s |   16.0s |      `-10%` |
| Module Resolutions | 181,078 | 137,232 |      `-24%` |
| Module Builds      |  38,046 |  29,405 |      `-23%` |

Barrel file optimization is enabled by default in Rsbuild 1.5, and we plan to make it the default for all projects in Rspack 1.6.

For more details, see the [experiments.lazyBarrel documentation](/guide/advanced/lazy-barrel.md).

### Faster file system watcher

Previously, Rspack relied on the [watchpack](https://github.com/webpack/watchpack) file system watcher to track file changes. However, we identified performance bottlenecks with `watchpack`. For example, each file change triggers the creation of a new instance, consuming significant CPU and memory in large projects (see [#7490](https://github.com/web-infra-dev/rspack/issues/7490)).

To address this, we built a native file system watcher in Rust, offering the following benefits:

- **High performance**: HMR performance improvements of up to 50%
- **Incremental updates**: Only processes files that actually change
- **Persistent runtime**: Runs continuously throughout development without reinitialization

You can try out the new watcher by enabling [experiments.nativeWatcher](/config/experiments.md#experimentsnativewatcher):

```js title="rspack.config.mjs"
export default {
  experiments: {
    nativeWatcher: true,
  },
  watchOptions: {
    // Other watch options...
  },
};
```

### Improved browser support

In Rspack 1.4, we officially introduced Wasm target support, enabling Rspack to run in browser-based environments powered by WebContainers, such as [StackBlitz](https://stackblitz.com/).

With the release of [@rspack/browser](/api/javascript-api/browser.md), you can now run Rspack directly in any modern browser without relying on WebContainers or specific platforms.

`@rspack/browser` is designed specifically for pure browser environments, providing core bundling capabilities for web projects. It offers a lightweight way to reproduce issues, share configurations, and help developers get started with Rspack through interactive online demos.

![rspack-web-repl](https://assets.rspack.rs/rspack/assets/rspack-v1-5-repl.rspack.png)

The API of `@rspack/browser` is aligned with the JavaScript API of `@rspack/core`, with additional features and APIs tailored for browser environments.

```js
import { rspack, builtinMemFs } from '@rspack/browser';

// Write files to memfs
builtinMemFs.volume.fromJSON({
  // ...project files
});

// Just like using JavaScript API of @rspack/core
rspack({}, (err, stats) => {
  if (err || stats.hasErrors()) {
    // ...
  }
  // Get output from memfs after bundling
  const files = builtinMemFs.volume.toJSON();
});
```

`@rspack/browser` is currently in an experimental stage and may introduce breaking changes. We will continue to enhance its capabilities for online bundling scenarios. In the meantime, Welcome to try it out at the [Rspack Playground](https://playground.rspack.rs/).

### Extending Rspack with Rust

You can now extend Rspack directly using Rust! With our provided repository template, you can build custom Rust plugins and loaders, and even replace Rspack's default native binding.

In JavaScript plugins, data transfer and type conversion between Rust and JavaScript can introduce performance overhead. By customizing Rspack's binding, your code can integrate directly with the Rspack Rust core, eliminating cross-language communication costs while retaining full support for all Rspack JavaScript APIs.

This approach is particularly suitable for replacing hooks that frequently interact with Rust (such as `compilation.hooks.processAssets`) and for compute-intensive custom loaders, where it can deliver significant build performance improvements.

Key benefits:

- **Native performance** — Extensions written in Rust run with the same native performance as the Rspack Rust core.
- **Full compatibility** — Retains all existing JavaScript APIs without requiring changes to your project.
- **Developer-friendly** — The official template includes a complete development environment and publishing workflow.

You can get started quickly with the [official template](https://github.com/rstackjs/rspack-binding-template). For more details, see the [design rationale](https://rstackjs.github.io/rspack-rust-book/custom-binding/getting-started/rationale.html). Note that this approach introduces additional maintenance costs and is recommended only when extreme performance optimization is required.

### Const inline optimization

When organizing project code, it is common to centralize constants into files such as `constants.js` or, in TypeScript projects, into `types.ts` files containing enums.

Rspack introduces two experimental features — [experiments.inlineConst](/config/optimization.md#optimizationinlineexports) and [experiments.inlineEnum](/config/optimization.md#optimizationinlineexports) — that perform **cross-module inlining optimizations for constants**. These optimizations help minifiers perform more accurate static analysis, eliminate unused code branches, and further reduce bundle size.

For example, `inlineConst` can inline constants defined in leaf modules of the module graph across modules, as shown below:

```js
// font-settings.js
export const bold = 0b001;
export const italic = 0b010;

// index.js
import { bold, italic } from './font-settings';

// MY_FONT is defined by DefinePlugin({ FONT: 0b001 })
const fontStyle = {};
if (MY_FONT & bold) fontStyle['font-weight'] = 'bold';
if (MY_FONT & italic) fontStyle['font-style'] = 'italic';
applyFont(fontStyle);
```

With `inlineConst` enabled, the `if` branches in the example can be clearly optimized by minifier, generating more streamlined output:

```js
(() => {
  'use strict';
  let t = {};
  t['font-weight'] = 'bold';
  applyFont(t);
})();
```

> For more details, see the [experiments.inlineConst documentation](/config/optimization.md#optimizationinlineexports). This feature is planned to be enabled by default in v1.6.

`inlineEnum` performs **cross-module inlining optimization for TypeScript enums**, working in a similar way to `inlineConst`.

```ts
// types.ts
export enum Kind {
  A,
  B,
}
// index.ts
import { Kind } from './types.ts';
console.log(Kind.A);
```

With `inlineEnum` enabled:

```js
(() => {
  console.log(0);
})();
```

Note that when `inlineEnum` is enabled, Rspack will inline all enums by default.
If you only want to inline `const enums`, please refer to this [example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/inline-const-enum).

> For more details, see the [experiments.inlineEnum documentation](/config/optimization.md#optimizationinlineexports).

### Type re-export analysis

In TypeScript projects, type re-exports are a common pattern:

```ts
// index.ts
export { MyType } from './types.ts';

// types.ts
export type MyType = {
  name: string;
};
```

In previous versions, if you re-exported a type without adding the `type` modifier, Rspack could throw a warning such as: `export 'MyType' (reexported as 'MyType') was not found`.

This happened because Rspack processed each module in isolation. As a result, a type export (like `MyType` in the example) could be mistakenly treated as a value. Since no corresponding value export was found in `./types.ts`, the warning was triggered.

Rspack 1.5 introduces the [experiments.typeReexportsPresence](/config/module-parser.md#javascripttypereexportspresence) option, which improves the detection of TypeScript type exports. With this option enabled, Rspack can correctly recognize type re-exports across modules, preventing false warnings.

> For more details, see the [experiments.typeReexportsPresence documentation](/config/module-parser.md#javascripttypereexportspresence).

### Built-in virtual modules plugin

In Rspack 1.4, we introduced [custom InputFileSystem](/blog/announcing-1-4.md#custom-input-file-system), which combined with the `webpack-virtual-modules` plugin, enabled support for virtual modules. However, this approach still had performance bottlenecks when dealing with a large number of virtual modules.

To address this, Rspack 1.5 adds a built-in [VirtualModulesPlugin](/plugins/virtual-modules-plugin.md).

This plugin is implemented in Rust and moves the storage and management of virtual modules to the Rust layer. This reduces module read and parse overhead. As a result, it delivers significantly better performance when handling large volumes of virtual modules.

The `VirtualModulesPlugin` retains API compatibility with `webpack-virtual-modules`, making migration straightforward:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.experiments.VirtualModulesPlugin({
      'src/generated/config.js': 'export default { version: "1.0.0" };',
    }),
  ],
};
```

> Thanks to our contributor [@nilptr](https://github.com/nilptr) for his great [work](https://github.com/web-infra-dev/rspack/pull/11021).

### Module Federation runtime hoisting

Previously, the Module Federation runtime was bootstrapped by patching the entry module.
In the new version, the Module Federation plugin integrates its runtime code directly with Rspack's runtime and elevates it into the runtime chunk.
This ensures that the Module Federation runtime is prepared before the application starts.

This change brings the following benefits:

1. Reduced bundle size in multi-entry scenarios
2. Fixed initialization errors related to Module Federation
3. Support for extracting the Module Federation runtime into the runtime chunk
4. A new hook-based plugin system for extensibility

The table below shows bundle size optimizations in a demo project using the new Module Federation plugin:

| Configuration                             | Before | After | Reduction |
| :---------------------------------------- | -----: | ----: | --------: |
| Multiple Entries (default)                |  210kb | 210kb |      `0%` |
| Multiple Entries + runtimeChunk: true     |  210kb | 150kb |     `29%` |
| Multiple Entries + runtimeChunk: 'single' |  210kb |  70kb |     `67%` |

More details about this change can be found [here](https://gist.github.com/ScriptedAlchemy/a71ccbdfb933e8a4cd0131801a2c26b5#file-hoisted-runtime-internal-md),

### Installation size optimization

Since v1.4, we have delivered several key optimizations to reduce Rspack's installation size, decreasing the size from `63.7MB` in Rspack 1.4.0 to `49.9MB` in Rspack 1.5.0.

![binary-size-by-dates](https://assets.rspack.rs/rspack/assets/rspack-v1-5-rspack-install-size.png)

Some of the most impactful optimizations include:

- **5 MB reduction** through [compiler parameter adjustments](https://github.com/web-infra-dev/rspack/pull/11077)
- **3 MB reduction** by optimizing upstream dependencies ([wasmer](https://github.com/wasmerio/wasmer/pull/5621/files), [SWC](https://github.com/swc-project/swc/pull/10638))
- **2 MB reduction** via [feature flag optimization](https://github.com/web-infra-dev/rspack/pull/10965)
- **2 MB reduction** through [browserslist-rs](https://github.com/browserslist/browserslist-rs/pull/32) data structure improvements

To further optimize installation size, we have integrated [automated size checks](https://github.com/web-infra-dev/rspack/blob/main/.github/actions/binary-limit/action.yml) into our daily workflow to continuously monitor changes in this metric.

### Seal phase performance optimization

In terms of build performance, Rspack 1.5 delivers major optimizations to the Seal phase (the stage responsible for code generation and optimization).
By improving data structures, increasing parallelism, and introducing hot code caching, Rspack significantly improves build efficiency for large projects. Thanks to parallelization, the performance gains are even more pronounced on multi-core machines.

For example, in a large-scale application at ByteDance containing approximately 40,000 modules, the overall Seal phase time was reduced by **around 50%**, with substantial improvements observed across all major sub-stages:

| Phase                    | v1.4.0 | v1.5.0 | Improvement |
| ------------------------ | -----: | -----: | ----------: |
| Flag dependency exports  |  394ms |  181ms |      `-54%` |
| Flag dependency usage    | 1828ms |  454ms |      `-75%` |
| Code splitting           | 2019ms |  777ms |      `-62%` |
| Bundle splitting         | 1588ms |  712ms |      `-55%` |
| Module concatenation     | 2645ms |  616ms |      `-76%` |
| Content hash calculation |  881ms |  404ms |      `-54%` |

## Misc

### Drop support for Node.js 16

Since Node.js 16 reached its end of life on September 11, 2023, and many community packages (such as `webpack-dev-server`, `css-loader`, `sass-loader`, etc.) have dropped support for Node.js 16, **Rspack 1.5 drops support for Node.js 16** to reduce maintenance costs.

Node.js version requirements for each package:

| Package            |        v1.4 |        v1.5 |
| ------------------ | ----------: | ----------: |
| @rspack/core       |  `>=16.0.0` | `>=18.12.0` |
| @rspack/cli        | `>=18.12.0` | `>=18.12.0` |
| @rspack/dev-server | `>=18.12.0` | `>=18.12.0` |
| @rsbuild/core      | `>=16.10.0` | `>=18.12.0` |

:::tip
⚠️ This is a breaking change. If you are currently using Node.js 16, you will need to upgrade to Node.js 18.12.0 or higher in order to use Rspack 1.5.
:::

For projects still running on Node.js 16, please follow these steps to upgrade:

1. **Upgrade Node.js version**: We recommend upgrading to Node.js 18.12.0 or later (Node.js 22 LTS is recommended).
2. **Update CI/CD configuration**: Ensure your continuous integration setup is updated to use a compatible Node.js version.

### Resolver JavaScript API

To make it easier for our users to leverage Rspack's module resolution capabilities, we have integrated [rspack-resolver](https://github.com/rstackjs/rspack-resolver) into the Rspack JavaScript API.
It provides module resolution functionality similar to [enhanced-resolve](https://github.com/webpack/enhanced-resolve).

For usage details, please refer to the [Resolver API documentation](/api/javascript-api/resolver.md#resolver-api).

### Stabilization of lazy compilation

After extensive validation, the [experiments.lazyCompilation](/config/lazy-compilation.md) option has been promoted from an experimental feature to a stable feature, and is now available at the top level of the Rspack configuration:

```diff title="rspack.config.mjs"
export default {
- experiments: {
-   lazyCompilation: true,
- },
+ lazyCompilation: true,
};
```

The previous experiments.lazyCompilation option will continue to work, but will emit a deprecation warning.

### Deprecated options

The Rspack [experiments.topLevelAwait](/guide/migration/rspack_1.x.md#other-experimental-configuration-changes) option was used to control support for top-level await, and it has always been enabled by default.
After careful observation, we found no real-world scenarios where disabling top-level await was necessary.

As a result, this option has been deprecated and is planned for removal in Rspack 2.0, at that point top-level await support can no longer be disabled.

## Rstack progress

[Rstack](/guide/start/ecosystem.md#rstack) is a unified JavaScript toolchain centered on Rspack, with high performance and consistent architecture.

### Rslint released

![rslint-banner](https://assets.rspack.rs/rslint/rslint-banner.png)

We are excited to announce the release of [Rslint](https://rslint.rs/)!

Rslint is a next-generation, TypeScript-first linter, written in Go and powered by the type-checking capabilities of typescript-go.

It originates from [tsgolint](https://github.com/typescript-eslint/tsgolint), created by [@auvred](https://github.com/auvred), and has since been extended and optimized to deliver a more powerful linting experience.

Key features of Rslint include:

- **ESLint-style configuration and directives**: almost seamless adoption
- **IDE support**: VS Code extension available, with support for Cursor, Trae, and more
- **Auto-fix**: resolve issues instantly with `rslint --fix`
- **Rule support**: 50+ `@typescript-eslint` rules already implemented
- **Test validation**: runs the original `typescript-eslint` test suite to ensure rule correctness

Rslint is still in its early stage of development, and we are actively working on expanding its feature set and rule support.

We encourage you to try it out and provide feedback to help us improve Rslint together!

### Rsbuild 1.5

Providing an out-of-the-box experience has always been a core design principle of Rsbuild. In Rsbuild 1.5, we have enabled several of Rspack's latest features by default, delivering improved build performance, including:

- Enabled [lazyCompilation](/config/lazy-compilation.md) to compile dynamically imported modules on demand, improving development server startup speed.
- Enabled [lazyBarrel](/guide/advanced/lazy-barrel.md) to optimize the build performance of barrel files and reduce unnecessary module resolution.
- Enabled [inlineEnum](/config/optimization.md#optimizationinlineexports) to inline TypeScript enums, reducing the bundle size after compilation.
- Enabled [typeReexportsPresence](/config/module-parser.md#javascripttypereexportspresence) to correctly detect TypeScript type re-exports, improving type handling accuracy.

> Once you upgrade to the latest version of Rsbuild, these features are enabled by default with no additional configuration required.

Rsbuild 1.5 also introduces the new [output.module](https://rsbuild.rs/config/output/module) option, which allows generating build outputs in the ES modules format.

Currently, this option provides ESM format support for Node.js bundles. We plan to extend support to web applications in future releases.

```ts title="rsbuild.config.ts"
export default {
  output: {
    target: 'node',
    module: true,
  },
};
```

### Rslib 0.12

In Rslib 0.12, we have integrated the Rstest testing framework into the project template. If needed, you can use Rstest to test your library projects, enabling development and testing through a unified Rstack toolchain.

![Using Rstest](https://assets.rspack.rs/rspack/assets/rspack-v1-5-rslib-using-rstest.png)

In addition, we are actively designing and developing a new ESM output generation strategy, aiming to deliver ESM output quality comparable to tools like esbuild and Rollup, while keeping webpack-compatible interop behavior to ensure correctness. See [interop tests](https://jserfeng.github.io/interop-test/by-test-case) for details.

### Rspress 2.0 beta

Rspress 2.0 is now in beta, with development nearing completion. We plan to release the stable version within the next two months.

The latest beta introduces a Markdown text copy component, making it easier for users to provide documentation content to large language models for analysis and processing. You can try out this feature on various Rstack documentation sites:

![plugin-llms Demo](https://assets.rspack.rs/rspack/assets/rspack-v1-5-rspress-plugin-llms-ui.png)

> This feature is powered by the @rspress/plugin-llms plugin, which automatically generates files compliant with the [llms.txt](https://llmstxt.org/) standard. For usage details, please refer to the [@rspress/plugin-llms documentation](https://v2.rspress.rs/plugin/official-plugins/llms).

### Rsdoctor 1.2

Rsdoctor 1.2 introduces several significant updates, including precise analysis of concatenated modules and an all-new Treemap visualization. These enhancements improve both the accuracy of build artifact analysis and the visualization experience, helping you better understand and optimize your project bundles.

Read more in the [Rsdoctor 1.2 release blog](https://rsdoctor.rs/blog/release/release-note-1_2).

### Rstest 0.2

After two months of continuous iteration and over 10 rounds of optimization, Rstest 0.2 delivers substantial improvements in both functionality and stability. This release introduces the following key enhancements:

- **Mock API**: Rstest now includes a comprehensive [mock API](https://rstest.rs/api/runtime-api/rstest/mock-modules), enabling developers to replace actual module implementations in test environments, with full support for mocking ES modules.
- **Enhanced Watch Mode**: Watch mode now supports incremental re-runs. When a test file or its dependencies change, Rstest intelligently re-executes only the affected tests, significantly improving testing efficiency.
- **CLI Shortcuts**: Watch mode also introduces keyboard shortcuts, allowing developers to perform common actions more quickly and seamlessly.

![Rstest Shortcuts](https://assets.rspack.rs/rspack/assets/rspack-v1-5-rstest-cli-shortcuts.png)



---
url: /blog/announcing-1-4.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 1.4

_June 26, 2025_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

![Rspack 1.4](https://assets.rspack.rs/rspack/rspack-banner-v1-4.png)

***

Rspack 1.4 has been released!

Notable changes:

- New features
  - [Running in the browser](#running-in-the-browser)
  - [Faster SWC](#faster-swc)
  - [Smaller bundles](#smaller-bundles)
  - [Incremental build by default](#incremental-build-by-default)
  - [New CssChunkingPlugin](#new-csschunkingplugin)
  - [Enhanced lazy compilation](#enhanced-lazy-compilation)
  - [Custom input file system](#custom-input-file-system)
  - [Performance analysis tool](#performance-analysis-tool)
- Rstack progress
  - [Rsbuild 1.4](#rsbuild-14)
  - [Rslib 0.10](#rslib-010)
  - [Rspress 2.0 beta](#rspress-20-beta)
  - [Rsdoctor MCP](#rsdoctor-mcp)
  - [Rstest released](#rstest-released)
- Ecosystem
  - [next-rspack](#next-rspack)
  - [Kmi](#kmi)
- Upgrade guide

## New features

### Running in the browser

Starting with Rspack 1.4, we have added Wasm target support, which means Rspack can now run in browser environments, including online platforms like [StackBlitz](https://stackblitz.com/) ([WebContainers](https://blog.stackblitz.com/posts/introducing-webcontainers/)). This enables developers to quickly create prototypes and share code examples without having to configure local environments.

You can try our [online example](https://stackblitz.com/~/github.com/rstackjs/rsbuild-stackblitz-example) directly.


In future versions, we will continue to optimize the Wasm version's usability and bundle size.

We are also developing the `@rspack/browser` package, which is a browser-specific version of Rspack, allowing you to use Rspack directly in any modern browser without relying on WebContainers or specific platforms.

### Faster SWC

Over the past few months, we have been continuously collaborating with the SWC team to optimize the performance and reliability of the JavaScript toolchain. After a period of optimization, we are pleased to see that SWC's performance has improved significantly, benefiting both Rspack users and all SWC-based tools:

- JavaScript parser is **30%-35%** faster
- JavaScript minifier is **10%** faster

![SWC benchmark](https://assets.rspack.rs/rspack/assets/rspack-v1-4-swc-benchmark.png)
> The above data is from: [CodSpeed - SWC](https://codspeed.io/swc-project/swc), compared against SWC 16 used by Rspack 1.3 as the baseline.

### Smaller bundles

SWC has enhanced its dead code elimination (DCE) capabilities in the current version, which combined with Rspack's powerful [tree shaking](/guide/optimization/tree-shaking.md) functionality, enables Rspack 1.4 to generate smaller bundles.

We tested this using `react-router` as an example: by importing only part of its exports in the source code and then comparing the build outputs from different bundlers, we found that Rspack generates the smallest bundles.

```js title="src/index.js"
import { BrowserRouter, Routes, Route } from 'react-router';

console.log(BrowserRouter, Routes, Route);
```

The output bundle sizes by different bundlers are as follows:

| Bundler          | Minified Size | Min+Gzipped Size |
| ---------------- | ------------- | ---------------- |
| Rspack (Rsbuild) | **36.35 kB**  | **13.26 kB**     |
| webpack          | 36.96 kB      | 13.37 kB         |
| Vite             | 42.67 kB      | 15.67 kB         |
| Rolldown         | 42.74 kB      | 15.17 kB         |
| Rolldown Vite    | 43.42 kB      | 15.46 kB         |
| Farm             | 43.42 kB      | 15.63 kB         |
| Parcel           | 44.62 kB      | 16.07 kB         |
| esbuild          | 46.12 kB      | 16.63 kB         |
| Bun              | 57.73 kB      | 20.8 kB          |

> Data from [react-router-tree-shaking-compare](https://github.com/chenjiahan/react-router-tree-shaking-compare).

### Incremental build by default

After extensive optimization, Rspack's incremental build has become stable. In Rspack 1.4, we've enabled incremental build for all phases by default, which significantly speeds up rebuilds - HMR performance typically improves by **30%-40%**, depending on the project.

Here is a performance comparison from one user after enabling incremental build:

![incremental benchmark](https://assets.rspack.rs/rspack/assets/rspack-v1-4-incremental-data.png)
If you need to revert to the previous behavior, you can set [experiments.incremental](/config/deprecated-options.md#experimentsincremental) to `'safe'`. However, we recommend that most projects use the new default configuration to achieve optimal performance.

```js title="rspack.config.mjs"
export default {
  experiments: {
    // Revert to previous behavior
    incremental: 'safe',
  },
};
```

### New CssChunkingPlugin

Rspack 1.4 introduces an experimental [CssChunkingPlugin](/plugins/css-chunking-plugin.md) specifically designed for handling CSS code splitting. This plugin ensures that styles are loaded in the same order as they are imported in the source code, preventing UI issues caused by incorrect CSS loading order.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.experiments.CssChunkingPlugin({
      // ...options
    }),
  ],
};
```

Once `CssChunkingPlugin` is enabled, CSS code splitting will be handled entirely by this plugin, and the `optimization.splitChunks` configuration will no longer affect CSS modules. You can check the [documentation](/plugins/css-chunking-plugin.md) for more details.

> This plugin is inspired by Next.js's [CSS Chunking](https://nextjs.org/docs/app/api-reference/config/next-config-js/cssChunking) feature. Thanks to the Next.js team for their innovation in this area.

### Enhanced lazy compilation

Rspack now supports enabling lazy compilation with `MultiCompiler`, which means that when you use multiple Rspack configurations in a single build, you can independently configure the [lazyCompilation options](/config/lazy-compilation.md) for each compiler instance.

```js title="rspack.config.mjs"
export default [
  {
    target: 'web',
    experiments: {
      // enable lazy compilation for client
      lazyCompilation: true,
    },
  },
  {
    target: 'node',
    experiments: {
      // disable lazy compilation for server
      lazyCompilation: false,
    },
  },
];
```

### Custom input file system

Rspack now allows you to customize `compiler.inputFileSystem` (the compiler's input file system). This feature can be enabled by configuring [experiments.useInputFileSystem](/config/experiments.md#experimentsuseinputfilesystem). Typical use cases include:

- Using [memfs](https://github.com/streamich/memfs) instead of the default input file system in browsers.
- Working with the [webpack-virtual-modules plugin](https://www.npmjs.com/package/webpack-virtual-modules) to support virtual modules.

```js title="rspack.config.mjs"
import VirtualModulesPlugin from 'webpack-virtual-modules';

export default {
  entry: './virtualEntry.js',
  plugins: [
    new VirtualModulesPlugin({
      'virtualEntry.js': `console.log('virtual entry')`,
    }),
  ],
  experiments: {
    useInputFileSystem: [/virtualEntry\.js$/],
  },
};
```

Since the custom `inputFileSystem` is implemented in JavaScript, it may lead to performance degradation. To mitigate this issue, `useInputFileSystem` allows you to pass an array of regular expressions to filter which files need to be read from the custom `inputFileSystem`, which avoids performance overhead caused by replacing the native file system.

In the future, we also plan to add built-in virtual module support in Rspack to provide better performance and user experience.

> For detailed usage, see the [documentation](/config/experiments.md#experimentsuseinputfilesystem).

### Performance analysis tool

Rspack 1.4 introduces more precise tracing capabilities, which can be used for performance analysis based on [perfetto](https://perfetto.dev/) to quickly identify build performance bottlenecks.

You can enable tracing through the `RSPACK_PROFILE` environment variable:

```sh
RSPACK_PROFILE=OVERVIEW rspack build
```

The generated `rspack.pftrace` file can be visualized and analyzed at [ui.perfetto.dev](https://ui.perfetto.dev/):

![tracing](https://assets.rspack.rs/rspack/assets/rspack-v1-4-tracing.png)
> For more detailed usage, see the [Tracing documentation](/contribute/development/tracing.md).

### Dependency upgrades

In Rspack 1.4, we have upgraded several major dependencies, including:

- Rspack now uses [Zod v4](https://zod.dev/v4) for configuration validation.
- `create-rspack` now provides [Biome v2](https://biomejs.dev/blog/biome-v2/) as an optional linter and formatter.

## Rstack progress

[Rstack](/guide/start/ecosystem.md#rstack) is a unified JavaScript toolchain centered on Rspack, with high performance and consistent architecture.

### Rsbuild 1.4

Rsbuild 1.4 has been released alongside Rspack 1.4, with notable features including:

#### Chrome DevTools integration

We've introduced a new [rsbuild-plugin-devtools-json](https://github.com/rstackjs/rsbuild-plugin-devtools-json) plugin, which enables seamless integration with Chrome DevTools' new [Automatic Workspace Folders](https://chromium.googlesource.com/devtools/devtools-frontend/+/main/docs/ecosystem/automatic_workspace_folders.md) feature. This means you can directly edit and debug your source code in DevTools and save changes to your local file system.

![rsbuild plugin devtools json](https://assets.rspack.rs/rspack/assets/rspack-v1-4-rsbuild-plugin-dev-tools-json.png)
#### Improved query parameters

Rsbuild now has built-in support for `.js?raw` query parameters, allowing you to import the raw content of JavaScript, TypeScript, and JSX files as text. This is very useful in scenarios where you need to process code as strings (such as displaying code examples).

```js
import rawJs from './script1.js?raw';
import rawTs from './script2.ts?raw';
import rawJsx from './script3.jsx?raw';

console.log(rawJs); // Raw content of JS file
console.log(rawTs); // Raw content of TS file
console.log(rawJsx); // Raw content of JSX file
```

#### Improved browser compatibility

When you import JS files from other packages in a monorepo, Rsbuild now uses SWC to compile them by default, which helps avoid browser compatibility issues introduced by external dependencies.

As shown in the diagram below, suppose the app's build target is ES2016 and utils' build target is ES2021. When `app/src/index.js` imports `utils/dist/index.js`, SWC will now downgrade it to ES2016.

![rsbuild monorepo compile scope](https://assets.rspack.rs/rspack/assets/rspack-v1-4-rsbuild-monorepo-compile-scope.png)
### Rslib 0.10

Rslib 0.10 has been released, with notable features including:

#### ESM output optimization

Rslib now generates cleaner, more concise, and smaller ESM output by default.

![rslib esm](https://assets.rspack.rs/rspack/assets/rspack-v1-4-rslib-esm.png)
#### Building Vue UI libraries

By integrating the [rsbuild-plugin-unplugin-vue](https://github.com/rstackjs/rsbuild-plugin-unplugin-vue) plugin, you can use Rslib to generate bundleless builds for Vue UI libraries.

```ts title="rslib.config.mjs"
import { defineConfig } from '@rslib/core';
import { pluginUnpluginVue } from 'rsbuild-plugin-unplugin-vue';

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

#### Output IIFE format

Rslib now supports generating [IIFE](https://rslib.rs/guide/basic/output-format#iife) format output, wrapping the code in a function expression.

![rslib iife](https://assets.rspack.rs/rspack/assets/rspack-v1-4-rslib-iife.png)
> See the [blog](https://rslib.rs/blog/introducing-rslib) for more information about Rslib.

### Rspress 2.0 beta

We are actively developing [Rspress 2.0](https://github.com/web-infra-dev/rspress) and have released multiple beta versions. Currently, we have completed most of the code refactoring work and have integrated [Shiki](https://shiki.style/) by default in Rspress 2.0 to provide more powerful code highlighting features.

Additionally, we are developing a brand new theme, with the preview shown below:

![rspress theme preview](https://assets.rspack.rs/rspack/assets/rspack-v1-4-rspress-preview.png)
### Rsdoctor MCP

Rsdoctor has introduced [@rsdoctor/mcp-server](https://rsdoctor.rs/guide/usage/mcp), which combines LLMs to help you better analyze build data. It can access Rsdoctor's local build analysis data and provide intelligent analysis and optimization suggestions.

Rsdoctor MCP provides bundle analysis, dependency analysis, bundle optimization suggestions, and build optimization suggestions. It can analyze bundle size composition, dependency relationships, and duplicate dependencies, while providing targeted optimization suggestions for bundle size optimization, code splitting, and build performance.


### Rstest released

[Rstest](https://github.com/web-infra-dev/rstest) is a brand-new testing framework built on Rspack that provides comprehensive, first-class support for the Rspack ecosystem. It integrates seamlessly into existing Rspack projects and offers Jest-compatible APIs.

This month, we released Rstest v0.0.3, which provides initial support for Node.js and UI component testing, and has been adopted in our repositories like Rsbuild.

![rstest](https://assets.rspack.rs/rspack/assets/rspack-v1-4-rstest.png)
> Rstest is currently in its early stages. We recommend staying tuned as we continue to enhance its testing capabilities to provide a more complete solution.

## Ecosystem

### next-rspack

Since [Rspack joined the Next.js ecosystem](/blog/rspack-next-partner.md), our primary goal has been to improve the stability and test coverage of next-rspack.

In the latest version, next-rspack has been largely completed, with test coverage reaching:

- Production builds **99.4%**
- Development builds **98.4%**

Moving forward, we plan to continue pushing test coverage to 100% and further optimize the performance of next-rspack.

![next-rspack](https://assets.rspack.rs/rspack/assets/rspack-v1-4-next-rspack.png)
### Kmi

[Kmi](https://github.com/kmijs/kmi) is a framework based on Umi and Rspack. By integrating Rspack as the bundler, Kmi delivers build performance improvements several times faster than the webpack version.

For developers currently using Umi, Kmi provides a progressive migration path that allows them to enjoy the performance benefits of Rspack while maintaining project stability.

For more information, see the [Kmi repository](https://github.com/kmijs/kmi).

## Upgrade guide

### Upgrade SWC plugins

If your project uses SWC Wasm plugins (such as `@swc/plugin-emotion`), you need to upgrade the plugins to a version compatible with `swc_core@29`, otherwise it may cause build errors due to version incompatibility.

> For more details, see [FAQ - SWC plugin version mismatch](/errors/swc-plugin-version.md).

### Lazy compilation middleware

The lazy compilation middleware has changed its way of accessing the [lazyCompilation](/config/lazy-compilation.md) option. Now, the middleware can automatically read the `lazyCompilation` option from the compiler instance, so you no longer need to manually pass in the `lazyCompilation` option.

```js
import { experiments, rspack } from '@rspack/core';
import { RspackDevServer } from '@rspack/dev-server';

const compiler = rspack([
  // ...multiple configs
]);

// no longer need to pass options to the middleware
const middleware = experiments.lazyCompilationMiddleware(compiler);

const server = new RspackDevServer(
  {
    setupMiddlewares: (other) => [middleware, ...other],
  },
  compiler,
);
```



---
url: /blog/rspack-next-partner.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Rspack joins the Next.js ecosystem

_April 10, 2025_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

One of Rspack's primary goals is to seamlessly integrate with webpack-based projects or frameworks, providing an enhanced development experience with minimal migration costs.

In the JavaScript ecosystem, [Next.js](https://nextjs.org/) has one of the most advanced build systems, with deeply customized webpack configurations and a rich plugin ecosystem. This made it an ideal candidate for testing and proving Rspack’s compatibility and robustness. Integrating Rspack into Next.js demonstrates Rspack's applicability in complex projects and provides Next.js users with an alternative solution to improve developer experience.

## Rspack comes to Next.js

Today, we’re excited to introduce [next-rspack](https://www.npmjs.com/package/next-rspack), a community-driven plugin bringing direct Rspack support to Next.js. This integration offers a fast, webpack-compatible alternative for teams not yet ready to adopt Turbopack.

> Get started today by visiting our [documentation](/guide/integrations/next.md) or checking out the official [Next.js example](https://github.com/vercel/next.js/tree/canary/examples/with-rspack).

Before landing this support, we explored integration possibilities by creating [rsnext](https://github.com/ScriptedAlchemy/rsnext/tree/rspack), a fork of Next.js designed to prototype a near drop-in solution. This early fork played a valuable role in validating feasibility and discovering edge cases. Also, it made us realize that while Rspack’s high compatibility with webpack gave us a head start, achieving stable integration still required significant effort and collaboration.

## Partnering with Vercel on shared foundations

The launch of next-rspack is just one aspect of our broader collaboration with Vercel. This partnership extends beyond Next.js integration, as both teams focus on improving shared foundational technologies such as [SWC](https://swc.rs/) and [Lightning CSS](https://lightningcss.dev/)—widely adopted tools across the JavaScript ecosystem.

By working together to enhance these core components, we're laying a stronger foundation for better developer experience, performance, and reliability. These efforts benefit not only Rspack and Next.js, but also help uplift the broader JavaScript ecosystem. A rising tide lifts all boats.

To ensure ongoing reliability, next-rspack is now integrated into Next.js’s continuous integration pipeline, proactively catching regressions and maintaining compatibility. Although still experimental, it currently passes around 96% of integration tests, giving us the confidence to publicly release this integration. You can track the latest status with [arewerspackyet](https://www.arewerspackyet.com/) and following [our twitter](https://x.com/rspack_dev) for latest progress about next-rspack.

For teams not yet ready to adopt Turbopack, next-rspack offers a solid, fast alternative with excellent compatibility and straightforward setup.

We deeply appreciate Vercel’s collaboration and shared commitment to improving the tools that developers rely on every day. We’ll continue working together to refine this integration and support the future of modern JavaScript development.

## Performance insights

### App router users

Currently, the App Router implementation with `next-rspack` is **slower than Turbopack**, and may even be slower than webpack. This is due to some **JavaScript plugins** that cause heavy Rust-JavaScript communication overhead.

We have **experimentally ported the theses plugins to Rust**, which dramatically improved performance—almost on par with Turbopack. And we are exploring how to address the long-term maintenance challenges that come with deep integration.

### Page router users

The situation is much more promising:

- **Development Mode**: 2x faster than webpack
- **Production Mode**: 1.5x faster than webpack

Users deeply integrated into the webpack ecosystem will find migration easier.

There're some known bottlenecks which limit further performance improvement(like huge Rust-JavaScript communication overhead, slower [output file tracing](https://nextjs.org/docs/pages/api-reference/config/next-config-js/output#how-it-works) implementation) which can be solved in the future, with expected improvements, we foresee:

- **5x faster builds and HMR in development**
- **3x faster production builds**

## Frequently asked questions

### How will it remain supported?

next-rspack is already integrated into Next.js’s CI pipeline, helping us catch regressions early and keep compatibility high. Support will evolve alongside both Next.js and Rspack, with ongoing collaboration between both teams and the open source community.

### Who maintains it?

next-rspack is a community plugin, but its development and integration rely on close collaboration between the Rspack and Vercel teams to ensure continued support and progress.

### Does this have any impact on Turbopack? is Vercel adopting Rspack?

Rspack doesn't replace Turbopack. It's an alternative solution for those with extensive webpack configurations who are not ready to migrate to Turbopack.

### What are known issues?

As of now, next-rspack passes around 96% of integration tests, and progress can be monitored on [arewerspackyet](https://www.arewerspackyet.com/).

- Some edge cases and advanced features may still require workarounds or additional support. Let us know how it went in the [feedback discussion](https://github.com/vercel/next.js/discussions/77800), even when you don't run into problems.
- Due to the current plugin implementation, the performance of the App Router is still suboptimal and there's still plenty of room for performance improvement.
- Since Rspack is not 100% compatible with webpack's API, some of your webpack plugins may not work smoothly on Rspack. Let us know if you have compatibility problems.

### How can you help?

Try out next-rspack, report issues, contribute code or docs, and join the community discussions. Your feedback and contribution is valuable.

## Future plans

- **Increase Test Coverage**: We aim to raise our test coverage from the current 96% to nearly 100% in the next quarter.
- **Enhance Performance**: We'll explore deeper integration with Next.js through native plugins to improve build performance.
- **Iterate Based on User Feedback**: Continue supporting more community plugins from the Next.js ecosystem.
- **Improve Integration Workflow**: Establish a more robust CI/CD pipeline between Rspack and Next.js to ensure the stability and reliability of next-rspack support.
- **Better RSC Support**: Turbopack’s unified module graph unlocks faster and simpler RSC implementation. Rspack will deliver a similar API to bring first-class, high-performance RSC support to the ecosystem.
- **Module Federation Support**: We are discussing with Next.js team about improved support of Module Federation.

Through 2024, stability and artifact integrity were a primary focus for Rspack. In 2025 we are focusing more on speed opportunities and broad ecosystem.

Stay tuned—we’re just getting started.



---
url: /blog/announcing-1-3.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 1.3

_March 28, 2025_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

![Rspack 1.3](https://assets.rspack.rs/rspack/rspack-banner-v1-3.png)

***

Rspack 1.3 has been released!

Notable changes:

- New features
  - [Circular dependency detection](#circular-dependency-detection)
  - [Build HTTP imports](#build-http-imports)
  - [Lazy compilation improvements](#lazy-compilation-improvements)
  - [AMD supports](#amd-supports)
- Performance improvements
  - [Code splitting 25% faster](#code-splitting-25-faster)
  - [Bundle size optimization](#bundle-size-optimization)
  - [Memory improvements](#memory-improvements)
- Rstack updates
  - [Rsdoctor 1.0](#rsdoctor-10)
  - [Rsbuild 1.3](#rsbuild-13)
  - [Rslib 0.6](#rslib-06)
  - [Rspress and Rstest](#rspress-and-rstest)
- Ecosystem
  - [Rspeedy for Lynx](#rspeedy-for-lynx)
  - [Re.Pack 5](#repack-5)
  - [React Router v7 support](#react-router-v7-support)
- Upgrade guide
  - [Module subtypes changed](#module-types-changed)
  - [Upgrade SWC plugins](#upgrade-swc-plugins)

## New features

### Circular dependency detection

Rspack 1.3 introduces a built-in plugin [CircularDependencyRspackPlugin](/plugins/circular-dependency-rspack-plugin.md) to detect circular dependencies between runtime modules.

This plugin is implemented in Rust and deeply integrated with Rspack's module graph, avoiding expensive data copying and serialization overhead. It detects all circular dependencies by performing a single traversal of the module graph for each entry point, rather than checking each module independently, resulting in lower performance overhead.

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.CircularDependencyRspackPlugin()],
};
```

> Special thanks to [@faultyserver](https://github.com/faultyserver) for contributing this plugin ❤️

### Build HTTP imports

In previous versions, you could import HTTP/HTTPS resources by using [externalsPresets.web](/config/externals.md#externalspresetsweb) or [externalsPresets.webAsync](/config/externals.md#externalspresetswebasync) options, which simply externals the these resources and let the browser (or other platform) to fetch them at runtime.

```js
import pMap from 'https://esm.sh/p-map';
```

And the new [experiments.buildHttp](/config/experiments.md#experimentsbuildhttp) option provides a new way to import HTTP/HTTPS resources, not fetch the resources at runtime, but download them to the local cache at build time and then bundle them into your output.

```js title="rspack.config.mjs"
export default {
  experiments: {
    buildHttp: {
      allowedUris: ['https://esm.sh/'],
    },
  },
};
```

> See [the docs](/config/experiments.md#experimentsbuildhttp) for more details.

### Lazy compilation improvements

In previous versions, when [lazy compilation](/guide/advanced/lazy-compilation.md) was enabled, Rspack would start a separate server to handle lazy compilation-related requests. This led to several issues, such as the need for two servers during development, and the lazy compilation server not being able to share proxy and CORS configurations with the default dev server.

Rspack 1.3 provides new Express-style middleware for integrating lazy compilation that addresses these issues.

- If you are using `@rspack/cli` or Rsbuild, you can upgrade to the new middleware by simply updating the dependency version.
- If you are using a custom development server, you will need to integrate this middleware to support lazy compilation.

Here's an example of how to use the lazy compilation middleware:

```js
import { rspack } from '@rspack/core';
import config from './rspack.config.mjs';
import DevServer from 'webpack-dev-server';

const compiler = rspack(config);
const middleware = rspack.experiments.lazyCompilationMiddleware(
  compiler,
  config.experiments.lazyCompilation,
);

const server = new DevServer(
  {
    setupMiddlewares(other) {
      return [middleware, ...other];
    },
  },
  compiler,
);
```

### AMD supports

Rspack now allows you to enable AMD module support by using the [amd](/config/other-options.md#amd) option.

Notably, Rspack differs from webpack in that the parsing of AMD modules is disabled by default (webpack enables it by default). This feature is only for compatibility with certain legacy AMD npm dependencies. We recommend prioritizing ES Module dependencies for better Rspack optimization and to boost ES Module adoption.

Add the `amd` option to enable support:

```js title="rspack.config.mjs"
export default {
  amd: {
    // ...
  },
};
```

> Special thanks to [@nilptr](https://github.com/nilptr) for contributing this plugin ❤️

## Performance improvements

### Code splitting 25% faster

In Rspack 1.2, we introduced the `experiments.parallelCodeSplitting` option to enable the new code splitting algorithm.

Starting from Rspack 1.3, this option is enabled by default, resulting in a **25%** performance boost for code splitting.

### Bundle size optimization

Rspack 1.3 introduces full support for the [output.environment](/config/output.md#outputenvironment) option, which allows you to specify which ECMAScript features can be used in the runtime code generated by Rspack, and to generate shorter and more modern runtime code.

By default, Rspack parses the [target](/config/target.md) option and automatically sets the values of the `output.environment` sub-options based on `browserslist` to determine which ECMAScript features are supported by the target environment, thus outputting the optimized code.

For example, if Rspack detects that the target environment supports arrow functions, it sets `output.environment.arrowFunction` to `true` and using arrow function syntax in the generated code.

```diff
// before
- __webpack_require__.d = function(exports, definition) {

// after
+ __webpack_require__.d = (exports, definition) => {
```

By utilizing modern JavaScript features supported by the target environment, Rspack can output smaller runtime code. In our performance testing on a real large-scale project, this optimization reduced the bundle size by approximately 500KB (before gzip compression).

### Memory improvements

Rspack now defaults to using [mimalloc](https://github.com/microsoft/mimalloc) v3 on macOS. This mitigates some memory consumption issue on macOS during rebuilding. According to some community and internal projects, this would lift the RSS for rebuilding, based on the size of each project, varying from **10% to 85%**.

Rspack 1.3 also implemented an internal mechanism to clean the outdated cache: `maxGenerations`. This controls how many compilations would cache survive if it's not being used by the compiler. Rspack sets the default to `1`. This means that the cache will be purged if it's not being used in the next compilation.

![Max generations](https://assets.rspack.rs/rspack/assets/rspack-v1-3-memory-improve-max-generations.png)
## Rstack updates

![Rstack](https://assets.rspack.rs/rstack/rstack-overview.png)
### Rsdoctor 1.0

After a year of development and testing, we are proud to introduce [Rsdoctor 1.0](https://github.com/web-infra-dev/rsdoctor) — a build analyzer tailored for the Rspack ecosystem and fully compatible with the webpack ecosystem.

Rsdoctor is committed to being a one-stop, intelligent build analyzer that makes the build process transparent, predictable, and optimizable through visualization and smart analysis, helping development teams precisely identify bottlenecks, optimize performance, and improve engineering quality.

Rsdoctor 1.0 introduces significant enhancements:

- A completely redesigned UI that delivers more intuitive and efficient information visualization.
- Rewrote data processing logic using Rust, achieving 20%+ improvement in analysis speed.
- New module search capabilities for analyzing dependencies and module sizes.

> Read the [Rsdoctor 1.0 release blog](https://rsdoctor.rs/zh/blog/release/release-note-1_0) for more.

### Rsbuild 1.3

Rsbuild 1.3 has been released alongside Rspack 1.3, notable features including:

- Support importing compiled CSS files as strings by using the [?inline](https://rsbuild.rs/guide/styling/css-usage#inline) query parameter:

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

console.log(inlineCss); // Output the compiled CSS file content
```

- Support importing raw CSS files and static assets as strings by using the [?raw](https://rsbuild.rs/guide/styling/css-usage#raw) query parameter:

```js
import rawSvg from './logo.svg?raw';
import rawCss from './style.css?raw';

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

### Rslib 0.6

Rslib 0.6 brings the following notable updates:

- **Improved CJS output**: Rslib's CJS output can now be statically analyzed, allowing Node.js ESM modules to use named imports to reference exports from CJS output.
- **Type error optimization**: When type errors occur, Rslib now prints the full context and code frame to the terminal, making it easier to fix type issues.

This release also adds support for YAML and TOML. See [Rslib 0.6](https://github.com/web-infra-dev/rslib/releases/tag/v0.6.0) for more details.

### Rspress and Rstest

We are also working on:

- **Rspress 2.0**: A fully upgraded static site generator with richer features and better performance.
- **Rstest**: A testing framework powered by Rspack. It delivers comprehensive, first-class support for the Rspack ecosystem, enabling seamless integration into existing Rspack-based projects.

More information will be released soon, stay tuned 🌟

## Ecosystem

### Rspeedy for Lynx

[Lynx](https://lynxjs.org/) is a family of technologies empowering developers to use their existing web skills to create truly native UIs for both mobile and web from a single codebase. Lynx was originally developed by an engineering team of ByteDance, which continues to drive its development.

Lynx has built a modern toolchain called [Rspeedy](https://lynxjs.org/rspeedy/) based on Rspack, Rsbuild, and Rsdoctor to enable fast builds. Lynx also features a speedy, versatile rendering engine and performance-driven dual-threaded UI programming.

![](https://lf-lynx.tiktok-cdns.com/obj/lynx-artifacts-oss-sg/lynx-website/assets/blog/lynx-unlock-native-for-more.png)

> Read the [Introductory Blog of Lynx](https://lynxjs.org/blog/lynx-unlock-native-for-more.html) for more.

### Re.Pack 5

[Re.Pack](https://github.com/callstack/repack) is a build tool for building your React Native application.

Re.Pack 5 has been released, which brings unprecedented performance improvements through Rspack, proper microfrontends support through Module Federation 2, simplified configuration and more.

> Read the [Re.Pack 5 release blog](https://re-pack.dev/blog/repack-5-release) for more.

### React Router v7 support

[rsbuild-plugin-react-router](https://github.com/rstackjs/rsbuild-plugin-react-router) has been released, which is an Rsbuild plugin that provides seamless integration with React Router v7, supporting the following features:

- Filesystem routes
- Server-side rendering
- Experimental Module Federation support

> See [rsbuild-plugin-react-router repository](https://github.com/rstackjs/rsbuild-plugin-react-router) to try it out.

## Upgrade guide

### Module types changed

The module types exported by Rspack have been refined with more accurate type definitions, which helps to align with webpack. Currently supported module subtypes include:

- NormalModule
- ContextModule
- ExternalModule
- ConcatenatedModule

You can now identify a module's specific type in two ways:

```ts
// Method 1: Instance type checking
module instanceof NormalModule;

// Method 2: Constructor signature detection
module.constructor.name === 'NormalModule';
```

The new type definitions may cause type errors in existing JavaScript API code, such as:

```ts
module.resource; // TypeScript Error: Property 'resource' does not exist on type 'Module'
```

To access the `resource` property, you now need to assert the module type using one of the following methods:

```ts
// Solution 1: `in` operator type guard
if ('resource' in module) {
  console.log(module.resource);
}

// Solution 2: Instance type assertion
if (module instanceof NormalModule) {
  module.resource;
}
```

### Upgrade SWC plugins

In Rspack 1.3, the Rust crate `swc_core` has been upgraded to v16. Users of the SWC Wasm plugin need to ensure version consistency with `swc_core` being used, otherwise, it may lead to unforeseen issues.

For more details, see [FAQ - SWC plugin version mismatch](/errors/swc-plugin-version.md).



---
url: /blog/announcing-1-2.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 1.2

_January 21, 2025_


![jerrykingxyz](https://github.com/jerrykingxyz.png)

jerrykingxyz

[](https://github.com/jerrykingxyz)

@jerrykingxyz

![chenjiahan](https://github.com/chenjiahan.png)

chenjiahan

[](https://github.com/chenjiahan)

@chenjiahan

![JSerFeng](https://github.com/JSerFeng.png)

JSerFeng

[](https://github.com/JSerFeng)

@JSerFeng

![ahabhgk](https://github.com/ahabhgk.png)

ahabhgk

[](https://github.com/ahabhgk)

@ahabhgk

![Rspack 1.2](https://assets.rspack.rs/rspack/rspack-banner-v1-2.png)

Rspack v1.2 has been released!

Notable changes:

- New features
  - [Persistent cache](#persistent-cache): An experimental feature that improves hot start performance by up to **250%**.
  - [Yarn PnP](#yarn-pnp)
- Performance improvements
  - [Faster code splitting](#faster-code-splitting): An experimental flag that significantly improve the code splitting performance.
  - [Watch scope change](#watch-scope-change)
  - [Reduced memory usage](#reduced-memory-usage)
  - [Smaller minification size](#smaller-minification-size)
  - [Faster side effects optimization](#faster-side-effects-optimization)
- Ecosystem
  - [Angular support](#angular-support)
  - [Rsbuild v1.2](#rsbuild-v12)

## New features

### Persistent cache

Rspack v1.2 introduced an experimental cache configuration that supports persistent caching, which can significantly improve hot startup speed.

```js title="rspack.config.mjs"
export default {
  cache: true,
  experiments: {
    cache: {
      type: 'persistent',
    },
  },
};
```

When a build hits the cache, it can bring up to 250% performance improvement in real projects.

| Project type               | Number of modules | Normal dev | Cold dev     | Hot dev       |
| -------------------------- | ----------------- | ---------- | ------------ | ------------- |
| Initial project            | 26                | 146 ms     | 149 ms (+2%) | 134 ms (-8%)  |
| Project with 10000 modules | 10040             | 2.43 s     | 2.43 s (+0%) | 1.16 s (-52%) |
| Project with Less files    | 1898              | 3.47 s     | 3.55 s (+2%) | 0.92 s (-73%) |
| Large real project         | 45968             | 93.3 s     | 91.9 s (-1%) | 26 s (-72%)   |

Note that persistent cache is still in an experimental stage and currently only supports the make stage of the build process (including module resolution, transformation, etc.). We will continue to optimize it in the future to further improve cache performance and coverage.

If you encounter any issues while using persistent cache, please feel free to report them via GitHub Issues.

> See [cache](/config/cache.md) for more details.

### Yarn PnP

Rspack has added support for [Yarn PnP](https://yarnpkg.com/features/pnp), which is enabled by default based on `process.versions.pnp` (that is, when the application is running in a Yarn PnP environment), and can also be forced to enable by configuring `resolve.pnp` to `true`.

```js title="rspack.config.mjs"
export default {
  resolve: {
    pnp: true,
  },
};
```

Special thanks to [@arcanis](https://x.com/arcanis), the lead maintainer for Yarn, for implementing PnP resolution in the Rspack resolver.

> See [resolve.pnp](/config/resolve.md#resolvepnp) for more details.

## Performance improvements

### Faster code splitting

In previous versions of Rspack, the code splitting would take up a lot of time under HMR. In Rspack v1.2, we implemented a new code splitting algorithm that supports multithreading and more efficient incremental rebuilds. If your code base contains a lot of dynamic imports, and code splitting will take a lot of time. Enabling this new feature can significantly improve the performance of code splitting.

```js title="rspack.config.mjs"
export default {
  experiments: {
    parallelCodeSplitting: true,
  },
};
```

### Watch scope change

Rspack v1.2 no longer watching the `node_modules` directory by default. This can greatly reduce the number of files to watch and improve performance.

According to our [benchmark repo](https://github.com/rstackjs/build-tools-performance), this change will:

- Reduce memory usage by 120MB
- Increase dev startup speed by 40%
- Increase HMR speed by 20\~30%

This change will not affect symlinked resources in monorepo, as symlinked resources are resolved to their real path by default.

If you prefer to keep the previous behavior, you can set:

```js title="rspack.config.mjs"
export default {
  watchOptions: {
    ignored: [],
  },
};
```

> See [watchOptions.ignored](/config/watch.md#watchoptionsignored) for more details.

### Reduced memory usage

We have optimized the data structure used to store strings during the [rspack-sources](https://github.com/rstackjs/rspack-sources) computation process. Throughout the computation, all string data points to the string heap memory of the root node, effectively avoiding the generation of new string allocations during the computation.

> See [perf: reduce memory consumption of CachedSource](https://github.com/web-infra-dev/rspack/pull/8666) for more details.

### Smaller minification size

Rspack v1.2 set default SWC minimizer `passes` to `2` to reduce bundle size by 1%-7%.

```js
new rspack.SwcJsMinimizerRspackPlugin({
  minimizerOptions: {
    compress: {
      // Defaults to 1 in previous versions
      passes: 2,
    },
  },
});
```

[passes](https://swc.rs/docs/configuration/minification#jscminifycompress) is the maximum number of times to run compress. In some cases, more than one pass leads to further compressed code. Given Rspack's inherent speed, we've determined that using `2` passes by default strikes an optimal balance between build performance and bundle size.

> See [feat: set default SWC minimizer passes to 2 to reduce bundle size](https://github.com/web-infra-dev/rspack/pull/8853) for more details.

### Faster side effects optimization

The implementation of side effects optimization has been refactored to be simpler and more parallelism-friendly. It can take full advantage of parallelism to improve performance. In tested projects, there is typically a 2x-3x performance improvement at this stage.

> See [perf: parallelize side effects optimization](https://github.com/web-infra-dev/rspack/pull/8781) for more details.

## Ecosystem

### Angular support

Nx team core member [Colum Ferry](https://github.com/Coly010) has brought complete Angular support to the Rspack ecosystem.

With the newly released `@ng-rsbuild/plugin-angular` and `@ng-rspack/build` packages, developers can now use Rspack or Rsbuild to build Angular applications, with faster build performance and module federation support.

Please visit [Angular Rspack](https://nx.dev/docs/technologies/angular/angular-rspack) for more information.

### Rsbuild v1.2

Rsbuild v1.2 has been released alongside Rspack v1.2, bringing several new features:

- Customize manifest file generation through [output.manifest.generate](https://rsbuild.rs/config/output/manifest#generate).
- Specify files to retain in the dist directory using [cleanDistPath.keep](https://rsbuild.rs/config/output/clean-dist-path#keep).
- [@rsbuild/plugin-assets-retry](https://v0.rsbuild.rs/plugins/list/plugin-assets-retry) now generates smaller runtime code.

> For more details, see [Rsbuild v1.2.0](https://github.com/web-infra-dev/rsbuild/releases/tag/v1.2.0).

## Upgrade guide

### Upgrade SWC plugins

In Rspack v1.2, the Rust crate `swc_core` has been upgraded to `10.1.0`. Users of the SWC Wasm plugin need to ensure version consistency with `swc_core` being used, otherwise, it may lead to unforeseen issues.

For more details, see [FAQ - SWC plugin version mismatch](https://swc.rs/docs/plugin/selecting-swc-core).

### Disable WarnCaseSensitiveModulesPlugin by default

The [WarnCaseSensitiveModulesPlugin](/plugins/case-sensitive-plugin.md) is used to check the paths of modules and issue warnings for modules that conflict when their paths are all in lowercase. Rspack used to enable it by default, but since it is only a "linter" plugin and it has additional performance overhead especially in development mode. So now it is disabled by default.

If you prefer to keep the previous behavior, you can set:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.WarnCaseSensitiveModulesPlugin()],
};
```



---
url: /blog/announcing-1-1.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 1.1

_November 7, 2024_


![LingyuCoder](https://github.com/LingyuCoder.png)

LingyuCoder

[](https://github.com/LingyuCoder)

@LingyuCoder

![ahabhgk](https://github.com/ahabhgk.png)

ahabhgk

[](https://github.com/ahabhgk)

@ahabhgk

![GiveMe-A-Name](https://github.com/GiveMe-A-Name.png)

GiveMe-A-Name

[](https://github.com/GiveMe-A-Name)

@GiveMe-A-Name

![9aoy](https://github.com/9aoy.png)

9aoy

[](https://github.com/9aoy)

@9aoy

![chenjiahan](https://github.com/chenjiahan.png)

chenjiahan

[](https://github.com/chenjiahan)

@chenjiahan

![Rspack 1.1](https://assets.rspack.rs/rspack/rspack-banner-v1-1.png)

Rspack v1.1 and Rsbuild v1.1 are out!

Notable changes:

- Performance improvements
  - [Better scheduling strategy](#better-scheduling-strategy): Make Rspack **10% faster** than v1.0.
  - [New incremental rebuild](#new-incremental-rebuild): Experimental feature that makes HMR **up to 38% faster**.
- New features
  - [Improved HTML Plugin](#improved-html-plugin): Refactored the built-in HTML plugin with new features.
  - [Improved JSDoc](#improved-jsdoc): Added JSDoc for all configuration options.
- Ecosystem
  - [Docusaurus Faster](#docusaurus-faster): Use Rspack as the bundler for Docusaurus sites.
  - [Nuxt Rspack Builder](#nuxt-rspack-builder): Experimental Rspack builder for Nuxt.
- [Rsbuild v1.1](#rsbuild-v11): CLI shortcuts and new configurations.

## Performance improvements

### Better scheduling strategy

According to our benchmarks, Rspack v1.1 is **10% faster** than v1.0.

![Rspack v1.1 vs v1.0](https://assets.rspack.rs/rspack/assets/rspack-1-1-perf-comparison.png)
A major optimization is that Rspack uses a better scheduling strategy inspired by [Using Rustlang’s Async Tokio Runtime for CPU-Bound Tasks](https://thenewstack.io/using-rustlangs-async-tokio-runtime-for-cpu-bound-tasks/) and SWC optimization for better concurrency support, which allows better scheduling of async tasks.

### New incremental rebuild

In the early versions of Rspack 0.x, we implemented [experiments.incrementalRebuild](https://v0.rspack.rs/config/experiments#experimentsincrementalrebuild). As this feature gradually stabilized, we removed the experiments configuration and enabled it by default.

However, this feature only enabled incrementality for the `make` and `emitAssets` stages of the rebuild. For many projects, the loader in the `make` stage takes a lot of time. At that time, this feature had a relatively obvious performance improvement in rebuild for these projects. But there are still some projects that take a lot of time in stages other than `make`. Therefore, we optimized and expanded this feature and gradually introduced this feature into other stages, such as `buildChunkGraph`, `providedExports`, `moduleCodegen`, etc.

In Rspack v1.1, we introduced [experiments.incremental](/config/deprecated-options.md#experimentsincremental) as the successor and superset of `experiments.incrementalRebuild`, aiming to bring further rebuild performance improvement and faster HMR to developers.

In a case of 10000 React components, the HMR becomes 38% faster:

![10000 React Components with new incremental enabled](https://assets.rspack.rs/rspack/assets/rspack-v1-1-new-incremental-compare.png)
In Rspack v1.1 you can enable this feature in development mode by:

```js title="rspack.config.mjs"
const isDev = process.env.NODE_ENV === 'development';

export default {
  mode: isDev ? 'development' : 'production',
  experiments: {
    incremental: isDev,
  },
};
```

> See [experiments.incremental](/config/deprecated-options.md#experimentsincremental) for more details.

This is still an experimental feature and we need more work to stabilize it. If you are interested, give it a try and send bug reports and feedback to [#8106](https://github.com/web-infra-dev/rspack/issues/8106).

## New features

### Improved HTML plugin

In earlier versions of Rspack, the built-in [HtmlRspackPlugin](/plugins/html-rspack-plugin.md) was implemented. However, its capabilities were severely lacking. It lacked some configuration options and did not support `hooks`, which made those plugins implemented based on the `hooks` of `HtmlWebpackPlugin` incompatible with Rspack.

Therefore, we refactored `HtmlRspackPlugin`. While supporting most of the configuration options of `HtmlWebpackPlugin`, we also completed the alignment of `hooks`. Now you can get these hooks through `HtmlRspackPlugin.getCompilationHooks` and use them to modify the content of the HTML assets like below:

```js title="rspack.config.mjs"
const DeferPlugin = {
  apply(compiler) {
    compiler.hooks.compilation.tap('DeferPlugin', (compilation) => {
      const hooks = HtmlRspackPlugin.getCompilationHooks(compilation);
      hooks.alterAssetTags.tapPromise('DeferPlugin', async (data) => {
        // Add `defer` attribute to all script tags
        for (const tag of data.assetTags.scripts) {
          if (tag.tagName === 'script') {
            tag.attributes.defer = true;
          }
        }
      });
    });
  },
};

export default {
  plugins: [new HtmlRspackPlugin(), DeferPlugin],
};
```

> See [HtmlRspackPlugin](/plugins/html-rspack-plugin.md) for more details.

### Improved JSDoc

Rspack uses [zod](https://github.com/colinhacks/zod) to validate user configurations and infer all configuration types. However, the inferred types lack JSDoc comments and the generated types are quite complex and hard to understand.

To fix this, we recently refactored the configuration types and added JSDoc comments for all of them to improve readability.

![configuration intellisense in IDE](https://assets.rspack.rs/rspack/assets/rspack-v1-1-config-intellisense.png)
> We're still looking to improve the JSDoc. If you're interested, feel free to submit pull requests. ❤️

## Ecosystem

### Docusaurus Faster

[Docusaurus v3.6](https://docusaurus.io/blog/releases/3.6) brings the `Docusaurus Faster` options that allow users to use Rspack as the bundler for Docusaurus sites.

The [Docusaurus Faster](https://docusaurus.io/blog/releases/3.6#docusaurus-faster) project's goal is to reduce the build times and memory consumption of Docusaurus. Docusaurus team have worked on multiple optimizations and modernized their infrastructure to use faster Rust-based tools like Rspack and SWC.

Benchmarks on community site show that the production site can build 2 to 4 times faster.

### Nuxt Rspack builder

[Nuxt v3.14](https://nuxt.com/blog/v3-14) brings a new first-class Nuxt builder for Rspack.

It's still experimental and Nuxt team refactored the internal Nuxt virtual file system to use `unplugin` to make this possible.

You can try [nuxt-rspack-starter](https://github.com/danielroe/nuxt-rspack-starter) to get started, or install [@nuxt/rspack-builder](https://www.npmjs.com/package/@nuxt/rspack-builder) and set `builder: 'rspack'` in the Nuxt config file.

## Rsbuild v1.1

Rsbuild v1.1 upgraded to Rspack v1.1 and introduced several new features.

### CLI shortcuts

Rsbuild now supports enabling CLI shortcuts through the [dev.cliShortcuts](https://rsbuild.rs/config/dev/cli-shortcuts) config. If you are using Rsbuild CLI, it is enabled by default.

The CLI shortcut allows you to clear the console, open the browser, restart the server, or customize any shortcut you want.

![Rsbuild CLI shortcuts](https://assets.rspack.rs/rsbuild/assets/rsbuild-cli-shortcuts.png)
### View static assets

Rsbuild dev server now provides a report page at `/rsbuild-dev-server` that allows you to view all static assets generated during the current build.

![rsbuild-dev-server](https://assets.rspack.rs/rsbuild/assets/assets-report-page.png)
### New configurations

Rsbuild 1.1 introduced some new configurations:

- [server.base](https://rsbuild.rs/config/server/base): Set the base path of the server.
- [source.assetsInclude](https://rsbuild.rs/config/source/assets-include): Set the additional files that should be treated as static assets.
- [output.filename.assets](https://rsbuild.rs/config/output/filename): Set the name of other static assets.
- [output.distPath.assets](https://rsbuild.rs/config/output/dist-path): Set the output directory of other static assets.

## Upgrade guide

### Upgrade SWC plugins

In Rspack v1.1, the Rust crate `swc_core` has been upgraded to `5.0.1`. Users of the SWC Wasm plugin need to ensure version consistency with `swc_core` being used, otherwise, it may lead to unforeseen issues.

For more details, see [SWC documentation](https://swc.rs/docs/plugin/selecting-swc-core).

### Hash function

Rspack's [output.hashFunction](/config/output.md#outputhashfunction) now defaults to the faster `xxhash64`, and the [output.hashDigestLength](/config/output.md#outputhashdigestlength) now defaults to `16` (prev `20`). This change will bring a significant performance improvement for large projects.

If you prefer the previous hash function, you can set:

```js title="rspack.config.mjs"
export default {
  output: {
    hashFunction: 'md5',
    hashDigestLength: 20,
  },
};
```

> Related PR: [#8249](https://github.com/web-infra-dev/rspack/pull/8249).



---
url: /blog/announcing-1-0.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 1.0

_August 28, 2024_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

![](https://assets.rspack.rs/rspack/rspack-banner-v1-0.png)

***

**We are excited to introduce Rspack 1.0!**

Rspack is a next-generation JavaScript bundler written in Rust, compatible with the webpack API and ecosystem, and is 10 times faster than webpack.

Eighteen months ago, we open-sourced Rspack 0.1 and received substantial feedback and contributions from the community. During this time, 170 contributors have joined in the development of Rspack, submitting over 5000 pull requests and more than 2000 issues, which have helped Rspack release over 80 versions. And Rspack's weekly downloads on npm have exceeded 100,000 🎉.

![Rspack Stats](https://assets.rspack.rs/rspack/assets/rspack-v1-0-stats.png)

Today Rspack has reached a new milestone - 1.0. This means that Rspack is production-ready, covers most of webpack's APIs and features, and is now prepared to support more users.

## Who's using Rspack

Since Rspack was open-sourced, many enterprises and developers have used Rspack in production. The weekly npm downloads of Rspack have also exceeded 100,000.

![Rspack downloads](https://assets.rspack.rs/rspack/assets/rspack-v1-0-downloads.png)

Within ByteDance, Rspack's weekly downloads exceed 400,000, and over 1,000 web applications use Rspack, including TikTok, Douyin, Lark, Coze, and more. These projects have significantly improved build times and iteration efficiency by using Rspack. This has also helped us identify some early design issues with Rspack, prompting us to improve the architecture and strike a balance between migration cost, performance, and flexibility.

We have also seen an increasing number of enterprise users starting to use Rspack, including Microsoft, Amazon, Alibaba, Intuit, Bit.dev, Discord, and others. We are excited that Rspack can help these enterprise users to achieve progressive migration, and we look forward to further cooperation and communication with more enterprises and developers in the future.

![Who is using](https://assets.rspack.rs/rspack/assets/rspack-v1-0-who-is-using.png)

## New features

Since the release of 0.1, Rspack has introduced numerous important features and optimizations, including:

### Better performance

As a Rust-based bundler, performance has always been a core focus for Rspack. Since the release of Rspack 0.1, we have made numerous performance improvements, optimized its performance for different scenarios, and added key features such as [lazy compilation](/config/lazy-compilation.md) to ensure better performance in large projects.

Here is a comparison of build performance between Rspack 0.1 and Rspack 1.0 from the [benchmark](https://github.com/rstackjs/build-tools-performance). Rspack has significantly improved build performance while also adding many new features:

![Rspack benchmark](https://assets.rspack.rs/rspack/assets/rspack-v1-0-benchmark.png)

Note that the current architecture and implementation of Rspack still have significant room for optimization. After the 1.0 release, we plan to further improve the performance by several times to better support large-scale applications.

### Better compatibility

When 0.1 was first released, Rspack had not yet implemented many webpack APIs and hooks, limiting its compatibility with webpack plugins and loaders. This required us to fork some community libraries to adapt them for Rspack, such as the early versions of [@rspack/plugin-html](https://www.npmjs.com/package/@rspack/plugin-html), [@rspack/plugin-minify](https://www.npmjs.com/package/@rspack/plugin-minify), and [@rspack/plugin-node-polyfill](https://www.npmjs.com/package/@rspack/plugin-node-polyfill).

As the API support has gradually improved, Rspack has added support for more and more webpack plugins and loaders. Currently, Rspack is compatible with almost all loaders in the community. For the 50 most downloaded [webpack plugins](/plugins/community-plugin-compatibility.md), more than 80% can be used in Rspack or have an alternative.

Building on this foundation, Rspack supports more libraries and frameworks, including React, Preact, Vue, Solid, Svelte, and NestJS. We would also like to thank the maintainers of many community plugins who have actively adapted their work for Rspack, such as [unplugin](https://github.com/unjs/unplugin) and [node-polyfill-webpack-plugin](https://www.npmjs.com/package/node-polyfill-webpack-plugin). Special thanks to [Alexander Akait](https://github.com/alexander-akait), one of the main maintainers of webpack, who helped us support many webpack loaders and plugins.

We also hope to support and create more community plugins to further enrich the webpack and Rspack ecosystem.

### Smaller bundle size

Rspack has consistently prioritized minimizing the bundle size of production builds. Since the release of 0.1, Rspack has gradually aligned its optimization capabilities with webpack, implementing features such as [split chunks](/plugins/split-chunks-plugin.md#splitchunksplugin), [tree shaking](/guide/optimization/tree-shaking.md), [scope hoisting](/config/optimization.md#optimizationconcatenatemodules) and [mangle exports](/config/optimization.md#optimizationmangleexports).

When a project migrates from webpack to Rspack, these features ensure that the bundle size remains the same as webpack while improving DX. In some scenarios, the output size of Rspack has even slightly outperformed webpack.

For example, in a real-world medium-sized web application, the bundle size of Rspack 1.0 was optimized from 6600KB to 5900KB compared to Rspack 0.1, which is equivalent to webpack. In the future, Rspack will continue to explore more advanced solutions to optimize bundle size.

### Support for Module Federation 2.0

[Module Federation](https://module-federation.io/) is a micro-frontend architectural pattern widely used in the ecosystem. The Rspack team has been working with the Module Federation team to develop Module Federation 2.0. This new version provides features such as dynamic TS type hints, Chrome devtools, runtime plugins, preloading. These features make Module Federation more suitable for use as a micro-frontend architecture in large-scale web applications.

Rspack also provides backwards compatibility and support for Module Federation 1.0, making it easier for webpack projects to migrate.

### Stable API and new website

In 1.0, we have improved the stability of the configuration, JavaScript API, and plugin API. This ensures that higher-level tools and frameworks can more easily integrate with Rspack. We have also improved the guides and API documentation on the official website.

Rspack 1.0 also includes a brand new [homepage](/index.md). Many thanks to designer Emily Jackson and team member [Zack Jackson](https://github.com/ScriptedAlchemy) for their efforts in making this happen.

![Rspack Homepage](https://assets.rspack.rs/rspack/assets/rspack-v1-0-homepage.png)

## Why Rspack

Over the past two years, the community has seen the birth of several Rust-based bundlers, all of which have demonstrated remarkable performance. Rspack not only provides first-class performance. It also leads the community in terms of flexibility and compatibility.

The current goals of Rspack are:

- To help existing webpack projects progressively migrate to a high performance bundler, so that build performance is no longer a bottleneck for fast iterations.
- Rspack is not just suitable for environments like browser and Node.js that we are familiar with; its goal is to cover all environments where JavaScript runs. This means that Rspack can easily support Deno, Electron, cross-platform applications, MiniApps, and any other JavaScript runtime.
- We found that balancing "flexibility" and "out-of-the-box" in a single tool was a challenging task. Therefore, after open-sourcing Rspack, we developed a set of Rstack toolchains, including projects such as Rsbuild, Rspress, Rsdoctor, and Rslib, each targeting different use cases. For example, to reduce the complexity and high barriers to configuring Rspack, we provide Rsbuild for an out-of-the-box development experience.

### Rstack

![Rstack](https://assets.rspack.rs/rspack/assets/rspack-v1-0-rstack.png)

Rstack is short for "Rspack Stack" and stands for the tech stack centered on Rspack. It consists of the following tools:

- [Rspack](https://github.com/web-infra-dev/rspack): Focuses on implementing the high performance bundler, balancing performance and flexible configuration.
- [Rsbuild](https://github.com/web-infra-dev/rsbuild): Focuses on building web applications, providing an out-of-the-box development experience.
- [Rslib](https://github.com/web-infra-dev/rslib): Focuses on building libraries, providing high quality ESM and CJS outputs.
- [Rspress](https://github.com/web-infra-dev/rspress) Focuses on generating static sites and supports MDX for building documentation sites and blogs.
- [Rsdoctor](https://github.com/web-infra-dev/rsdoctor) Focuses on build analysis, helping developers resolve build-related issues.

Together these tools make up the Rstack. We aim to provide a unified set of web development tools that deliver a top tier experience for both developers and users.

### Compatibility with webpack

Rspack 1.0 is designed to be compatible with webpack v5, which will help many projects using webpack to migrate smoothly to Rspack. While maintaining compatibility with webpack, Rspack 1.0 also embraces modern web standards and aims for ultimate build performance.

- For web standards, Rspack actively follows the evolution of modern web standards and the latest developments from TC39 and web standards. For example, Rspack already supports the use of Web Workers through [new Worker()](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker), supports importing JSON modules through [Import Attributes](https://github.com/tc39/proposal-import-attributes), and supports importing CSS based on the [CSS Module Scripts](https://web.dev/articles/css-module-scripts) specification.
- For performance, we have introduced many optimizations in 1.0. For example, if a JavaScript-side hook is not used, the Rust side will not invoke communication with the JavaScript side. Also, Rspack performs lazy loading for many message objects. Even if the message object is large, if JavaScript only consumes a subset of its properties, Rspack will only transfer the consumed data, minimizing the communication overhead between Rust and JavaScript. And Rspack plans to provide even more lightweight hooks in the future to achieve more efficient communication between Rust and JavaScript.

In future major releases, Rspack will evolve based on the webpack API to better meet the needs of modern web development.

## How to use 1.0

If you are using Rspack 0.7 or an earlier version, please note that 1.0 contains some breaking changes. We have prepared detailed documentation to help you upgrade. Please refer to: [Migration from Rspack 0.x](/guide/migration/rspack_0.x.md).

If you have never used Rspack before, please see [Quick Start](/guide/start/quick-start.md) to get started with Rspack. Also, feel free to give a star 🌟 to the [Rspack GitHub repository](https://github.com/web-infra-dev/rspack).

## What's next

Rspack 1.0 marks a new beginning. Following this release, the Rspack team will focus on the following goals:

- **Develop Rspack 1.x.** Rspack 1.x will iterate over 12 to 18 months, bringing more new features and improvements.
- **Release Rsbuild 1.0.** It is based on Rspack 1.0 and supports [multi-environment builds](https://rsbuild.rs/guide/advanced/environments). Currently, Rsbuild has released version 1.0 RC, and the official release is expected in September.
- **Release Rsdoctor 1.0.** This release will improve support for Vue and provide [report formats](https://github.com/web-infra-dev/rsdoctor/issues/408) for CI/CD.
- **Develop Rslib 0.x.** Rslib is a library building tool based on Rsbuild. See [Rslib repository](https://github.com/web-infra-dev/rslib) for more details.
- **Develop Rspress 2.0.** It will be based on React 19 and will improve some of the API designs. See [Rspress v2.0 planning](https://github.com/web-infra-dev/rspress/discussions/1105) for more details.

Here are some key features we plan to support in Rspack 1.x:

### Faster HMR

Rspack can currently meet the performance requirements for most projects, but there is still significant room for performance optimization. During development, Rspack has already achieved nearly constant level incremental builds during the make phase. However, in the seal phase, some computations can still slow down as projects scale. Rspack will incrementally optimize the computations in the seal phase to keep the HMR time at a constant level.

### Portable cache

The evolution path of Rspack's caching capabilities follows a sequential implementation of memory cache, persistent cache, and portable cache. Currently, Rspack has implemented a memory cache that provides excellent HMR performance. The next step is to implement a persistent cache based on this foundation to address long cold startup times for large projects and to functionally align with webpack.

After that, we plan to continue implementing **portable cache**. This means that Rspack's build cache will not only be persistent, but also portable across environments and machines. This will help teams make better use of the cache and lay the groundwork for distributed builds.

### TypeScript-based optimization

Currently, when Rspack processes TypeScript modules, it first converts them to JavaScript through a loader before further processing. This provides flexibility but also hinders further optimization of the build output. For example, developers need to use `enum` instead of `const enum`, but `enum` is difficult to optimize as a constant. In the future, we plan to treat TypeScript as a first-class citizen in Rspack, leveraging TypeScript's static information to provide more advanced compile-time optimization of the build output (such as [type-based property renaming](https://github.com/google/closure-compiler/wiki/Type-Based-Property-Renaming)).

### Stable Rust API

Currently, higher-level tools can use the JS API to integrate Rspack, which provides good extensibility. However, the communication overhead between Rust and JavaScript that limits the performance of Rspack. We also provide the [SWC Wasm plugin](/guide/features/builtin-swc-loader.md#jscexperimentalplugins) to support extensions, but its performance is still slower than native languages.To provide higher-level tools with more flexible integration options and better performance, we plan to expose Rspack's Rust API for integration.

### React Server Components support

At ByteDance, we have experimentally supported RSC (React Server Components) based on Rspack and validated it in a large web application. In the future, Rspack will provide first-class support for RSC, with more core features to make RSC easier to implement. For example, Rspack now supports the [layer](/guide/advanced/layer.md) feature, which allows to build for multiple environments in a single run.

### Improved ESM output

ESM is the standard for JavaScript modules. We are currently improving Rspack and webpack's support for ESM output and creating a library build tool based on Rspack called Rslib. This will allow developers to make better use of ESM's static analysis and tree-shaking when building npm packages.

## Acknowledgements

The development of Rspack would not have been possible without the contributions and support of the awesome community. Special thanks to:

- The [NX team](https://nx.dev/) for trusting in Rspack and integrating it early during its open-source phase.
- [Zack Chapple](https://github.com/zackarychapple) and the [Zephyr team](https://www.zephyr-cloud.io/) for helping to promote Rspack.
- The [Unplugin team](https://github.com/unjs/unplugin) for actively helping to integrate Rspack and enriching the plugin ecosystem.
- [Brandon Dail](https://github.com/aweary) for using Rspack on Discord and helping us spread the word.
- [Kaffi Y](https://github.com/xc2) for tirelessly helping users and answering Rspack-related questions on GitHub and Discord.
- All the developers participating in ByteDance's Rspack Innovator project, such as [Kelvin Omereshone](https://x.com/Dominus_Kelvin), [Yannik Peschke](https://x.com/_yanpes), [Russell Canfield](https://x.com/RussellCanfield), and [Kyrylo](https://x.com/KyryloBashtenko) who gave us early feedback and advice.
- All the companies and users who have been using Rspack since version 0.x, their valuable suggestions have helped Rspack to progress.

In the open source community, Rspack won the 2024 [Breakthrough of the Year Award](https://osawards.com/javascript/), which is a great encouragement for the Rspack team. We would like to thank all the developers who voted for Rspack.

![Rspack OSS Awards](https://assets.rspack.rs/rspack/assets/rspack-v1-0-osawards.png)

Since the 0.1 release, we have established good collaborations with several community teams:

- While aligning with webpack, we worked with the webpack team to improve support for native CSS and ESM output. In the process, the Rspack team submitted over 100 commits to webpack. Special thanks to [Alexander Akait](https://github.com/alexander-akait) for his review feedback.
- We also worked with the SWC team, contributing the Preact Refresh SWC plugin and fixing some transform and minify bugs in SWC. Thanks to [kdy](https://github.com/kdy1) for his review feedback.
- Rspack has embraced the [unplugin](https://github.com/unjs/unplugin) ecosystem and fully supports the unplugin API. Thanks to [sxzz](https://github.com/sxzz) for his review feedback and [antfu](https://github.com/antfu) for his remarkable creativity.

We are also excited to see Rspack being used or integrated into a wider ecosystem, including [Bazel](https://medium.com/@yanirmanor/why-moving-to-rspack-and-how-to-use-it-with-bazel-9f66139fe493), [Storybook](https://github.com/rstackjs/storybook-rsbuild), [Electron](https://github.com/noshower/electron-forge-plugin-rspack), and more.

Finally, we would like to thank all the developers who have contributed to the Rspack ecosystem ❤️:

![Rspack Contributors](https://assets.rspack.rs/rspack/assets/rspack-v1-0-contributors.png)

## FAQ

### What does the 1.0 release mean?

The 1.0 release means that Rspack has implemented the core features of webpack and achieved API stability. Over the next 12 to 18 months, we will ensure the stability of the Rspack 1.x API so that developers can confidently build frameworks and tools on top of it. During the 1.x iteration, we may still find some designs require polishing in Rspack. We will address these through progressive upgrades using [future flags](https://v1.rspack.rs/config/experiments#experimentsrspackfuture).

### When will Rsbuild 1.0 be released?

We are currently preparing for the release of Rsbuild 1.0, which is scheduled for early September.

We have also released the Rsbuild 1.0 RC version, and there will be no further breaking changes introduced for Rsbuild. Please refer to [Migrating from Rsbuild 0.x](https://rsbuild.rs/guide/upgrade/v0-to-v1) to upgrade to Rsbuild 1.0 RC.

### Does Rspack follow semantic versioning?

Rspack follows semantic versioning (semver) and will not introduce breaking changes to the public API in minor or patch releases. Note that there are some exceptions:

> If your project has strict requirements for semantic versioning, you can pin Rspack to a minor version.

#### Experimental features

Rspack provides some experimental features that can be used via the [experiments](/config/experiments.md) config. In minor releases, Rspack may make changes to the APIs of these experimental features and provide detailed explanations of these changes in the release notes. So if you are using experimental features, please pay attention to the minor release notes.

#### SWC related features

Rspack is built on SWC, which is currently in the pre-1.0 phase. To keep up with the fixes and improvements in SWC, we regularly update the SWC version. This may include some breaking changes in SWC or break some versions of the SWC Wasm plugins. In such cases, we will release a minor version of Rspack and add a note to the changelog. if the SWC upgrade doesn't contain any breaking changes, we may upgrade SWC in a patch or minor release.

#### Types

In minor releases, the types exported by Rspack may change for the following reasons:

- TypeScript itself does not follow semver. It may introduce some breaking changes in minor releases that require Rspack to adjust its types.
- Rspack may use some features introduced in higher versions of TypeScript, which could affect projects using lower versions of TypeScript.

#### Bugfix for webpack compatibility

If the webpack API was mistakenly implemented in earlier versions of Rspack, we may fix it in non-major versions to align with the webpack API's behavior.



---
url: /blog/announcing-1-0-alpha.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 1.0 alpha

_June 29, 2024_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

![](https://assets.rspack.rs/rspack/rspack-banner-v1-0-alpha.png)

Rspack 1.0 alpha is now available on npm!

Before releasing Rspack 1.0 stable version, we will test for 1\~2 months to improve the API stability and reliability of v1.0 and to verify its impact on downstream projects.

Rspack 1.0 stable version is expected to be released this August. This is a significant milestone as it means that Rspack has implemented the major features and APIs of webpack. This will allow thousands of webpack projects to make a smooth transition while achieving significant improvements in build performance.

## Outputs optimization

Rspack 1.0 enables the `optimization.concatenateModules` by default during production builds. This option enables module concatenation optimization, also known as scope hoisting.

```js title="rspack.config.mjs"
export default {
  optimization: {
    // Now enabled by default in production
    concatenateModules: mode === 'production',
  },
};
```

The primary purpose of module concatenation is to merge multiple modules into a single function, thereby reducing the overhead associated with parsing and executing JavaScript code in the browser. By merging modules, redundant code such as import and export statements between modules can be reduced, resulting in smaller bundle sizes.

With module concatenation enabled, the output size of Rspack can be reduced by about **4% to 10%** (before Gzip).

Currently, Rspack has implemented most of the optimization strategies aligned with webpack. In future versions, Rspack will explore and make improvements based on webpack to provide deeper optimizations and smaller output sizes.

## Builtin Lightning CSS

Rspack 1.0 has built-in integration with [Lightning CSS](https://github.com/parcel-bundler/lightningcss). Lightning CSS is an extremely fast CSS parser, transformer, bundler, and minifier written in Rust.

The new version of Rspack has implemented the CSS minimizer plugin based on Lightning CSS, and it is now the default CSS minimizer of Rspack. Compared to the previously used SWC CSS minimizer plugin, it applies more optimizations to make the CSS output smaller.

```diff title="rspack.config.mjs"
export default {
  optimization: {
    minimizer: [
      // The default CSS minimizer changed:
-     new rspack.SwcCssMinimizerRspackPlugin()
+     new rspack.LightningCssMinimizerRspackPlugin()
    ],
  },
};
```

You can switch back to `SwcCssMinimizerRspackPlugin` by following configuration.

```js
export default {
  optimization: {
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin(),
      new rspack.SwcCssMinimizerRspackPlugin(),
    ],
  },
};
```

For example, Rspack already has tree shaking for CSS Modules, but it only removes unused CSS Modules classnames referenced by JS files. With the [unusedSymbols](https://lightningcss.dev/minification.html#unused-symbols) option of Lightning CSS, Rspack can now eliminate unused declarations in CSS Modules files, including IDs, keyframes, CSS variables or other CSS identifiers.

We believe that Lightning CSS will become the shared foundation for the next generation build tools, and Rspack will support more CSS compilation features based on Lightning CSS.. Thanks to [@devongovett](https://github.com/devongovett) for creating such an excellent tool.

## Lean core

To ensure the long term stability of Rspack v1, we have removed some non-core features that were built into the Rspack core. This allows the core to be lean and focused on providing common bundler features.

In v0.x, Rspack core has built-in SWC plugins to support Emotion, Styled Components, and Relay. This is because in the early days Rspack did not support the use of SWC Wasm plugins and could only integrate them into the core.

Currently, Rspack supports the use of SWC plugins via [experimental.plugins](/guide/features/builtin-swc-loader.md#jscexperimentalplugins) in `builtin:swc-loader`. So we have removed the built-in plugins from the Rspack core, including:

- [@swc/plugin-emotion](https://www.npmjs.com/package/@swc/plugin-emotion)
- [@swc/plugin-relay](https://www.npmjs.com/package/@swc/plugin-relay)
- [@swc/plugin-styled-components](https://www.npmjs.com/package/@swc/plugin-styled-components)

Take `@swc/plugin-styled-components` as an example. In v1.0, you can use it as follows.

- Installation:

```bash
npm i @swc/plugin-styled-components -D
```

- Configuration:

```diff
export default {
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        loader: "builtin:swc-loader",
        options: {
-         rspackExperiments: {
-           styledComponents: {},
-         },
          jsc: {
+           experimental: {
+             plugins: [["@swc/plugin-styled-components", {}]],
+           },
          },
        },
      },
    ],
  },
};
```

## Bundling CSS

Rspack 1.0 aligns with the webpack [experiment.css](/config/deprecated-options.md#experimentscss) default value, making it easier to migrate from webpack to Rspack.

In the webpack ecosystem, there are three common approaches to bundling CSS files:

1. Use [css-loader](https://github.com/webpack/css-loader) and [mini-css-extract-plugin](https://github.com/webpack/mini-css-extract-plugin) to generate standalone CSS files.
2. Use [css-loader](https://github.com/webpack/css-loader) and [style-loader](https://github.com/webpack/style-loader) to inject CSS through `<style>` tags.
3. Use [experiment.css](/config/deprecated-options.md#experimentscss), an experimental feature introduced in webpack 5 that provides native CSS support.

In version 0.x, Rspack enabled `experiment.css` by default, which would conflict with css-loader. Users had to manually disable `experiment.css` to use css-loader.

Starting with Rspack 1.0, the default value of `experiment.css` changes to `false`, in line with webpack, allowing users to use any of the above approaches.

You can add the following configuration to continue using `experiment.css`:

```js title="rspack.config.mjs"
export default {
  experiments: {
    css: true,
  },
};
```

## How to upgrade

To install the alpha version of Rspack and Rspack CLI:

```bash
# npm
npm add -D --save-exact @rspack/core@alpha @rspack/cli@alpha

# yarn
yarn add -D --save-exact @rspack/core@alpha @rspack/cli@alpha

# pnpm
pnpm add -D --save-exact @rspack/core@alpha @rspack/cli@alpha
```

During the Rspack alpha testing, new versions will still introduce some breaking changes, which we will highlight in the changelog. Please read the changelog to understand the differences before upgrading.

For Rsbuild users, please wait for the release of Rsbuild 1.0 alpha version (expected in 1-2 weeks).

## Breaking changes

### resolve.tsConfigPath

`resolve.tsConfigPath` config has been removed, please use [resolve.tsConfig](/config/resolve.md#resolvetsconfig) instead.

```diff title="rspack.config.mjs"
export default {
  resolve: {
-   tsConfigPath: path.resolve(__dirname, './tsconfig.json'),
+   tsConfig: path.resolve(__dirname, './tsconfig.json'),
  },
};
```

### rspackExperiments.styledComponents

The `rspackExperiments.styledComponents` option of `builtin:swc-loader` has been removed, please use [@swc/plugin-styled-components](https://www.npmjs.com/package/@swc/plugin-styled-components) instead.

```diff
export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        loader: "builtin:swc-loader",
        options: {
-         rspackExperiments: {
-           styledComponents: true,
-         },
          jsc: {
+           experimental: {
+             plugins: [["@swc/plugin-styled-components", {}]],
+           },
          },
        },
      },
    ],
  },
};
```

### rspackExperiments.emotion

The `rspackExperiments.emotion` option of `builtin:swc-loader` has been removed, please use [@swc/plugin-emotion](https://www.npmjs.com/package/@swc/plugin-emotion) instead.

```diff
export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        loader: "builtin:swc-loader",
        options: {
-         rspackExperiments: {
-           emotion: true,
-         },
          jsc: {
+           experimental: {
+             plugins: [["@swc/plugin-emotion", {}]],
+           },
          },
        },
      },
    ],
  },
};
```

### rspackExperiments.relay

The `rspackExperiments.relay` option of `builtin:swc-loader` has been removed, please use [@swc/plugin-relay](https://www.npmjs.com/package/@swc/plugin-relay) instead.

```diff
export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        loader: "builtin:swc-loader",
        options: {
-         rspackExperiments: {
-           relay: true,
-         },
          jsc: {
+           experimental: {
+             plugins: [["@swc/plugin-relay", {}]],
+           },
          },
        },
      },
    ],
  },
};
```

### Others

Other breaking changes:

- `optimization.chunkIds` defaults to `'natural'` when `mode === 'none'`, see [#6956](https://github.com/web-infra-dev/rspack/pull/6956).
- `optimization.moduleIds` defaults to `'natural'` when `mode === 'none'`, see [#6956](https://github.com/web-infra-dev/rspack/pull/6956).
- Rust crate `swc_core` has been upgraded to `0.95.x`, please upgrade your SWC Wasm plugin, see [#6887](https://github.com/web-infra-dev/rspack/pull/6887).
- Removed `output.amdContainer`, use `output.library.amdContainer` instead, see [#6958](https://github.com/web-infra-dev/rspack/pull/6958).
- Removed `Compilation.currentNormalModuleHooks`, see [#6859](https://github.com/web-infra-dev/rspack/pull/6859).
- Removed `stats.modules[].profile.integration`, see [#6947](https://github.com/web-infra-dev/rspack/pull/6947).
- Removed some options for `SwcJsMinimizerRspackPluginOptions`, see [#6950](https://github.com/web-infra-dev/rspack/pull/6950).



---
url: /blog/announcing-0-7.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 0.7

_May 28, 2024_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

![](https://assets.rspack.rs/rspack/rspack-banner-v0-7.png)

Rspack v0.7 has been released!

This is the last minor release before the Rspack v1.0. After this, the Rspack team will focus on the development of v1.0 and aim to launch the Rspack v1.0 alpha version soon.

Notable changes in Rspack v0.7:

- [Support for Lazy Compilation](#support-for-lazy-compilation): Significantly improves the dev startup performance of large applications by compiling on demand.
- [Faster CSS Build](#faster-css-builds): Introducing a new css-module-lexer, which increases CSS bundling speed by 4 times.
- [Breaking changes](#breaking-changes): Removed some unstable APIs to make default behaviors more consistent with webpack.

## Support for lazy compilation

Rspack v0.7 now supports lazy compilation, which is very helpful for improving the dev startup performance of multi-page applications (MPA) or large single-page applications (SPA).

### What is lazy compilation

Lazy compilation is an excellent way to improve startup performance. It compiles modules on demand rather than compiling all modules at startup. This means developers can quickly see the application running when they start the dev server and build the necessary modules in stages.

### Why need lazy compilation

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.

With lazy compilation enabled, Rspack will only compile the entrypoints and dynamic import modules that are requested. This can significantly reduce the number of modules that are compiled at development startup, improving startup time.

Consider the following scenario:

Your team is developing an MPA application with dozens of pages. Most of the time, you only work on a few pages and don't need to build the code for other pages. In this case, you can enable lazy compilation, allowing Rspack to compile only the modules referenced by the pages you access.

When lazy compilation is enabled, Rspack treats "entry points" and "dynamic imports" as split points. For example:

```js title="src/a.js"
if (someCondition) {
  import('./b.js');
}
```

When we compile a.js, Rspack treats b.js as an empty module, as if no code had ever been written to it. As soon as we need to access b.js, Rspack fills the b.js module with its original content, as if the user had just written that piece of code.

Take the Rspack documentation site as an example, it contains several pages. With lazy compilation is enabled, only the entry points and their dependent modules will be built. This greatly improves startup speed, reducing the startup time from 2.1 seconds to 0.05 seconds.

When a developer accesses a particular page of the site, the build for that page is triggered, and this build time will still be significantly less than the full build time.

![lazy-compilation-compare](https://assets.rspack.rs/rspack/assets/lazy-compilation-compare.png)

### How to use

Now, you can enable the lazy compilation feature in Rspack through the [experiments.lazyCompilation](/config/lazy-compilation.md) configuration:

```js title="rspack.config.mjs"
const isDev = process.env.NODE_ENV === 'development';

export default {
  experiments: {
    lazyCompilation: isDev,
  },
};
```

Please note that the current lazy compilation aligns with the webpack implementation, **and is still in the experimental stage**. In some scenarios, lazy compilation might not work as expected, or the performance improvement may be insignificant.

We will continue to improve the usability of lazy compilation in different scenarios to achieve a more stable state. If you encounter any issues while using it, feel free to provide feedback to us via [GitHub Issues](https://github.com/web-infra-dev/rspack/issues).

## Faster CSS builds

In v0.7, we have refactored the internal implementation of the [experiments.css](/config/deprecated-options.md#experimentscss).

For CSS dependency analysis, we have developed [css-module-lexer](https://github.com/ahabhgk/css-module-lexer) using Rust. This is a high performance lexer for CSS Modules that can parse CSS or CSS Modules and return their dependency metadata.

With the integration of css-module-lexer, Rspack can now support more complex CSS Modules syntax, making its behaviour align with webpack's `css-loader`. For example, it can support the following CSS Modules syntax:

```css title="style.module.css"
:local(.parent):global(.child) > ul {
  color: red;
}
```

The CSS parsing process before and after the refactor is shown in the diagram below:

![rspack-css-lexer](https://assets.rspack.rs/rspack/assets/rspack-css-lexer.png)

`css-module-lexer` has also brought significant performance improvements to Rspack's `experiments.css`. In performance tests, the building performance of `bootstrap.css` has increased by about 4x.

- Before refactoring: \~84 ms (analyzing CSS dependencies \~71 ms)
- After refactoring: \~25 ms (analyzing CSS dependencies \~11 ms)

## Breaking changes

Rspack will gradually remove all unstable APIs and configurations before version 1.0, and more configurations / APIs / default behaviors will be align with webpack.

### Deprecating unstable JavaScript APIs

Rspack early exposed some APIs that were intended for internal use only and were unstable, such as `compiler.compilation` and `compiler.builtinPlugins`. These APIs were not stable and could not be used in webpack.

In v0.7, we reorganized the currently exposed APIs and their interface definitions. If you have been using these APIs, you will need to make the necessary adjustments to align with the implementations consistent with webpack.

The following APIs are deprecated:

- `compiler.builtinPlugins`
- `compiler.compilation`
- `compiler.compilationParams`
- `compiler.getAsset(name)`
- `statsError.formatted`
- `statsWarning.formatted`
- ...

For details about the deprecated API, please refer to [rspack#6448](https://github.com/web-infra-dev/rspack/pull/6448), [rspack#6505](https://github.com/web-infra-dev/rspack/pull/6505).

### CSS @import rules must precede all other rules

In Rspack 0.7, we have partially refactored the internal implementation of [experiments.css](/config/deprecated-options.md#experimentscss).

After refactoring, when `@import` is not at the top, you will get the following error. In this case, you need to manually adjust the `@import` rule to the top.

```bash
ERROR in ./src/main.css
  × Module parse failed:
  ╰─▶   × CSS parsing warning: Any '@import' rules must precede all other rules
         ╭─[4:1]
       4 │ };
       5 │
       6 │ @import 'bootstrap/dist/css/bootstrap.css';
         · ───────
       7 │
       8 │
         ╰────

  help:
        You may need an appropriate loader to handle this file type.
```

### Remove builtins and experiments.rspackFuture.newTreeshaking

v0.7 has removed the `builtins.treeShaking` (oldTreeShaking) and `experiments.rspackFuture.newTreeshaking` (new tree shaking switch) configurations, taking the old tree shaking functionality completely offline.

### Remove resolve.browserField

This configuration is shorthand for `resolve.aliasFields = ["browser"]`, and since Rspack already supports `resolve.aliasFields`, this configuration is no longer necessary.

### Remove experiments.newSplitChunks

This configuration is used to enable the new splitChunks implementation, and since Rspack already uses the new splitChunks implementation by default, this configuration is no longer needed.

### Remove snapshot

This configuration is used to control the snapshot strategy when using cache. Under Rspack's current incremental rebuild architecture, cache no longer relies on snapshot, so this configuration is no longer needed.

### Remove exportsConvention for module type css

This configuration is used to control the naming convention of CSS module exports in experiments.css. It only has an effect on modules with the module type `css/module`, which have exports. For modules with the module type `css`, there are no exports, so this configuration is not needed.

### Upgrade SWC to 0.91.x

Upgraded the Rust crate `swc_core` to `0.91.x`. This will affect users of the SWC Wasm plugin.

## Migration guide

### Upgrade the SWC plugins

In version v0.7, the Rust crate `swc_core` has been upgraded to `0.91.x`. Users of the SWC Wasm plugin need to ensure version consistency with `swc_core` being used, otherwise, it may lead to unforeseen issues.

For more details, please see this [document](https://swc.rs/docs/plugin/selecting-swc-core#091x) of SWC.

### Replace resolve.browserField with resolve.aliasFields

If you previously configured `resolve.browserField`, you will need to replace it with `resolve.aliasFields`:

- `resolve.browserField = true` is replaced with `resolve.aliasFields = ["browser"]`
- `resolve.browserField = false` is replaced with `resolve.aliasFields = []`

### Remove generator.css.exportsConvention

If you previously configured `module.generator.css.exportsConvention` or `generator.exportsConvention` in `module.rule`, you only need to delete that configuration.

## Rsbuild v0.7

Rsbuild v0.7 has been released with Rspack v0.7, please read [Announcing Rsbuild v0.7](https://v0.rsbuild.rs/community/releases/v0-7) to learn more.



---
url: /blog/announcing-0-6.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 0.6

_April 10, 2024_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

## Major feature updates

### Built-in support for mini-css-extract-plugin

Now you can use `rspack.CssExtractRspackPlugin` as a replacement for `mini-css-extract-plugin`.

This is very useful in some scenarios, for example when the built-in CSS parser cannot meet your needs, there are more customized CSS Modules names, or you want to use some loaders that depend on the output of css-loader, but still want to extract the CSS into a separate file.

For more details, please see [CssExtractRspackPlugin](/plugins/css-extract-rspack-plugin.md#cssextractrspackplugin).

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.CssExtractRspackPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
      },
    ],
  },
};
```

> There is an basic [project example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/react-with-extract-css).

### Enable new tree shaking by default

In Rspack 0.1.0, basic tree shaking functionality was introduced. Due to the initial architecture being unstable, we employed a relatively simplistic approach to implement the basic version of tree shaking (only support unused export variables elimination). However, as rspack's capabilities improved, the architecture gradually stabilized.

The basic tree shaking functionality was insufficient to meet user needs, for example:

1. It couldn't handle circular references and couldn't provide enough optimization information for other build stages to achieve further optimization (such as mangleExports, concatenateModules, barrel exports optimization).
2. Some interoperability-related issues often occurred, such as worker-thread modules, Common Js modules, module federation, etc.

To address these issues, we decided to adopt a webpack-like approach, re-implementing the entire optimization process from the bottom up. In version 0.4.2, we introduced the `experiments.rspackFuture.newTreeshaking` configuration to experimentally enable the new optimization algorithm.
After four months of bug fixing and optimization, the new tree shaking algorithm has become relatively stable. Therefore, we've decided to default-enable the new tree shaking algorithm in version 0.6.0.

## Breaking changes

### Remove experiments.rspackFuture.disableApplyEntryLazily

The `experiments.rspackFuture.disableApplyEntryLazily` option has been enabled by default since v0.5.0 and was removed in v0.6.0.

### Remove compiler.build and compiler.rebuild

`compiler.build` and `compiler.rebuild` are not part of the webpack public API and have now been removed.

### Remove builtins.css and introduce CSS related module.parser and module.generator options

Remove `builtins.css`, please replace it with the CSS-related [`module.parser`](/config/module-parser.md#cssauto) and [`module.generator`](/config/module-generator.md#cssauto) options that have been introduced.

Also, starting from v0.6.0, Rspack's experiments CSS will align with webpack's experiments CSS as a target, which means that, like webpack experiments CSS, it will no longer support [browsers that do not support CSS variables](https://caniuse.com/css-variables) in the future. Therefore, for those projects that need to use configurations not yet supported by experiments CSS, or need to support older browsers, we recommend migrating to [`rspack.CssExtractRspackPlugin`](/plugins/css-extract-rspack-plugin.md).

In v0.6.0, we introduced three new types of `module.generator` and `module.parser` options: `css/auto`, `css`, and `css/module`, which will only take effect when experiments.css is enabled, checkout [this example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/css-parser-generator-options) about how to use it.

In the `module.parser` options, module types `css`, `css/auto`, and `css/module` all include the `namedExports` property. It has replaced the `builtins.css.namedExports` configuration.

For the `module.generator` options, the `css/auto` and `css/module` module types offer the `exportsOnly`, `exportsConvention`, and `localIdentName` properties. The `css` type includes only the `exportsOnly` and `exportsConvention` properties. `exportsOnly`, `exportsConvention`, and `localIdentName` respectively replace `builtins.css.modules.exportsOnly`, `builtins.css.modules.localsConvention`, and `builtins.css.modules.localIdentName`.

In addition, there are some changes to the default values:

1. The value of `exportsConvention` has changed from `'asIs'`, `'camelCaseOnly'`, etc., to `'as-is'`, `'camel-case-only'`, etc., to maintain consistency with webpack experiments css.

2. With `namedExports: false`, it is now possible to use default exports, named exports, and namespace exports at the same time; previously, only the default export was supported:

   ```js
   // Before v0.6.0, only default export was supported
   import classes from './index.module.css';

   // Now, in addition to default export, it also supports:
   // Namespace exports
   import * as classes from './index.module.css';
   // Named exports
   import { class1, class2 } from './index.module.css';
   // Default and named exports used together
   import classes, { class1, class2 } from './index.module.css';
   ```

3. The default value of `namedExports` changed from `false` to `true`, meaning you'll have to use a namespace import (like `import * as classes from './style.css'`) or named import (like `import { class1 } from './style.css'`) by default, which will improve future compatibility with [native CSS module](https://web.dev/articles/css-module-scripts). And this does not mean you have to migrate all imports at once; you can disable this behavior by setting `namedExports: false`, and since now `namedExports: false` also supports named export and namespace export, you can migrate these imports progressively.

4. The default value of `localIdentName` has changed from `'[path][name][ext]__[local]'` in development mode and `'[hash]'` in production mode to `'[uniqueName]-[id]-[local]'` in both development and production modes, which will slightly improve the gzip compression size of the CSS output.

5. The default value of `exportsOnly` in `target: 'node'` has changed from `false` to `true`.

6. The default rule type for CSS has changed from `css` to `css/auto`. `css/auto` will automatically process CSS files with `.module.` or `.modules.` as infixes as [CSS Modules](https://github.com/css-modules/css-modules), consistent with [`css-loader`'s `modules.auto: true`](https://github.com/webpack/css-loader?tab=readme-ov-file#auto), which will [simplify the writing rules for using less or sass with CSS Modules](https://github.com/webpack/webpack/issues/16572).

### Upgrade SWC to 0.90.x

Upgraded the Rust crate `swc_core` to `0.90.x`. This will affect users of the SWC Wasm plugin.

### Emit warnings when CSS order is inconsistent in multiple chunks

When the order of CSS in multiple chunks is inconsistent, a warning will be issued. For example, if you have two entries, `entryA` and `entryB`, where `entryA` imports `a.css` and then `b.css`, while `entryB` imports `b.css` and then `a.css`.
When splitChunks conditions are met, `a.css` and `b.css` will become a separate chunk. The order of `a.css` and `b.css` in this chunk cannot be guaranteed, resulting in the following warning.

```bash
WARNING in ⚠ chunk src_a_css-src_b_-5c8c53 [css-extract-rspack-plugin]
  │ Conflicting order. Following module has been added:
  │  * css ./css-loader/dist/cjs.js??ruleSet[1].rules[2].use[1]!./src/a.css
  │ despite it was not able to fulfill desired ordering with these modules:
  │  * css ./css-loader/dist/cjs.js??ruleSet[1].rules[2].use[1]!./src/b.css
  │   - couldn't fulfill desired order of chunk group(s) parent2
  │   - while fulfilling desired order of chunk group(s) parent1
```

If you are sure that their order inconsistency does not matter, you can ignore this error by configuring `ignoreWarnings`.

```js title="rspack.config.mjs"
export default {
  ignoreWarnings: [/Conflicting order/],
};
```

## Migration guide

### Apply rspack.CssExtractRspackPlugin

If you have used `mini-css-extract-plugin` and webpack before, you can simply replace `mini-css-extract-plugin` by `rspack.CssExtractPlugin`.

```diff title="rspack.config.mjs"
+ import { rspack } from '@rspack/core';
- import CssExtract from 'mini-css-extract-plugin';

export default {
  plugins: [new rspack.CssExtractRspackPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [CssExtract.loader, 'css-loader'],
      },
    ],
  },
};
```

### Migrate from builtins.css

1. Use `module.parser["css/auto"].namedExports` to replace `builtins.css.namedExports`.
2. Use `module.generator["css/auto"].exportsOnly` to replace `builtins.css.modules.exportsOnly`.
3. Use `module.generator["css/auto"].exportsConvention` to replace `builtins.css.modules.localsConvention`.
4. Use `module.generator["css/auto"].localIdentName` to replace `builtins.css.modules.localIdentName`.

The above occurrences of `"css/auto"` are the default module type for CSS, which can be modified to `"css"` or `"css/module"` as needed.

Add the following configuration to maintain the original default behavior of `builtins.css`, which can be modified as needed based on the following setup:

```diff title="rspack.config.mjs"
export default {
+  module: {
+    generator: {
+      "css/auto": {
+        exportsOnly: false,
+        exportsConvention: 'as-is',
+        localIdentName: isProduction ? '[hash]' : '[path][name][ext]__[local]',
+      },
+      "css": {
+        exportsOnly: false,
+        exportsConvention: 'as-is',
+      },
+      "css/module": {
+        exportsOnly: false,
+        exportsConvention: 'as-is',
+        localIdentName: isProduction ? '[hash]' : '[path][name][ext]__[local]',
+      },
+    },
+    parser: {
+      "css/auto": {
+        namedExports: false,
+      },
+      "css": {
+        namedExports: false,
+      },
+      "css/module": {
+        namedExports: false,
+      },
+    },
+  },
}
```

If it is necessary to configure some modules separately, you can use the [`rules[].parser`](/config/module-rules.md#rulesparser) and [`rules[].generator`](/config/module-rules.md#rulesgenerator) options in `module.rules`.

### Migrate to compiler.run

`compiler.build` or `compiler.rebuild` have been deprecated. Please switch to `compiler.run` for both building and rebuilding.

### Upgrade the SWC plugins

In version `0.6.0`, the Rust crate `swc_core` has been upgraded to `0.90.x`. Users of the SWC Wasm plugin need to ensure version consistency with `swc_core` being used, otherwise, it may lead to unforeseen issues.

For more details, please see this [document](https://swc.rs/docs/plugin/selecting-swc-core#090x) of SWC.



---
url: /blog/announcing-0-5.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 0.5

_January 09, 2024_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

## Major feature updates

### Module Federation added to Rspack

Checkout [this blog](/blog/module-federation-added-to-rspack.md) for more details.

## Breaking changes

### optimization.chunkIds is deterministic in production mode by default

`optimization.chunkIds` is `"deterministic"` now in production mode, which aligns with webpack's default behavior.

### Support rspack.HotModuleReplacementPlugin

Support `rspack.HotModuleReplacementPlugin` in Rspack. If you are not using `@rspack/dev-server` and using a custom dev server, you need to apply `HotModuleReplacementPlugin` to enable HMR instead of setting `devServer.hot` to `true`, which is the same in webpack. This provides more compatibility with the plugin which uses `HotModuleReplacementPlugin` internally.

### Remove default transformation

Default transformation is a builtin, which internally transforms source files (such as TypeScript), into compatible sources (such as JavaScript). To make the transformation more customizable, we handed out this feature to users by using `builtin:swc-loader` and dropped the support of several [rules\[\].type](/config/module-rules.md#rulestype). These `rules[].type`s are dropped:

- `"typescript"` or `"ts"`
- `"tsx"`
- `"jsx"`

In order to achieve old behavior, please remove `rules[].type` or change it to `"javascript/auto"` and apply your custom loader configurations.

To transform a `.jsx` file:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        exclude: /[\\/]node_modules[\\/]/,
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            parser: {
              syntax: 'ecmascript',
              jsx: true,
            },
          },
        },
      },
    ],
  },
};
```

To transform a `.tsx` file:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.tsx$/,
        exclude: /[\\/]node_modules[\\/]/,
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            parser: {
              syntax: 'typescript',
              tsx: true,
            },
          },
        },
      },
    ],
  },
};
```

To transform a `.ts` file:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.ts$/,
        exclude: /[\\/]node_modules[\\/]/,
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            parser: {
              syntax: 'typescript',
            },
          },
        },
      },
    ],
  },
};
```

### target does not affect user code anymore

Rspack aligns [target](/config/target.md) with webpack. Instead of transforming arbitrary user code, Rspack now lets loaders control the transformation of user land code. To transform user land code to which your target environment(s) needed, add `env` to `builtin:swc-loader`:

```diff title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /[\\/]node_modules[\\/]/,
        loader: "builtin:swc-loader",
        options: {
          jsc: {
            parser: {
              syntax: "ecmascript"
            }
          },
+         env: {
+           targets: "Chrome >= 48"
+         }
        }
      }
    ]
  }
}
```

### Remove extended resolve extensions

`resolve.extensions` helps us to omit certain file extensions during resolution. In previous versions, `.ts`, `.tsx`, `.jsx` are supported and these extensions are removed in the latest version, which aligns with webpack's behavior.

In order to get the same behavior, change `resolve.extensions` to this:

```js title="rspack.config.mjs"
export default {
  resolve: {
    extensions: ['...', '.tsx', '.ts', '.jsx'], // "..." means to extend from the default extensions
  },
};
```

### Make @swc/helpers and react-refresh as peerDependencies

Before we remove default transformation, it's possible to use it to degrade your code to es5 by `target`, and insert the react refresh helper code into your react component by `builtin.react.refresh`, so we installed the `@swc/helpers` and `react-refresh` as the dependencies of `@rspack/core`, to provide the out-of-box experience. But since we removed the default transformation now, and recommend using Rsbuild for the out-of-box experience, the `@swc/helpers` and `react-refresh` no longer need to be installed by `@rspack/core`, and we make them as peerDependencies of `@rspack/core`.

If you are using `externalHelpers: true` with `builtin:swc-loader` or `swc-loader`, now you need to install `@swc/helpers` as dependencies of your project. If you are using `@rspack/plugin-react-refresh`, now you need to install `react-refresh` as devDependencies of your project.

### Remove deprecated builtins options

Some of the builtins options have been deprecated since v0.4.0.

If you are still using `builtins.noEmitAssets`, `builtins.devFriendlySplitChunks`, `builtins.react`, `builtins.html`, `builtins.copy`, `builtins.minifyOptions`, checkout [migrating builtin options to builtin plugins](/blog/announcing-0-4.md#migrating-builtin-options-to-builtin-plugins) to migrate.

And if you are still using `builtins.presetEnv`, `builtins.decorator`, `builtins.pluginImport`, `builtins.emotion`, `builtins.relay`, checkout the migration guide [here](/blog/announcing-0-4.md#deprecating-default-transformation).

### Remove builtin:sass-loader

`builtin:sass-loader` has been deprecated since v0.4.0. It's removed in v0.5.0. If you are still using it, migrate to `sass-loader`.

### Remove experiments.incrementalRebuild options

`experiments.incrementalRebuild` options has been deprecated since v0.4.0. It's removed in v0.5.0.

### Remove builtins.devFriendlySplitChunks and experiments.newSplitChunks

`experiments.newSplitChunks` and `builtins.devFriendlySplitChunks` has been deprecated since v0.4.0. It's removed in v0.5.0.

### Remove experiments.rspackFuture.newResolver options

`experiments.rspackFuture.newResolver` has been deprecated since v0.4.0. It's removed in v0.5.0.

### Deprecating apply entry lazily

Apply entry lazily is deprecating by rspackFuture: [experiments.rspackFuture.disableApplyEntryLazily](https://v0.rspack.rs/config/experiments#experimentsrspackfuturedisableapplyentrylazily), which is introduced in v0.4.5, enabled by default in v0.5.0, and will be removed in v0.6.0.

When `experiments.rspackFuture.disableApplyEntryLazily` is `false`, `options.entry` can still make valid changes after `rspack(options)` is called, but with `true` it can't, and it's behave the same as webpack5.

This configuration has no effect on users developing applications in Rspack most of the time, but should be noted by developers of Rspack plugins or higher-level frameworks.

## Migration guide

v0.5.0 removed lots of deprecated features, except that, v0.5.0 introduced four breaking changes, and you only need to notice two of them if you are developing applications using Rspack. So v0.5.0 is easy to migrate if you already migrate to v0.4+ with no deprecate warnings, if you haven't, checkout the [v0.4.0 migration guide](/blog/announcing-0-4.md#migration-guide).

### Add resolve.extensions

This is a breaking change that is most likely to affect you.

After you upgrade `@rspack/core` to v0.5.0, if you build failed with error: `Can't resolve './src/foo.tsx'`, or `Can't resolve './src/foo.ts'`, or `Can't resolve './src/foo.jsx'`, you need to add `resolve.extensions = ['...', '.tsx', '.ts', '.jsx']` in your configuration.

```diff
const configuration = {
  resolve: {
+   extensions: ['...', '.tsx', '.ts', '.jsx'],
  },
}
```

You only need to add the needed extensions to `resolve.extensions`. For example, if you are not using any `.tsx` or `.ts` files, only using `.js` or `.jsx` files, then you only need to add `'.jsx'` to resolve.extensions. `'.js'` is one of the default extensions and all default extensions (`['.js', '.json', '.wasm']`) are represented by `'...'`.

### Install @swc/helpers or react-refresh

This is a breaking change that is most likely to affect you.

After you upgrade `@rspack/core` to v0.5.0, if you build failed with error: `Failed to resolve @swc/helpers/some-helper` or `Failed to resolve react-refresh/some-module`, you need to install `@swc/helpers` or `react-refresh` in your project.

If you are using `externalHelpers: true` with `builtin:swc-loader` or `swc-loader`, now you need to install `@swc/helpers` as dependencies of your project.


```sh [npm]
npm install @swc/helpers
```

```sh [yarn]
yarn add @swc/helpers
```

```sh [pnpm]
pnpm add @swc/helpers
```

```sh [bun]
bun add @swc/helpers
```

```sh [deno]
deno add npm:@swc/helpers
```

If you are using `@rspack/plugin-react-refresh`, now you need to install `react-refresh` as devDependencies of your project.


```sh [npm]
npm install react-refresh
```

```sh [yarn]
yarn add react-refresh
```

```sh [pnpm]
pnpm add react-refresh
```

```sh [bun]
bun add react-refresh
```

```sh [deno]
deno add npm:react-refresh
```

### Apply rspack.HotModuleReplacementPlugin

If you are using `@rspack/cli`, or rsbuild, or other higher-level framework of Rspack to develop applications, you don't need to worry about this. This should be well handled by the higher-level framework or cli. But if you are using `@rspack/core` with a custom dev server (not `@rspack/dev-server` or `webpack-dev-server`), or developing a custom dev server, you need to notice this.

Before enabling HMR in Rspack is setting `devServer.hot` to `true`, but now you need to apply `HotModuleReplacementPlugin` by yourself in your custom dev server.

```diff
class CustomDevServer {
  enableHMR(compiler) {
-   compiler.options.devServer ??= {};
-   compiler.options.devServer.hot = true;
+   new compiler.rspack.HotModuleReplacementPlugin().apply(compiler);
  }
}
```

### Do not change entry options after rspack(options)

If you are using `@rspack/cli`, or rsbuild, or other higher-level framework of Rspack to develop applications, you don't need to worry about this. This should be well handled by the higher-level framework or cli. But if you are developing a plugin or higher-level framework, you need to notice this.

Before prepending an extra entry in Rspack is prepending it to `compiler.options.entry`, but now you need to apply `EntryPlugin` by yourself.

```diff
const { rspack } = require('@rspack/core');
const compiler = rspack(options);

function prependEntry(compiler, additionalEntry) {
-  for (const key in compiler.options.entry) {
-    compiler.options.entry[key].import = [
-      additionalEntry,
-      ...(compiler.options.entry[key].import || []),
-    ];
-  }
+  new compiler.rspack.EntryPlugin(compiler.context, additionalEntry, {
+    name: undefined, // `name: undefined` to prepend the it to every entry, or add it to a specified entry with specified entry name
+  }).apply(compiler);
}

prependEntry(compiler, 'dev-client.js');
```



---
url: /blog/module-federation-added-to-rspack.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Module Federation added to Rspack

_January 09, 2024_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

## Introducing Rspack 0.5.0

The latest Rspack 0.5.0 introduces the highly anticipated Module Federation along with the new "v1.5" federation APIs. It marks the most substantial revamp of federation since its inception. The v1.5 offers extra capabilities for end users and framework authors, a feat unattainable with the original design.


![Rspack with Infinity Gauntlet](https://assets.rspack.rs/rspack/assets/rspack-federation-with-rspack.png)

## Webpack federation gets some love!

Federation API has been opened up for users to enrich, expand, or manage the lifecycle. While v1.5 comes with several new capabilities, it doesn't introduce breaking changes to the API regarding the original Module Federation.

v1.5 is also accessible to webpack via [@module-federation/enhanced](https://www.npmjs.com/package/@module-federation/enhanced) with the upper plugin ecosystem, such as the next.js federation or node.js federation plugins, already utilizing v1.5 in their canary releases.

In Rspack, Module Federation v1.5 can be used through `rspack.container.ModuleFederationPlugin`, and the original Module Federation can be used through `rspack.container.ModuleFederationPluginV1`.

## Migration opportunities

The support of Module Federation in Rspack opens up a several of creative migration options to speed up bundler tools by sharing code at runtime. Both webpack and Rspack can share code, relying on the same centralized runtime that the Module Federation Group introduced in v1.5. This ensures maintaining feature parity is manageable, and no additional forks of Module Federation are necessary to customize it.

**Progressive migration** to Rspack can be achieved via federation. If you have webpack locked plugins or cannot perform a full cut over to rspack, via module federation you can allow Rspack and webpack to share dependencies and code, meaning more code could be built via Rspack while the webpack host does less work but still gets the same result. [example: webpack Rspack interop](https://github.com/module-federation/module-federation-examples/pull/3490)

**Speed up builds by sharing the node\_modules via federation**. One could tell webpack to `import: false` them, and Rspack could compile all the shared modules, reducing the parse overhead and amount of code the webpack part has to do, by delegating it to Rspack where similar workloads take only a few milliseconds to perform. [example: Rspack Vendor Offload to webpack apps](https://github.com/module-federation/module-federation-examples/pull/3491)

**Migrate one at a time**. Since the interfaces between webpack ([@module-federation/enhanced](https://www.npmjs.com/package/@module-federation/enhanced)) and Rspack are shared, users can switch over any existing federation build or remote to Rspack. We recommend any remaining webpack builds using `@module-federation/enhanced` which leverages our new design and exports ModuleFederationPlugin. You can, however, still use the stock plugin that ships in webpack core. Rspack should slot in seamlessly with existing federated applications.

## Speed comparison to webpack federation

In a simple comparison, using a module federation [example](https://github.com/module-federation/module-federation-examples/tree/master/comprehensive-demo-react16)

- Apps: 5
- Webpack: 500-3000ms per build - production
- Rspack: 130-350ms per build - production

Generally, we have observed 5-10x gains in build speeds of federated applications, roughly in line with typical performance gains we see with rspack. Most builds in module federation examples. Development builds we have converted typically take less than 150ms to cold start.

## Rsbuild support

Rsbuild continues to offer a simplified approach to build configurations. It makes working with Rspack feel less like handling a webpack-based build system. Although it's compatible with module federation, Rsbuild will be utilized to offer a more streamlined experience with module federation. For instance, Rsbuild plugins for react could automatically share defaults, or Rsbuild could provide convenient presets and patterns.

We have already initiated the migration of some [module federation examples](https://github.com/module-federation/module-federation-examples) to Rspack and Rsbuild. One notable example is the CRA migration, which was seamless and took minutes to switch from CRA to Rsbuild [here](https://github.com/module-federation/module-federation-examples/tree/master/cra). This guide is also beneficial for CRA users seeking an easy performance boost for aging builds: [Rsbuild Migration Guide](/guide/migration/cra.md). Rsbuild has also been fantastic for [migrating Vue examples off vue-cli](https://rsbuild.rs/guide/migration/vue-cli) and onto something faster, easier, and federation friendly.

## The difference between federation v1 and v1.5

Originally Federation was quite bare. RemoteEntry exposed `{get, init}` interface and not much else. This ended up being very limiting, but was simple. As complex uses grew and more capabilities were discovered, it became clear we needed more control beyond the initial idea of just sharing code between builds and loading it.

v1.5 introduces runtimePlugins. These can be added to compile time via `runtimePlugins` options. But you can also dynamically register them in javascript files at runtime too.

In Rspack:

```js
import { rspack } from '@rspack/core';
import { fileURLToPath } from 'node:url';

new rspack.container.ModuleFederationPlugin({
  name: 'app1',
  filename: 'static/js/remoteEntry.js',
  exposes: {
    './Button': './src/components/button.js',
  },
  runtimePlugins: [
    fileURLToPath(new URL('./my-custom-plugin.js', import.meta.url)),
  ],
  remotes: {
    app2: 'app2@http://localhost:3002/static/js/remoteEntry.js',
  },
  shared: {
    react: { singleton: true },
    'react-dom': { singleton: true },
  },
});
```

And For webpack:

```js
import { ModuleFederationPlugin } from '@module-federation/enhanced';
import { fileURLToPath } from 'node:url';

new ModuleFederationPlugin({
  name: 'app1',
  filename: 'static/js/remoteEntry.js',
  exposes: {
    './Button': './src/components/button.js',
  },
  runtimePlugins: [
    fileURLToPath(new URL('./my-custom-plugin.js', import.meta.url)),
  ],
  remotes: {
    app2: 'app2@http://localhost:3002/static/js/remoteEntry.js',
  },
  shared: {
    react: { singleton: true },
    'react-dom': { singleton: true },
  },
});
```

Federation can also be used in a dynamic manner, without a compile-time plugin. You can read more about v1.5 runtime [here](https://github.com/module-federation/universe/tree/feat/async-boundary-option/packages/runtime)

```js
// Can load modules using only the runtime SDK without relying on build plugins
// When not using build plugins, shared dependencies cannot be automatically reused
import { init, loadRemote } from '@module-federation/runtime-tools';
import customPlugin from './runtimePlugin';

init({
  name: 'app1',
  remotes: [
    {
      name: 'runtime_remote1',
      alias: 'app2',
      entry: 'http://localhost:3006/remoteEntry.js',
    },
  ],
  shared: {
    react: {
      version: '18.2.0',
      scope: 'default',
      lib: () => React,
      shareConfig: {
        singleton: true,
        requiredVersion: '>17',
      },
    },
    'react-dom': {
      version: '18.2.0',
      scope: 'default',
      lib: () => ReactDOM,
      shareConfig: {
        singleton: true,
        requiredVersion: '>17',
      },
    },
  },
  plugins: [customPlugin()],
});

// Load by alias
loadRemote <
  { add: (...args: Array<number>) => number } >
  'app2/util'.then(md => {
    md.add(1, 2, 3);
  });
```

Read more about Federation 1.5 Update: [Module Federation 1.5](https://github.com/module-federation/universe/discussions/1936)



---
url: /blog/announcing-0-4.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 0.4

_November 22, 2023_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

## Major changes

### Drop Node.js 14 support

Rspack no longer supports Node.js 14, Node.js 16+ is now required.

### Make @rspack/core as peer dependency of @rspack/cli

`@rspack/core` is now a peer dependency of `@rspack/cli` rather than a direct dependency. This means that you need to manually install `@rspack/core` with `@rspack/cli` now. aligning Rspack more closely with webpack. In the long term, the positioning of `@rspack/cli` will no longer be an out-of-the-box solution. We will align `@rspack/cli` with webpack-cli and may even directly support the use of `@rspack/core` in `webpack-cli`. We recommend [Rsbuild](https://rsbuild.rs/) as an out-of-the-box solution.

### Deprecating default transformation

`experiments.rspackFuture.disableTransformByDefault` is enabled by default in v0.4.0. For people that still need the legacy behavior, you may manually set this option to `false`.

This feature primarily addresses three categories of problems: [builtins](https://v0.rspack.rs/config/builtins) code transformation features, [target](/config/target.md), and custom [rules\[\].type](/config/module-rules.md#rulestype).

1. Removal of support for some [builtins](https://v0.rspack.rs/config/builtins) features:

- [builtins.relay](https://v0.rspack.rs/config/builtins#builtinsrelay): moved to `rspackExperiments.relay`
- [builtins.react](https://v0.rspack.rs/config/builtins#builtinsreact): moved to `jsc.transform.react`
- [builtins.emotion](https://v0.rspack.rs/config/builtins#builtinsemotion): moved to `rspackExperiments.emotion`
- [builtins.pluginImport](https://v0.rspack.rs/config/builtins#builtinspluginimport): moved to `rspackExperiments.import`
- [builtins.decorator](https://v0.rspack.rs/config/builtins#builtinsdecorator): moved to `jsc.parser.decorators`
- [builtins.presetEnv](https://v0.rspack.rs/config/builtins#builtinspresetenv): moved to `jsc.env`

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            parser: {
              syntax: 'ecmascript',
              jsx: true,
            },
            transform: {
              react: {
                runtime: 'automatic',
              },
            },
          },
          rspackExperiments: {
            emotion: true, // The same as `builtins`
          },
        },
      },
    ],
  },
  experiments: {
    rspackFuture: {
      disableTransformByDefault: true,
    },
  },
};
```

2. [target](/config/target.md) will not downgrade user-side code(including `node_modules`)

```diff title="rspack.config.mjs"
export default {
  target: ["web", "es5"],
  module: {
    rules: [
      {
        test: /\.[cm]?js$/,
        exclude: /node_modules/,
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            parser: {
              syntax: "ecmascript"
            },
+           target: "es5" // Notice: `jsc.target` and `env` cannot be set at the same time.
          },
+        env: { //  Notice: `jsc.target` and `env` cannot be set at the same time.
+         targets: "chrome >= 48"
+        }
        }
      },
    ],
  }
};
```

3. Removed non-webpack compatible [rules\[\].type](/config/module-rules.md#rulestype)

These types have been removed:

- `"typescript"`
- `"jsx"`
- `"tsx"`

For JS-related types, only the following will be retained:

- `"javascript/auto"`
- `"javascript/esm"`
- `"javascript/dynamic"`

Refer to [this](https://v0.rspack.rs/config/experiments#experimentsrspackfuturedisabletransformbydefault) for the complete migration guide.

Check out our previous discussion [here](https://github.com/web-infra-dev/rspack/discussions/4070).

### Deprecating builtin.react.refresh

With `experiments.rspackFuture.disableTransformByDefault` is enabled by default in v0.4.0, `builtin.react.refresh` has also been deprecated. Now we recommend using `@rspack/plugin-react-refresh` to enable react fast refresh.

```diff title="rspack.config.mjs"
+ import { ReactRefreshRspackPlugin } from '@rspack/plugin-react-refresh';

const isDev = process.env.NODE_ENV === 'development';

export default {
  mode: isDev ? 'development' : 'production',
  module: {
    rules: [
      {
        test: /\.jsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'ecmascript',
                jsx: true,
              },
              transform: {
                react: {
+                  development: isDev,
+                  refresh: isDev,
                },
              },
            },
          },
        },
      },
    ],
  },
-  builtins: {
-    react: {
-      refresh: true,
-    }
-  },
  plugins: [
+    isDev && new ReactRefreshRspackPlugin()
  ],
};
```

Checkout [here](/guide/integrations/react.md#fast-refresh) for more details.

### Deprecating builtin:sass-loader

`builtin:sass-loader` has now been deprecated. If you are using it, migrate to `sass-loader`. Rspack will remove `builtin:sass-loader` in v0.5.0.

### Deprecating experiments.incrementalRebuild

`experiments.incrementalRebuild` has now been deprecated. Rspack will remove it in v0.5.0.

### Refactoring export API in @rspack/core

Before, some APIs should not be exported accidentally exported through re-export from @rspack/core. Now with this refactor, we clean up the export APIs from @rspack/core.

This shouldn't break anything, but if you are using unintentionally exported APIs, this may break you, and you may be using Rspack in the hacky way.

If there is a real need for removed APIs from this refactor, please raise an issue in the Rspack repository.

### Deprecating `builtins.devFriendlySplitChunks` and `experiments.newSplitChunks`

In order to full migrate to Webpack's split chunks implementation, these fields are deprecated. Rspack will remove these fields in v0.5.0.

### Enable newResolver by default

New resolver is now enabled by default.

The new resolver has passed all of [enhanced-resolve](https://www.npmjs.com/package/enhanced-resolve)'s test suite. It is 5 times faster than previous implementation, and 28 times faster than enhanced-resolve.

The new resolver can be configured to read `tsconfig.json`'s `compilerOptions.paths` and `references` field and provides better support for nested path alias. See API [resolve.tsConfig](/config/resolve.md#resolvetsconfig) for details.

To opt out of the new resolver, set `experiments.rspackFuture.newResolver` to `false`.

## Migration guide

There is a [migrate example](https://github.com/rstackjs/rstack-examples/pull/2) demonstrating how to migrate from Rspack 0.3.14 to Rspack 0.4.0.

### Choose `@rspack/cli` or `Rsbuild`?

If your application is a CSR application, we strongly encourage you to use Rsbuild instead of configuring Rspack yourself, as Rsbuild is much easier to use compared to `@rspack/cli`.

### Upgrade Node.js version

Rspack no longer supports Node.js 14 as of version 0.4.0; Node.js 16+ is now required.

### Install `@rspack/core` manually with `@rspack/cli`

```diff title=package.json
{
  "devDependencies": {
+    "@rspack/core": "0.4.0",
     "@rspack/cli": "0.4.0"
  }
}
```

### Use `builtin:swc-loader` to support module transformation

Rspack no longer transforms files by default as of version 0.4.0, you can still enable old transform behavior by the following setting

```js
{
  experiments: {
    rspackFuture: {
      disableTransformByDefault: false; // set to old transform behavior
    }
  }
}
```

But we suggest you use `builtin:swc-loader` to transform files now. More details are available in [Deprecating Default Transformation](#deprecating-default-transformation).

### Use `@rspack/plugin-react-refresh` for React applications

`builtin.react.refresh` does not work when we disable the default transformation, so you need to use `@rspack/plugin-react-refresh` to enable fast refresh. More details are available in [Deprecating builtin.react.refresh](#deprecating-builtinreactrefresh).

### Migrating builtin options to builtin plugins

In v0.4.0, Rspack deprecated some of the builtin options and migrated them to [builtin plugins](/config/plugins.md).

Currently, Rspack's internal plugins are divided into two categories:

- Plugins compatible with Webpack, such as DefinePlugin, ProvidePlugin, etc. This part has been fully aligned with webpack.
- Rspack-specific plugins, such as SwcJsMinimizerRspackPlugin, CopyRspackPlugin, etc.

The original `builtins.define` can be migrated as follows:

```diff title="rspack.config.mjs"
+ import { rspack } from '@rspack/core';

export default {
-  builtins: {
-    define: { process.env.NODE_ENV: JSON.stringify(process.env.NODE_ENV) }
-  },
+  plugins: [
+    new rspack.DefinePlugin({ process.env.NODE_ENV: JSON.stringify(process.env.NODE_ENV) })
+  ]
}
```

For `builtins.html`, it can be directly migrated to [HtmlRspackPlugin](/plugins/html-rspack-plugin.md):

```diff title="rspack.config.mjs"
+ import { rspack } from '@rspack/core';

export default {
-  builtins: {
-    html: [{ template: "./index.html" }]
-  },
+  plugins: [
+    new rspack.HtmlRspackPlugin({ template: "./index.html" })
+  ]
}
```

When there are multiple configurations in `builtins.html`, multiple plugin instances can be created:

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.HtmlRspackPlugin({ template: './index.html' }),
    new rspack.HtmlRspackPlugin({ template: './foo.html' }),
  ],
};
```

For `builtins.copy`, it can be directly migrated to [CopyRspackPlugin](/plugins/copy-rspack-plugin.md).

For the original `builtins.minifyOptions`, we provide [SwcJsMinimizerRspackPlugin](/plugins/swc-js-minimizer-rspack-plugin.md):

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  optimization: {
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin({
        // minimizer configuration
      }),
    ],
  },
};
```

Other builtin options can be directly referred to the rspack [builtin plugins](/config/plugins.md) for migration, or completed according to the CLI prompts after upgrading to v0.4.0.



---
url: /blog/announcing-0-3.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 0.3

_August 24, 2023_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

## Breaking changes

In version 0.3, Rspack aligns the default CSS handling behavior with webpack when set `experiments.css = true`. This involves removing many built-in CSS transformation logic, which introduces some breaking changes. If your application previously relied on these transformation logic, please pay attention to the migration steps below.

### Removal of @rspack/postcss-loader and builtins.postcss

Before Rspack fully supported `postcss-loader`, Rspack implemented `@rspack/postcss-loader` and built-in `builtins.postcss` to fulfill the functionality. Currently, Rspack fully supports `postcss-loader`, so we have decided to deprecate `@rspack/postcss-loader` and `builtins.postcss`. Users of `@rspack/postcss-loader` can seamlessly migrate to `postcss-loader`, while users that previously used Rspack's `builtins.postcss` for the `px2rem` conversion functionality can migrate to `postcss-loader` and `postcss-plugin-px2rem`. Here is the migration process:

• Before:

```js title="rspack.config.mjs"
export default {
  builtins: {
    postcss: {
      pxtorem: {
        rootValue: 50,
      },
    },
  },
};
```

• After:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: [
                  [
                    'postcss-plugin-px2rem',
                    {
                      rootValue: 100,
                    },
                  ],
                ],
              },
            },
          },
        ],
      },
    ],
  },
};
```

### Removal of built-in CSS autoprefixer functionality

To align better with webpack's CSS handling, Rspack removes the built-in autoprefixer functionality in 0.3. You can use `postcss-loader` to achieve `autoprefixer`.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                plugins: [['autoprefixer']],
              },
            },
          },
        ],
        type: 'css',
      },
    ],
  },
};
```

You can refer to the [examples/postcss-loader](https://github.com/rstackjs/rstack-examples/tree/main/rspack/postcss-loader) for a complete example.

### Access to internal modules restricted

Due to the current instability of the internal module API in Rspack, directly accessing the internal modules can easily lead to breaking changes. Therefore, Rspack restricts the ability to directly access internal modules and only supports accessing Rspack's API from the root module.

• Before:

```js
import { Stats } from '@rspack/core/dist/stats'; // not supported since 0.3
```

• After:

```js
import { Stats } from '@rspack/core';
```

## Major feature updates

### Web Workers support

Rspack natively supports Web Workers, which means you can use Web Workers out of the box without using worker-loader. Here is how to use it:

```js
new Worker(new URL('./worker.js', import.meta.url));
new Worker(new URL('./worker.js', import.meta.url), {
  name: 'my-worker',
});
```

For more information about web workers support, see [web workers](/guide/features/web-workers.md).

### `builtin:swc-loader` support

Although Rspack provides many SWC compilation configuration options, these configurations are global and cannot fulfill the requirement of using different SWC transformation logic for different modules. Therefore, Rspack supports `builtin:swc-loader` to provide more fine-grained SWC transformation configuration. Compared to the JavaScript version of `swc-loader`, `builtin:swc-loader` has better performance. You can use `builtin:swc-loader` as follows:

```js title="rspack.config.mjs"
import { defineConfig } from '@rspack/cli';

export default defineConfig({
  module: {
    rules: [
      {
        test: /\.jsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'ecmascript',
                jsx: true,
              },
              transform: {
                react: {
                  pragma: 'React.createElement',
                  pragmaFrag: 'React.Fragment',
                  throwIfNamespace: true,
                  development: false,
                },
              },
            },
          },
        },
      },
    ],
  },
});
```

You can refer to [examples/builtin-swc-loader](https://github.com/rstackjs/rstack-examples/tree/main/rspack/builtin-swc-loader) for more examples. Currently, `builtin:swc-loader` still has limitations, such as not supporting Wasm plugins, etc. Rspack will continue to iterate and support more features of `builtin:swc-loader` in future versions.

### Improved profile support

Performance optimization is a common requirement in business support. To reduce the cost of performance optimization for businesses, we have improved the experience of Rspack Profile. You can generate profile-related files for performance optimization by using the RSPACK\_PROFILE environment variable.

```sh
$ RSPACK_PROFILE=ALL rspack build
```

For more detailed information about Profile, see [Performance Profiling](/guide/diagnostics/profile.md).

Alignment with More APIs

- `splitChunks.chunks` supports regex.
- Supports `splitChunk.\{cacheGroup\}.type`.
- Supports `splitChunk.\{cacheGroup\}.idHint`.
- Supports `ensureChunkConditionsPlugin`.
- `rules[].use` supports functions.
- Supports `configuration.profile`.

### More hook and plugin support

Compared to version 0.2, we have implemented more plugin APIs and made compatibility improvements for more plugins in version 0.3. At the same time, we have refined the plugin API support progress of webpack, making the support progress of plugin APIs transparent. You can track the implementation progress of plugin APIs here: [plugin-api-progress](https://github.com/orgs/web-infra-dev/projects/9).

### Alignment with webpack architecture

In version 0.3, we have further optimized the alignment with the webpack architecture, migrating from the original AST-based codegen architecture to the string transformation-based architecture. This alignment work further ensures that Rspack can align with more Hook APIs of webpack during the codegen stage to be compatible with more community plugins.

### Rspack ecosystem

Starting from version 0.2, Rspack provides support for vue-loader. However, creating a complete Vue.js CLI solution based on vue-loader can be a complex task. To simplify the development of Vue.js applications using Rspack, we offer the [Rsbuild](https://rsbuild.rs/), which is an out-of-the-box solution. This solution helps developers easily develop Vue.js applications using Rspack.



---
url: /blog/announcing-0-2.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 0.2

_June 02, 2023_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

It has been almost three months since the release of Rspack 0.1. We have received so much attention and feedback from the community, and we are grateful.

In version 0.2, we have added many features, such as: realContentHash, DataURI, support for ESM format, strengthened compatibility with webpack, and optimized many details. In addition, thanks to compatibility with the webpack API, we have also further achieved compatibility with the surrounding ecosystem. Completing tests for compatibility with vue-loader versions 17 (corresponding to Vue 3) and 15 (corresponding to Vue 2). You can now try using Rspack in Vue 2/3 projects.

We look forward to you experiencing these new improvements in version 0.2, and welcome your feedback.

## Main feature updates

### Loader

Version 0.2 has completed compatibility with most of the loader APIs, including: inline match resource, pitching loader, and inline loader. More APIs have further improved compatibility with webpack loaders, details of which can be found in our webpack compatibility updates [Loader API](/api/loader-api/index.md).

### Plugin hooks

New hooks for plugins have been added.

Compiler hooks:

1. [beforeCompile](/api/plugin-api/compiler-hooks.md#beforecompile)
2. [afterCompile](/api/plugin-api/compiler-hooks.md#aftercompile)

Compilation hooks:

1. [optimizeModules](/api/plugin-api/compilation-hooks.md#optimizemodules)
2. [optimizeChunkModule](/api/plugin-api/compilation-hooks.md#optimizechunkmodules)
3. [finishModules](/api/plugin-api/compilation-hooks.md#finishmodules)
4. [chunkAsset](/api/plugin-api/compilation-hooks.md#chunkasset)

NormalModuleFactory hooks:

1. [beforeResolve](/api/plugin-api/normal-module-factory-hooks.md#beforeresolve)
2. [afterResolve](/api/plugin-api/normal-module-factory-hooks.md#afterresolve)
3. [ResolveForScheme](/api/plugin-api/normal-module-factory-hooks.md#resolveforscheme)

ContextModuleFactory hooks:

1. [beforeResolve](/api/plugin-api/context-module-factory-hooks.md#beforeresolve)

### realContentHash

We have implemented optimization.realContentHash, which calculates the Hash based on the final product's file content. This makes the generated Hash more stable and is better utilized for caching. In version 0.2, this feature will be enabled by default for production environment builds.

### ESM/System format

In the new version, System/ESM products can be generated, and the configuration for outputting ESM products is as follows:

```js title="rspack.config.mjs"
export default {
  output: {
    chunkFormat: 'module',
    chunkLoading: 'import',
    library: {
      type: 'module',
    },
  },
};
```

### New `SplitChunksPlugin` implementation

We have restructured the existing implementation of `SplitChunksPlugin` in Rspack, making the behavior of `SplitChunksPlugin` more predictable and reducing the cost of troubleshooting related issues.

After the restructuring, we are confident to implement more features on SplitChunksPlugin. We are pleased to announce that in version 0.2, SplitChunksPlugin supports the following configuration options:

- `splitChunks.maxSize`
- `splitChunks.maxAsyncSize`
- `splitChunks.maxInitialSize`
- `splitChunks.maxAsyncRequests`
- `splitChunks.maxInitialRequests`

In version 0.2, we will use the new `SplitChunksPlugin` by default. If you encounter problems, please provide feedback promptly, and we will fix them as soon as possible. You can switch back to the deprecated implementation by using the `experiments.newSplitChunks: false` option, but we strongly recommend using the new version. In version 0.3, we will remove the deprecated implementation.

### DataURI support

We have implemented support for DataURI. Now you can write the following code to implement virtual modules:

```js
import x from 'data:text/javascript,export default 42';
```

In addition, we have supported `mimetype` and `scheme` as two types of module rule conditions. For example, you can make resources with `scheme` as `'data'` no longer treated as inline processing, but as separate resource files through the following method:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        scheme: 'data',
        type: 'asset/resource',
      },
    ],
  },
};
```

## Breaking changes

- Alignment of Filename Generation Logic

  In version 0.1.12, we further aligned the file name generation logic with webpack, and refactored the implementation of file name generation. However, the \[ext] in `output.filename`, `output.chunkFilename`, `output.cssFilename`, and `output.cssChunkFilename` will no longer be replaced. This behavior is now consistent with webpack but is a breaking change for versions of Rspack prior to 0.1.12. If you used \[ext] in the above 4 filename configurations, you need to change it to the corresponding `.js` or `.css`, for example:

  ```diff title="rspack.config.mjs"
  export default {
    output: {
  -    filename: "[name][ext]",
  +    filename: "[name].js",

  -    chunkFilename: "async/[name][ext]",
  +    chunkFilename: "async/[name].js",

  -    cssFilename: "[name][ext]",
  +    cssFilename: "[name].css",

  -    cssChunkFilename: "async/[name][ext]",
  +    cssChunkFilename: "async/[name].css",
    }
  }
  ```

  Details: [https://github.com/web-infra-dev/rspack/issues/3270](https://github.com/web-infra-dev/rspack/issues/3270)

- Enabled realContentHash by default in production

  Details: [https://github.com/web-infra-dev/rspack/pull/3338](https://github.com/web-infra-dev/rspack/pull/3338)

- Modified the Extensions of Resolve

  Details: [https://github.com/web-infra-dev/rspack/pull/3242](https://github.com/web-infra-dev/rspack/pull/3242)

- Modified the Export Method of @rspack/dev-middleware and @rspack/html-plugin, and Removed `getRspackMemoryAssets` Exported by @rspack/dev-middleware

  Details: [https://github.com/web-infra-dev/rspack/pull/3358](https://github.com/web-infra-dev/rspack/pull/3358)

## Webpack compatibility updates

As we support more webpack APIs, we are also compatible with more community plugins and loaders. We have adapted some plugins and loaders that have a high demand in the community.

### fork-ts-checker-webpack-plugin

Type checking in TypeScript for Rspack is highly demanded. Rspack has fully adapted [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin). You can use this plugin to perform TypeScript type checking during compilation. However, as TypeScript's type checking is usually very time-consuming, this makes the time required for type checking on larger projects may far exceed the build time of Rspack itself. In dev mode, this plugin will not block the build, but in build mode, this plugin will block the build. Please choose whether to enable this plugin based on your actual needs.

### license-webpack-plugin

A widely reported community demand is support for extracting licenses from code. Now, Rspack can achieve the requirement of extracting licenses from the code through [license-webpack-plugin](https://github.com/xz64/license-webpack-plugin).

### style-loader & css-loader

Although Rspack supports and enables the `experiments.css` feature of webpack by default, there are still many communities that strongly depend on [style-loader](https://github.com/webpack/style-loader) & [css-loader](https://github.com/webpack/css-loader). We have completed support for style-loader and css-loader in 0.2.0, which also allows us to better adapt to frameworks such as Svelte and Vue.

### node-loader

When using Rspack to package Node applications like NestJS, a common requirement is to package libraries containing addons. These libraries' native dependencies cannot be directly packaged into js, so they need special treatment. Rspack has adapted [node-loader](https://github.com/webpack-contrib/node-loader), so you can now use Rspack to build node applications.

Rspack has additional adaptation of webpack's plugins. We have tracked the adapted plugins and loaders in [loader-compat](https://github.com/rstackjs/rstack-examples/tree/main/rspack/loader-compat) and [plugin-compat](https://github.com/rstackjs/rstack-examples/tree/main/rspack/plugin). If you find that a community plugin or loader you are using is also compatible, welcome to submit it to us so we can list it in our compatibility matrix.

## Framework ecosystem updates

### Modern.js Framework

Thanks to the close collaboration and parallel iteration of the [Modern.js framework](https://modernjs.dev/) and Rspack, **Modern.js Rspack mode has covered 85% of the framework's capabilities**, supporting SSR, BFF, micro front-end scenarios, and aligning with TypeScript type checking, code compatibility detection and other features.

At ByteDance, more than 80 projects are using the Modern.js Rspack mode. Some of the projects have been deployed into production and have seen a 10x improvement in build performance.

### Modern.js Doc

In addition to the Modern.js framework, the document site solution under the Modern.js system - Modern.js Doc - has also switched the bundler from webpack to Rspack, and rewritten the MDX compilation process based on Rust.

Compared to previous versions using webpack, the current version's build speed can be reduced to seconds. Using the Modern.js official website documentation as an example, the project's startup and build time has been reduced from 30 seconds to less than 2 seconds. In the future, we plan to rename Modern.js Doc to **Rspress** as the official documentation site solution for Rspack and maintain it through a separate repository.

### Vue

Rspack 0.2 has achieved compatibility with vue-loader! For Vue 3 projects, you can use Rspack's native CSS and TS processors to improve the compilation speed of Vue projects. All you need to do is upgrade vue-loader to version 17.2.2 or above and set `experimentalInlineMatchResource: true`. For more information on Vue 3/Vue 2 support, please refer to [guide-vue](/guide/integrations/vue.md).

### Svelte

Thanks to Rspack's excellent support for the Loader API and the excellent design of [svelte-loader](https://github.com/sveltejs/svelte-loader), Rspack has fully adapted [svelte-loader](https://github.com/sveltejs/svelte-loader). Therefore, you can directly use [svelte-loader](https://github.com/sveltejs/svelte-loader) in Rspack for svelte application development. You can refer to [example-svelte](https://github.com/rstackjs/rstack-examples/tree/main/rspack/svelte) to complete the svelte-loader related configuration.

### Storybook

With the help of the Storybook team, Rspack has completed support for the Storybook React version. You can follow the [migrate Storybook](/guide/migration/storybook.md) method to migrate from the webpack version to the Rspack version. In actual projects, tests have shown that the Rspack version is 5-10 times faster than the webpack version when the docgen feature is not turned on. When docgen is turned on, since Rspack still relies on babel to handle docgen, the performance is affected, but there is still a 2-3 times improvement.

### Angular

With the help of the [Valor](https://valor-software.com/) team, Rspack has completed preliminary support for Angular. You can use Rspack to build Angular applications, but the support for dev and HMR has not yet been fully adapted. We will continue to follow up on Angular support in version 0.2.x.

### NestJS

With the help of [Rosa](https://rosa.be/), [Nx](https://nx.dev/), and [Valor](https://valor-software.com/), Rspack has completed the compilation support for [NestJS](https://nestjs.com/). You can use Rspack to package NestJS applications, and in actual projects, tests have shown that Rspack has a 5-10 times build performance improvement compared to the webpack version.

## Dev guide

The Rspack team cherishes the valuable contributions made by the open source community and wants to actively fosters collaboration. We are committed to maintaining an open approach, striving to engage and involve the community at every step.

This is why we are currently crafting a comprehensive development guide that equips contributors with all the essential materials required to facilitate the development of Rspack.

The current version of the guide contains all the necessary materials for building, testing, debugging, and profiling Rspack. Additionally, it includes contribution procedures, such as creating a minimal reproducible example.
In the future, the guide will offer an insightful overview of Rspack's architecture, enabling contributors to gain a profound understanding of the project's intricate inner workings.

## Test infrastructures

In order to ship with confidence, we are currently:

- Building and testing a list of examples in the Rspack repository (currently 38 examples)
- Porting all webpack tests from the webpack repository
- Running all tests on Node 14, 16 and 18
- Maintaining a separate ecosystem-ci repository for integration tests

## Nightly release

In order to expedite iteration, Rspack is released daily with the "@nightly" tag to npm.

## Acknowledgements

With the release of Rspack 0.2, we wholeheartedly thank all the contributors who have put effort into this version.

Special thanks to:

- [@TheLarkInn](https://github.com/TheLarkInn) and [@alexander-akait](https://github.com/alexander-akait), for answering and resolving many of Rspack team's questions about Webpack.
- [@zackarychapple](https://github.com/zackarychapple), [@valorkin](https://github.com/valorkin), [@edusperoni](https://github.com/edusperoni), and [@Coly101](https://github.com/Coly010) for assisting the Rspack team with basic support for Angular and [@zackarychapple](https://github.com/zackarychapple) for reviewing this release blog.
- [@xin2017338](https://github.com/xin2017338), for supporting System.js format and optional-dependency functionality in Rspack, as well as contributing a lot in terms of Windows compatibility.
- [@faga295](https://github.com/faga295), for supporting the decompression code comment feature and rspack preview feature in Rspack.
- [@lippzhang](https://github.com/lippzhang), for making numerous contributions in aligning Rspack's behavior with Webpack.
- [@HerringtonDarkholme](https://github.com/HerringtonDarkholme), for allowing Rspack to use rspack.config.ts as a configuration file.
- [@dhruvkelawala](https://github.com/dhruvkelawala), for implementing the builtins.provide feature in Rspack.
- [@magic-akari](https://github.com/magic-akari), for supporting the `new URL("./foo", import.meta.url)` syntax in Rspack.
- [@tuchg](https://github.com/tuchg), for supporting the packing of .wasm files in Rspack.

We also want to thank all the users of Rspack, for showing trust in such a young open-source project. Your valuable feedback plays a key role in our project improvements and optimizations. Your support and trust is our motivation to move forward.

Finally, let us collectively celebrate the release of Rspack 0.2 and look forward to future developments and more opportunities for collaboration. Thanks again to all friends who support and pay attention to Rspack!



---
url: /blog/announcing-0-1.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Announcing Rspack 0.1

_March 06, 2023_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

Today we are so thrilled to announce that Rspack is officially released! Rspack is a Rust-based JavaScript bundler developed by the ByteDance Web Infra team that has features including high-performance, webpack interoperability, flexible configuration etc. Rspack has solved many problems in our scenarios and improved the developer experience for JavaScript engineers. To help more people get involved in this exciting project, we decided to open source this project. You are welcomed to create a pull request or issue.

## Why Rspack?

There are a lot of giant JavaScript applications inside ByteDance. They have very complex build configurations/scripts which may cost ten minutes to half an hour. We have tried so many ways to improve the build performance, but all existing solutions in the world lead to some other issues while solving some of them. After tons of work, we understand the requirements for a bundler are:

- Dev startup performance. `npm run dev` is a daily script for developers that may run many times. Reducing the cost of them to one minute from ten minutes is really life-saving.
- Build performance. `npm run build` is common in CI/CD environments and determines the efficiency of launch. Many giant applications in ByteDance are built in 20 \~ 30 minutes. If we can reduce it to 3\~5 minutes, developers will be really productive.
- Flexible configuration. Giant projects always have complex configurations and can't be standardized. Back in time, we migrated some of the projects to other build tools to improve build performance, and the hardest part is changing the configuration.
- Production optimization. We tried various solutions in the community and webpack gave the best result in production optimization like chunk-splitting, tree-shaking, etc. A better chunk strategy can help web apps get better metrics performance.

In conclusion, we decided to build our own bundler, which is `Rspack`.

## How is Rspack doing now?

The Rspack project started about 11 months ago. Although it's still in the early stages, it can bring 5\~10 times improvement to applications' build scripts. The metrics can be better when we finish all the optimizations.

Rspack has completed the architecture of webpack loader. It means you can use all kinds of loaders in the community, such as `babel-loader`, `less-loader`, `svgr` etc. We are planning to support all features of loader in Rspack. By that time, you can use loaders which haven't been supported for now, such as `vue-loader`.

Rspack currently only supports memory cache. Persistent and portable cache will be added in the future. We are working on a build system that can make cache shareable between two devices or environments. And Rspack will help accomplish that.

Rspack is now available in all frameworks inside ByteDance, and we are trying to collaborate with all friends in the community. Just like webpack, Rspack is an infrastructure for JavaScript ecosystems, which means that frameworks and Rspack can be beneficial for each other.

## Acknowledgement

Rspack can not be shipped today without the inspiration and support of various projects in the community. We would like to show our respect to these predecessors:

- [The webpack team and community](https://webpack.js.org/) for creating a great bundler and ecosystem from which we draw a lot of inspiration.
- [@sokra](https://github.com/sokra) for the great work on the [webpack](https://github.com/webpack/webpack) project.
- [@ScriptedAlchemy](https://github.com/ScriptedAlchemy) for creating Module Federation and helping Rspack connect with the community.
- The [SWC](https://github.com/swc-project/swc) project created by [@kdy1](https://github.com/kdy1), which powers Rspack's code parsing, transformation and minification.
- The [esbuild](https://github.com/evanw/esbuild) project created by [@evanw](https://github.com/evanw), which inspired the concurrent architecture of Rspack.
- The [NAPI-RS](https://github.com/napi-rs/napi-rs) project created by [@Brooooooklyn](https://github.com/Brooooooklyn), which powers Rspack's node-binding implementation.
- The [Parcel](https://github.com/parcel-bundler/parcel) project created by [@devongovett](https://github.com/devongovett) which is the pioneer of rust bundler and inspired Rspack's incremental rebuild design.
- The [Vite](https://github.com/vitejs/vite) project created by [Evan You](https://github.com/yyx990803) which inspired Rspack's compatibility design of webpack's ecosystem.
- The [Rolldown](https://github.com/rolldown-rs/rolldown) project created by [Rolldown team](https://github.com/sponsors/rolldown-rs), which explores the possibility of making a performant bundler in Rust with Rollup-compatible API. It inspires the design principles of Rspack.
- The [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) project created by [@jantimon](https://github.com/jantimon), `@rspack/html-plugin` is a fork of [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) to avoid some webpack API usage not supported in Rspack.
- The [Turbopack](https://github.com/vercel/turbo) project which inspired the ast path logic of Rspack.

## Future plans

### Improve basic capabilities

Keep building Rspack will be our top priority. Compared with webpack, Rspack is still a baby, lacking complex features. Please keep sending us feedback on feature requests. We will finish them step by step.

### Working with community partners

We would love to offer some help with Rspack integration in your framework. If you are an engineer maintaining a framework who happens to be interested in giving Rspack a try, please contact us.
We have also established a partnership with the webpack team. Rspack is an attempt to optimize webpack performance using Rust, and in the future, we will explore more possibilities for optimizing webpack together with the webpack team. When Rspack reaches a certain level of maturity, webpack will attempt to integrate Rspack into webpack with experiments flag.

### Improve plugin capabilities

Rspack has supported most of the loader APIs, but only a few plugin APIs. There are two reasons why we haven't supported them all. One is that some APIs are bad for performance, so we didn't explore them for developers. And the other reason is simply lack of time, so you can create a merge request to help us.

A high performance plugin system is under discussion. It may be shipped out someday. Hopefully it can help developers get shorter build time while accessing a flexible configuration.

### Continuously improve performance

Currently, Rspack is a project with performance as the core selling point, so in the future we will do a lot of things to maintain this feature, such as improving the performance observation lab and doing a good job of performance prevention; using concurrent/multi-core friendly algorithms in more scenarios; developing a caching system that can be shared across platforms; optimizing memory usage and consumption, etc.

### Build a quality assurance system

Webpack has already accumulated very rich test cases, and in the future Rspack will reuse the existing test cases of webpack to improve its code coverage. Build a better CI system, and build an Ecosystem CI system with community projects to ensure that project upgrades do not cause breaks on upstream projects, to ensure long-term project health, and to ensure long-term increase in test coverage.

## Trial

- Quick start: [rspack.rs](/guide/start/quick-start.md)
- GitHub Repo: [github.com/web-infra-dev/rspack](https://github.com/web-infra-dev/rspack)



---
url: /contribute/architecture/builtin-plugin.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Builtin plugin

Builtin plugin uses [rspack\_macros](https://github.com/web-infra-dev/rspack/tree/7cc39cc4bb6f73791a5bcb175137ffd84b105da5/crates/rspack_macros) to help you avoid writing boilerplate code, you can use [cargo-expand](https://github.com/dtolnay/cargo-expand) or [rust-analyzer expand macro](https://rust-analyzer.github.io/manual.html#expand-macro-recursively) to checkout the expanded code, and for developing/testing these macro, you can starts with [rspack\_macros\_test](https://github.com/web-infra-dev/rspack/tree/7cc39cc4bb6f73791a5bcb175137ffd84b105da5/crates/rspack_macros_test).

A simple example:

```rust
use rspack_hook::{plugin, plugin_hook};
use rspack_core::{Plugin, ApplyContext, CompilerOptions};
use rspack_core::CompilerCompilation;
use rspack_error::Result;

// define the plugin
#[plugin]
pub struct MyPlugin {
  options: MyPluginOptions
}

// define the plugin hook
#[plugin_hook(CompilerCompilation for MyPlugin)]
async fn compilation(&self, compilation: &mut Compilation) -> Result<()> {
  // do something...
}

// implement apply method for the plugin
impl Plugin for MyPlugin {
  fn apply(&self, ctx: &mut rspack_core::ApplyContext<'_>) -> Result<()> {
    ctx.compiler_hooks.tap(compilation::new(self))
    Ok(())
  }
}
```

And here is [an example](https://github.com/web-infra-dev/rspack/blob/7cc39cc4bb6f73791a5bcb175137ffd84b105da5/crates/rspack_plugin_ignore/src/lib.rs).

If the hook you need is not defined yet, you can define it by `rspack_hook::define_hook`. Take `compiler.hooks.assetEmitted` as an example:

```rust
// this will allow you define hook's arguments without limit
define_hook!(CompilerShouldEmit: AsyncSeriesBail(compilation: &mut Compilation) -> bool);
//           ------------------  --------------- -----------------------------  -------
//           hook name           exec kind       hook arguments                 return value (Result<Option<bool>>)

#[derive(Debug, Default)]
pub struct CompilerHooks {
  // ...
  // and add it here
  pub asset_emitted: CompilerAssetEmittedHook,
}
```

There are 5 kinds of exec kind:

- `AsyncSeries`, return value is `Result<()>`
- `AsyncSeriesBail`, return value is `Result<Option<T>>`
- `AsyncParallel`, return value is `Result<()>`
- `SyncSeries`, return value is `Result<()>`
- `SyncSeriesBail`, return value is `Result<Option<T>>`



---
url: /contribute/architecture/rspack-loader.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Rspack loader

## Related PRs

- [rspack#2780](https://github.com/web-infra-dev/rspack/pull/2789)
- [rspack#2808](https://github.com/web-infra-dev/rspack/pull/2808)

The old architecture is a quite simple version, which only supports loaders for normal stage.
Pitching loader does not put into consideration. The basic concept of the old version is to
convert the normal loader to a native function which can be called from the Rust side.
Furthermore, for performance reason, Rspack also composes loaders from the JS side to
mitigate the performance issue of Node/Rust communications.

In this new architecture, loaders will not be converted directly into native functions.
Instead, it is almost the same with how webpack's loader-runner resolves its loaders, by
leveraging the identifier. Every time Rspack wants to invoke a JS loader, the identifiers will
be passed to the handler passed by Node side to process. The implementation also keeps
the feature of composing JS loaders for performance reason.

## Guide-level explanation

The refactor does not introduce any other breaking changes. So it's backwards compatible.

The change of the architecture also help us to implement pitching loader with composability.

### Pitching loader

Pitching loader is a technique to change the loader pipeline flow. It is usually used with inline loader syntax for creating another loader pipeline. style-loader, etc and other loaders which might consume the evaluated result of the following loaders may use this technique.

There are other technique to achieve the same ability, but it's out of this article's topic.

See [Pitching loader](https://webpack.js.org/api/loaders/#pitching-loader) for more detail.

## Reference-level explanation

### Actor of loader execution

In the original implementation of loader, Rspack will convert the normal loaders in the first place, then pass it to the Rust side. In the procedure of building modules, these loaders will be called directly:

![Old architecture](https://user-images.githubusercontent.com/10465670/233357319-e80f6b32-331c-416d-b4b5-30f3e0e394bd.png)

The loader runner is only on the Rust side and execute the loaders directly from the Rust side. This mechanism has a strong limit for us to use webpack's loader-runner for composed loaders.

In the new architecture, we will delegate the loader request from the Rust core to a dispatcher located on the JS side. The dispatcher will normalize the loader and execute these using a modified version of webpack's loader-runner:

![image](https://user-images.githubusercontent.com/10465670/233357805-923e0a27-609d-409a-b38d-96a083613235.png)

Loader functions for pitch or normal will not be passed to the Rust side. Instead, each JS loader has its identifier to uniquely represent each one. If a module requests a loader for processing the module, Rspack will pass identifier with options to the JS side to instruct the webpack like loader-runner to process the transform. This also reduces the complexity of writing our own loader composer.

### Passing options

Options will normally be converted to query, but some of the options contain fields that cannot be serialized, Rspack will reuse the **loader ident** created by webpack to uniquely identify the option and restore it in later loading process.

### Optimization for pitching

As we had known before, each loader has two steps, pitch and normal. For a performance friendly interoperability, we must reduce the communication between Rust and JS as minimum as possible.

Normally, the execution steps of loaders will look like this:

![image](https://user-images.githubusercontent.com/10465670/233360942-7517f22e-3861-47cb-be9e-6dd5f5e02a4a.png)

The execution order of the loaders above will looks like this:

```
loader-A(pitch)
   loader-B(pitch)
      loader-C(pitch)
   loader-B(normal)
loader-A(normal)
```

The example above does not contain any JS loaders, but if, say, we mark these loaders registered on the JS side:

![image](https://user-images.githubusercontent.com/10465670/233362338-93e922f6-8812-4ca9-9d80-cf294e4f2ff8.png)

The execution order will not change, but Rspack will compose the step 2/3/4 together for only a single round communication.



---
url: /contribute/development/building.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Building

Please see [prerequisites](/contribute/development/prerequisites.md) for setting up Rust and Node.js.

## Install Node.js dependencies

Install Node.js dependencies via [pnpm](https://pnpm.io/).

```bash
# enable pnpm with corepack
corepack enable

# Install dependencies
pnpm i
```

## Building Rspack

- Run `cargo build` to compile Rust code.
- Run `pnpm run build:cli:dev` to compile both Node.js and Rust code.
- If you want to build Rspack Wasm, run `pnpm run build:cli:dev:wasm`.

The built binary is located at `packages/rspack-cli/bin/rspack`.



---
url: /contribute/development/debugging.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Debugging

## Debugging with VS Code

1. Install `go install github.com/go-delve/delve/cmd/dlv@latest`
2. Install VS Code extension [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) and [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb)
3. build `@rspack/cli` and napi binding by run `pnpm install && pnpm -w build:cli:dev`
4. In VS Code's `Run and Debug` tab, select `Debug Rspack` to start debugging the initial launch of `@rspack/cli` with a simple rspack project. This task can be configured in `.vscode/launch.json`.

## Using `@rspack-debug/core`

Frameworks and tools that integrate Rspack usually depend on the release build of `@rspack/core`. The release package is suitable for normal builds, but it does not include some debug-only capabilities. When you need these capabilities for local investigation, override `@rspack/core` with `@rspack-debug/core` in the project that runs the build.

For example, with pnpm:

```json title="package.json"
{
  "pnpm": {
    "overrides": {
      "@rspack/core": "npm:@rspack-debug/core@latest"
    },
    "peerDependencyRules": {
      "allowAny": ["@rspack/*"]
    }
  }
}
```

Then reinstall dependencies and run the original build command again. For example, if the project builds through Rsbuild:

```bash
pnpm install
RSPACK_PROFILE=OVERVIEW RSPACK_TRACE_LAYER=perfetto rsbuild build
```

`@rspack-debug/core` should only be used for local debugging and diagnostics. Prefer pinning it to the same version as the original `@rspack/core` dependency when investigating a version-specific issue, and remove the override after the investigation.

### Common debugging scenarios guide

#### Debugging Rust

Simply set breakpoints in the specified Rust code and start `Debug Rspack` to begin debugging.

#### Debugging JavaScript

When starting `Debug Rspack`, select the `--inspect` or `--inspect-brk` option, then start `Attach JavaScript` and choose the PID of the corresponding process.

#### Debugging a running Rspack process

When Rspack is integrated into other frameworks or tools (such as Nx), it may be difficult to independently start Rspack in Launch mode. In this case, you can debug the code through attach mode. Start `Attach Rust` and select the PID of the Rspack process, and start `Attach JavaScript` to debug JavaScript.

#### Debugging a Rspack process with a deadlock

When using `Attach Rust` to attach the debugger to the Rspack process, click the Pause button on the Debugger to set breakpoints at the deadlock scene.

## rust-lldb

`rust-lldb` can be used to get panic information from debug builds

```bash
rust-lldb -- node /path/to/rspack build
```

Once it launches, press `r` for running the program.

For example, `examples/arco-pro` crashes without any information before [this fix](https://github.com/web-infra-dev/rspack/pull/3195/files):

```
rspack/examples/arco-pro ❯ node ../../packages/rspack-cli/bin/rspack build
Rspack ██████████████████████░░░░░░░░░░░░░░░░░░ 56% building ./pages/welcome
zsh: bus error  node ../../packages/rspack-cli/bin/rspack build
```

Using `rust-lldb`

```bash
rspack/examples/arco-pro ❯ rust-lldb -- node ../../packages/rspack-cli/bin/rspack build
```

Press `r` and it prints:

```
Process 23110 stopped
* thread #10, name = 'tokio-runtime-worker', stop reason = EXC_BAD_ACCESS (code=2, address=0x70000cc66560)
    frame #0: 0x0000000140d0db4b rspack.darwin-x64.node`swc_ecma_parser::parser::expr::ops::_$LT$impl$u20$swc_ecma_parser..parser..Parser$LT$I$GT$$GT$::parse_unary_expr::h29f49330a806839c(self=0x0000000000000000) at ops.rs:244
   241 	    /// Parse unary expression and update expression.
   242 	    ///
   243 	    /// spec: 'UnaryExpression'
-> 244 	    pub(in crate::parser) fn parse_unary_expr(&mut self) -> PResult<Box<Expr>> {
   245 	        trace_cur!(self, parse_unary_expr);
   246 	        let start = cur_pos!(self);
   247
Target 0: (node) stopped.
```



---
url: /contribute/development/prerequisites.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Prerequisites

Rspack is built using [Rust](https://rust-lang.org/) and [NAPI-RS](https://napi.rs/), then released as [Node.js](https://nodejs.org/) packages.

## Setup Rust

- Install Rust using [rustup](https://rustup.rs/).
- If you are using VS Code, we recommend installing the [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) extension.

## Setup Node.js

Use the latest Node.js LTS version. For installation instructions, see [Install Node.js](https://nodejs.org/en/download).



---
url: /contribute/development/profiling.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Profiling

In this section, we'll explore how to profile Rspack for identifying bottlenecks.
By examining where Rspack spends its time, we can gain insights into how to improve performance.
Since different profilers have different strengths. It is good to use more than one.

<!-- toc -->

## Build release version with debug info

Performance analysis should be conducted on a release version that includes debug information. This approach ensures accurate performance results while providing sufficient debug information for analysis. Use the following command to profiling using local build rspack.

1. Build a release version with debug information:

```sh
pnpm build:binding:profiling
```

2. Change `@rspack/core` and `@rspack/cli` to use `link` protocol to link to local build Rspack:

```diff title="package.json"
  dependencies: {
-    "@rspack/core": "x.y.z",
-    "@rspack/cli": "x.y.z",
     # link protocol only works in pnpm
+    "@rspack/core": "link:{your_rspack_repo}/packages/rspack",
+    "@rspack/cli": "link:{your_rspack_repo}/packages/rspack-cli"
  }
```

3. Reinstall:

```sh
pnpm install
```

## Memory profiling

Memory profilers observe allocations at the allocator boundary. The regular Rspack release package uses mimalloc, while `@rspack-debug/core` uses the system allocator. Use `@rspack-debug/core` when collecting Heaptrack data or dynamically injecting jemalloc.

In the project you want to profile, override `@rspack/core` with the same version of `@rspack-debug/core` as described in [Debugging](/contribute/development/debugging.md#using-rspack-debugcore), then reinstall the dependencies. For example, if the project uses `@rspack/core@2.1.0` with pnpm:

```json title="package.json"
{
  "pnpm": {
    "overrides": {
      "@rspack/core": "npm:@rspack-debug/core@2.1.0"
    },
    "peerDependencyRules": {
      "allowAny": ["@rspack/*"]
    }
  }
}
```

```sh
pnpm install
```

| Profiler           | Output   | Analyzer                           | Best used for                                      |
| ------------------ | -------- | ---------------------------------- | -------------------------------------------------- |
| Heaptrack          | `*.gz`   | `heaptrack_print`, `heaptrack_gui` | Allocation call stacks and temporary allocations   |
| jemalloc profiling | `*.heap` | `jeprof`                           | Live memory and cumulative allocation flame graphs |

:::warning
Heaptrack and jemalloc use different data formats. `jeprof` cannot read a Heaptrack data file. Do not enable Heaptrack and jemalloc profiling in the same run.
:::

### Heaptrack

[Heaptrack](https://github.com/KDE/heaptrack) intercepts system allocator calls and records allocation call stacks. Install it using your Linux distribution's package manager, then run the build under Heaptrack:

```sh
heaptrack --record-only -o ./rspack-heaptrack \
  node ./node_modules/@rspack/cli/bin/rspack.js build
```

Inspect the generated file from the terminal or GUI:

```sh
heaptrack_print ./rspack-heaptrack.gz | less
heaptrack_gui ./rspack-heaptrack.gz
```

The exact output filename is printed when Heaptrack exits. `--record-only` prevents Heaptrack from trying to open the GUI automatically, which is useful in WSL, containers, and remote shells.

The system allocator used by `@rspack-debug/core` allows Heaptrack to capture allocations from the Rspack native binding. The regular release package uses mimalloc and bypasses the system allocator hooks, so its Rust allocation data is incomplete. Depending on the Heaptrack version, the GUI may show Rust v0 symbol names beginning with `_R` instead of demangled names; this affects display only, not the recorded stacks. For a demangled text report, install [`rustfilt`](https://github.com/luser/rustfilt) and pipe the output through it:

```sh
heaptrack_print ./rspack-heaptrack.gz | rustfilt | less
```

### jemalloc profiling

On Linux, a build that uses the system allocator can be redirected to a profiling-enabled shared jemalloc with `LD_PRELOAD`. Install jemalloc, `jeprof`, and Graphviz using your distribution's packages. On Debian or Ubuntu, the shared library is provided by `libjemalloc2`; the development package commonly provides the profiling tools.

For example, on Debian or Ubuntu:

```sh
sudo apt install heaptrack libjemalloc-dev graphviz
```

Locate the installed library and collect profiles:

```sh
mkdir -p /tmp/rspack-jemalloc
JEMALLOC=$(ldconfig -p | awk '/libjemalloc.so.2/{print $NF; exit}')

MALLOC_CONF='prof:true,prof_active:true,prof_final:true,lg_prof_sample:19,lg_prof_interval:26,prof_prefix:/tmp/rspack-jemalloc/rspack' \
  LD_PRELOAD="$JEMALLOC" \
  node ./node_modules/@rspack/cli/bin/rspack.js build
```

The important options are:

- `prof:true` enables profiling.
- `prof_active:true` starts sampling immediately.
- `prof_final:true` writes a final dump when the process exits.
- `lg_prof_sample:19` samples approximately every 512 KiB of allocations.
- `lg_prof_interval:26` writes a dump after approximately every 64 MiB of allocation activity.
- `prof_prefix` controls where profile files are written.

Find the native Rspack binding loaded by the project:

```sh
RSPACK_BINDING=$(node -e 'require("@rspack/core"); const binding = Object.keys(require.cache).find(file => /rspack\..+\.node$/.test(file)); if (!binding) throw new Error("Rspack native binding not found"); process.stdout.write(binding)')
PROFILE=$(ls -t /tmp/rspack-jemalloc/rspack.*.heap | head -n 1)
```

Generate an SVG for a selected dump and open it in a browser:

```sh
jeprof --show_bytes --functions --svg \
  "$RSPACK_BINDING" \
  "$PROFILE" \
  > rspack-memory.svg
```

For a text report sorted by cumulative memory:

```sh
jeprof --show_bytes --functions --text --cum \
  "$RSPACK_BINDING" \
  "$PROFILE"
```

The default `inuse_space` report describes memory that was live when the dump was written. To investigate allocation traffic, add `prof_accum:true` to `MALLOC_CONF` and pass `--alloc_space` to `jeprof`. Cumulative allocated bytes are not peak memory.

jemalloc only reports allocations routed through jemalloc. Node.js, V8, native libraries, memory mappings, and profiler metadata can also contribute to process RSS. Compare the profile with `/usr/bin/time -v` when investigating total or peak process memory.

## CPU profiling

### Samply

[Samply](https://github.com/mstange/samply) supports performance analysis for both Rust and JavaScript simultaneously. Follow these steps to perform a complete performance analysis:

- Run the following command to start performance analysis:

```sh
samply record -- node --perf-prof --perf-basic-prof --interpreted-frames-native-stack {your_rspack_folder}/rspack-cli/bin/rspack.js -c {your project}/rspack.config.js
```

- After the command execution, the analysis results will automatically open in the [Firefox Profiler](https://profiler.firefox.com/). The screenshot below is from a [Samply profiler](https://profiler.firefox.com/public/5fkasm1wcddddas3amgys3eg6sbp70n82q6gn1g/calltree/?globalTrackOrder=0\&symbolServer=http%3A%2F%2F127.0.0.1%3A3000%2F2fjyrylqc9ifil3s7ppsmbwm6lfd3p9gddnqgx1\&thread=2\&v=10).

:::warning
Node.js currently only supports `--perf-prof` on Linux platforms. JavaScript profiling in Samply depends on `--perf-prof` support. If you need to use Samply for JavaScript profiling on other platforms, consider using Docker for profiling, or you can compile Node.js yourself for macOS using [node-perf-maps](https://github.com/tmm1/node/tree/v8-perf-maps) for profiling purposes.
:::

#### JavaScript profiling

Rspack’s JavaScript typically runs in the Node.js thread. Select the Node.js thread to view the time distribution on the Node.js side.

![Javascript Profiling](https://assets.rspack.rs/rspack/assets/profiling-javascript.png)

#### Rust profiling

Rspack’s Rust code usually runs in the tokio thread. Select the tokio thread to view the time distribution on the Rust side.

![Rust Profiling](https://assets.rspack.rs/rspack/assets/profiling-rust.png)

### Rsdoctor timeline

If we want to analyze the time cost of loaders and plugins or the compilation behavior of loaders, we can use Rsdoctor to view:

![image](https://assets.rspack.rs/others/assets/rsdoctor/rsdoctor-loader-timeline.png)

Refer to [Rsdoctor Compilation Analysis](/guide/diagnostics/use-rsdoctor.md)

## Mac Xcode instruments

Xcode instruments can be used to produce a CPU profile if you are on a Mac.

![image](https://github.com/SyMind/rspack-dev-guide/assets/19852293/124e3aee-944a-4509-bb93-1c9213f026d3)

To install Xcode Instruments, simply install the Command Line Tools:

```bash
xcode-select --install
```

For normal Rust builds, [`cargo instruments`](https://github.com/cmyr/cargo-instruments) can be used as the glue
for profiling and creating the trace file.

Since Rspack takes quite a while to build, you can use the following procedure without invoking `cargo instruments`.
It has the same effect.

In workspace root's `Cargo.toml`, turn on debug symbols and disable symbol stripping in the `[profile.release]` section

```toml
[profile.release]
debug = 1 # debug info with line tables only
strip = false # do not strip symbols
```

Then build the project

```bash
pnpm run build:cli:release
```

The final binary is located at `packages/rspack-cli/bin/rspack` once the project is built.

Under the hood, `cargo instruments` invokes the `xcrun` command,
which means we can run the following in our own project that uses Rspack.

```bash
xcrun xctrace record --template 'Time Profile' --output . --launch -- /path/to/rspack/packages/rspack-cli/bin/rspack build
```

It produces the following output

```
Starting recording with the Time Profiler template. Launching process: rspack.
Ctrl-C to stop the recording
Target app exited, ending recording...
Recording completed. Saving output file...
Output file saved as: Launch_rspack_2023-04-24_11.32.06_9CFE3A63.trace
```

We can open the trace file by

```bash
open Launch_rspack_2023-04-24_11.32.06_9CFE3A63.trace
```



---
url: /contribute/development/project.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Project architecture

This is a **monorepo** containing both Rust crates and JavaScript packages:

## Rust crates (`crates/`)

### Core crates

- **`rspack`**: Main crate that integrates all core functionality and plugins, providing the complete build tool entry point
- **`rspack_core`**: Core engine containing module system, dependency graph, compilation pipeline, and other core functionality
- **`rspack_binding_api`**: Node.js binding API that bridges Rust core functionality to JavaScript/TypeScript interfaces
- **`node_binding`**: Node.js binding implementation that generates Node.js native modules
- **`rspack_napi`**: NAPI (Node-API) support layer for interoperability between Rust and Node.js
- **`rspack_allocator`**: Memory allocator using mimalloc to optimize memory allocation performance (Linux/macOS)

See [JavaScript API architecture](/api/javascript-api/architecture.md) for the ownership, threading,
hook bridge, and lifecycle relationships between these crates and `@rspack/core`.

### Build & binding crates

- **`rspack_binding_build`**: Binding build script for building Node.js native bindings
- **`rspack_binding_builder`**: Binding builder for generating custom Rspack bindings
- **`rspack_binding_builder_macros`**: Binding builder macros providing procedural macro support
- **`rspack_binding_builder_testing`**: Binding builder testing utilities

### Utility crates

- **`rspack_error`**: Error handling and formatting, providing user-friendly error messages
- **`rspack_fs`**: File system abstraction layer providing cross-platform file operation interfaces
- **`rspack_paths`**: Path utilities for path normalization, resolution, and manipulation
- **`rspack_hash`**: Hash algorithm implementations supporting MD4, SHA2, xxhash, etc.
- **`rspack_regex`**: Regular expression utilities providing high-performance regex matching
- **`rspack_location`**: Location information handling for source code position tracking
- **`rspack_ids`**: ID generation and management for creating unique identifiers for modules, chunks, etc.
- **`rspack_collections`**: Collection data structures providing optimized HashMap, HashSet, etc.
- **`rspack_util`**: Utility function collection containing various helper functions
- **`rspack_futures`**: Async utilities providing asynchronous programming support
- **`rspack_workspace`**: Workspace support for handling monorepo scenarios

### Caching & storage

- **`rspack_cacheable`**: Caching system providing serialization and deserialization for cacheable data
- **`rspack_cacheable_macros`**: Caching system macros for auto-generating cache-related code
- **`rspack_cacheable_test`**: Caching system tests
- **`rspack_storage`**: Storage abstraction layer providing persistent storage interfaces

### Hook system

- **`rspack_hook`**: Hook system implementing plugin hook registration and invocation mechanisms
- **`rspack_macros`**: Procedural macros providing various compile-time code generation features
- **`rspack_macros_test`**: Macro system tests

### Compilation & transformation

- **`rspack_javascript_compiler`**: JavaScript compiler for processing JS/TS code compilation
- **`rspack_loader_runner`**: Loader runner for executing various loaders to process resources
- **`rspack_loader_swc`**: SWC loader using SWC for code transformation
- **`rspack_loader_lightningcss`**: Lightning CSS loader for processing CSS files
- **`rspack_loader_react_refresh`**: React Fast Refresh loader supporting React hot module replacement
- **`rspack_loader_preact_refresh`**: Preact Refresh loader supporting Preact hot module replacement
- **`rspack_loader_testing`**: Loader testing utilities

### Plugin system

#### Core plugins

- **`rspack_plugin_javascript`**: JavaScript plugin for parsing, transforming, and code generation of JS/TS modules
- **`rspack_plugin_runtime`**: Runtime plugin generating webpack-compatible runtime code
- **`rspack_plugin_entry`**: Entry plugin for handling entry point configuration
- **`rspack_plugin_dynamic_entry`**: Dynamic entry plugin supporting dynamic entry points

#### Asset & resource plugins

- **`rspack_plugin_asset`**: Asset plugin for processing static assets
- **`rspack_plugin_copy`**: Copy plugin for copying files to output directory
- **`rspack_plugin_json`**: JSON plugin for processing JSON files
- **`rspack_plugin_wasm`**: WebAssembly plugin for processing WASM modules
- **`rspack_plugin_html`**: HTML plugin for generating HTML files

#### CSS plugins

- **`rspack_plugin_css`**: CSS plugin for processing CSS modules and styles
- **`rspack_plugin_extract_css`**: CSS extraction plugin for extracting CSS to separate files
- **`rspack_plugin_css_chunking`**: CSS code splitting plugin
- **`rspack_plugin_lightning_css_minimizer`**: Lightning CSS minifier plugin

#### Optimization plugins

- **`rspack_plugin_swc_js_minimizer`**: SWC JavaScript minifier plugin
- **`rspack_plugin_split_chunks`**: Code splitting plugin implementing chunk splitting strategies
- **`rspack_plugin_merge_duplicate_chunks`**: Merge duplicate chunks plugin
- **`rspack_plugin_remove_empty_chunks`**: Remove empty chunks plugin
- **`rspack_plugin_remove_duplicate_modules`**: Remove duplicate modules plugin
- **`rspack_plugin_limit_chunk_count`**: Limit chunk count plugin
- **`rspack_plugin_real_content_hash`**: Real content hash plugin generating hashes based on content

#### Development plugins

- **`rspack_plugin_hmr`**: Hot Module Replacement (HMR) plugin
- **`rspack_plugin_devtool`**: Source Map plugin for generating source maps
- **`rspack_plugin_progress`**: Progress display plugin
- **`rspack_plugin_lazy_compilation`**: Lazy compilation plugin

#### Library & module plugins

- **`rspack_plugin_library`**: Library plugin for generating library files
- **`rspack_plugin_esm_library`**: ESM library plugin for generating ES module format libraries
- **`rspack_plugin_externals`**: Externals plugin for excluding external dependencies
- **`rspack_plugin_module_replacement`**: Module replacement plugin supporting module aliases
- **`rspack_plugin_ignore`**: Ignore plugin for ignoring specific modules

#### Advanced features

- **`rspack_plugin_mf`**: Module Federation plugin implementing micro-frontend module federation
- **`rspack_plugin_dll`**: DLL plugin implementing dynamic link library functionality
- **`rspack_plugin_worker`**: Web Worker plugin for processing Worker files
- **`rspack_plugin_schemes`**: Custom scheme plugin supporting custom resource protocols
- **`rspack_plugin_runtime_chunk`**: Runtime chunk plugin for separating runtime code

#### Utility plugins

- **`rspack_plugin_ensure_chunk_conditions`**: Ensure chunk conditions plugin
- **`rspack_plugin_no_emit_on_errors`**: No emit on errors plugin
- **`rspack_plugin_circular_dependencies`**: Circular dependency detection plugin
- **`rspack_plugin_banner`**: Banner plugin for adding file header comments
- **`rspack_plugin_size_limits`**: Size limits plugin for checking bundle sizes
- **`rspack_plugin_sri`**: Subresource Integrity (SRI) plugin
- **`rspack_plugin_module_info_header`**: Module info header plugin
- **`rspack_plugin_warn_sensitive_module`**: Warn sensitive module plugin

#### Debug & testing plugins

- **`rspack_plugin_rsdoctor`**: RsDoctor plugin providing debugging and diagnostic functionality
- **`rspack_plugin_rslib`**: RsLib plugin for library builds
- **`rspack_plugin_rstest`**: RsTest plugin for testing

### Browser & environment support

- **`rspack_browserslist`**: Browserslist support for handling browser compatibility queries

### Monitoring & tracing

- **`rspack_tracing`**: Tracing system providing performance tracing functionality
- **`rspack_tracing_perfetto`**: Perfetto tracing support integrating Perfetto performance analysis tools
- **`rspack_watcher`**: File watcher monitoring file changes to trigger rebuilds
- **`rspack_tasks`**: Task system for managing build tasks

### SWC plugins

- **`swc_plugin_import`**: SWC import plugin for processing module import transformations
- **`swc_plugin_ts_collector`**: SWC TypeScript collector plugin for collecting TS type information

## NPM packages (`packages/`)

### Core packages

- **`@rspack/core`**: Main JavaScript/TypeScript package that provides webpack-compatible API, wrapping the Rust core functionality and exposing the complete build tool interface for Node.js applications

### CLI tools

- **`@rspack/cli`**: Command-line interface providing build, serve, and preview commands for running Rspack from the terminal
- **`create-rspack`**: Project scaffolding tool for creating new Rspack projects with various templates (vanilla, React, Vue) supporting both JavaScript and TypeScript

### Browser support

- **`@rspack/browser`**: Browser-compatible version of Rspack that can run in browser environments using WebAssembly, currently in early development stage

### Test tools

- **`@rspack/test-tools`**: Testing utilities and helper functions for writing and running Rspack tests, including support for WebAssembly test execution

## Test cases (`tests/`)

### Core test suite (`rspack-test/`)

The main test suite for Rspack core functionality, containing various test types that simulate the build process:

#### Test types

- **`normalCases/`** (`Normal.test.js`, `Normal-dev.test.js`, `Normal-hot.test.js`, `Normal-prod.test.js`): Test cases for core build processes without configuration changes, used when testing does not require `rspack.config.js`
- **`configCases/`** (`Config.part1.test.js`, `Config.part2.test.js`, `Config.part3.test.js`): Test cases for build configuration options, allowing specification of build configuration through `rspack.config.js` and test behavior through `test.config.js`
- **`hotCases/`** (`HotNode.test.js`, `HotWeb.test.js`, `HotWorker.test.js`, `HotSnapshot.hottest.js`): Test cases for Hot Module Replacement (HMR) functionality, including HotNode (`target=async-node`), HotWeb (`target=web`), and HotWorker (`target=webworker`)
- **`watchCases/`** (`Watch.part1.test.js`, `Watch.part2.test.js`, `Watch.part3.test.js`): Test cases for incremental compilation in Watch mode, using numbered directories (0, 1, 2...) to represent change batches
- **`statsOutputCases/`** (`StatsOutput.test.js`): Test cases for console output logs after build completion, with snapshots stored in `__snapshots__/StatsOutput.test.js.snap`
- **`statsAPICases/`** (`StatsAPI.test.js`): Test cases for the Stats object generated after build completion, using `tests/rspack-test/fixtures` as source code
- **`diagnosticsCases/`** (`Diagnostics.test.js`): Test cases for formatted warning/error output during the build process, with snapshots stored in `stats.err` files
- **`hashCases/`** (`Hash.test.js`): Test cases for hash generation functionality, validating hash information in the Stats object
- **`compilerCases/`** (`Compiler.test.js`): Test cases for Compiler/Compilation object APIs, using `tests/rspack-test/fixtures` as source code
- **`defaultsCases/`** (`Defaults.test.js`): Test cases for configuration option interactions, generating build configurations and observing differences from defaults
- **`errorCases/`** (`Error.test.js`): Test cases for `compilation.errors` and `compilation.warnings` interactions
- **`hookCases/`** (`Hook.test.js`): Test cases for various hook functionalities, recording hook input/output in snapshots
- **`treeShakingCases/`** (`TreeShaking.test.js`): Test cases for Tree Shaking-related features, with product snapshots stored in `__snapshots__/treeshaking.snap.txt`
- **`builtinCases/`** (`Builtin.test.js`): Test cases for plugins with built-in native implementations, generating different snapshots based on plugin type (CSS, CSS modules, HTML, JavaScript)
- **`cacheCases/`** (`Cache.test.js`): Test cases for caching functionality, including common cache, invalidation, snapshot, storage, and portable cache scenarios
- **`serialCases/`** (`Serial.test.js`): Test cases for serial execution scenarios
- **`exampleCases/`** (`Example.test.js`): Example test cases demonstrating various Rspack features
- **`esmOutputCases/`** (`EsmOutput.test.js`): Test cases for ES module output functionality, including basic output, deconflict, dynamic import, externals, interop, namespace, preserve-modules, re-exports, and split-chunks scenarios
- **`multiCompilerCases/`** (`MultiCompiler.test.js`): Test cases for multi-compiler scenarios
- **Incremental tests** (`Incremental-node.test.js`, `Incremental-async-node.test.js`, `Incremental-web.test.js`, `Incremental-webworker.test.js`, `Incremental-watch.test.js`): Test cases for incremental compilation targeting different environments
- **Native watcher tests** (`NativeWatcher.part1.test.js`, `NativeWatcher.part2.test.js`, `NativeWatcher.part3.test.js`): Test cases for native file watcher functionality

#### Supporting directories

- **`fixtures/`**: General test files and shared fixtures used across multiple test types
- **`js/`**: Build artifacts and temporary files generated during test execution, organized by test type (e.g., `js/normal`, `js/config`, `js/hot-{target}`)
- **`__snapshots__/`**: Test snapshots for various test types, including StatsOutput, HotSnapshot, and other snapshot-based tests

### E2E Tests (`e2e/`)

End-to-end tests for Rspack, covering real-world scenarios and integration testing:

- **`cases/`**: E2E test cases organized by feature area (chunk, css, file, hooks, html, incremental, lazy-compilation, make, module-federation, persistent-cache, react, vue3, worker)
- **`fixtures/`**: Shared fixtures and utilities for E2E tests
- **`utils/`**: Utility functions for E2E test execution

### JavaScript benchmarks (`bench/`)

Performance benchmarks for tracking Rspack JavaScript API performance and preventing performance degradation:

- **`fixtures/`**: Benchmark test fixtures (e.g., `ts-react` project for benchmarking)
- Benchmark files for measuring build performance and API execution time

### Rust benchmarks (`xtask/benchmark/`)

CodSpeed benchmarks for tracking Rust compilation pipeline performance:

- **`cases/`**: End-to-end benchmark cases for module graph, chunk graph, bundling, scanning dependencies, and persistent cache
- **`stages/`**: Focused benchmark cases for individual compilation stages
- See **`xtask/benchmark/README.md`** for local CodSpeed CPU simulation commands and Valgrind temporary file locations



---
url: /contribute/development/releasing.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Releasing

Rspack releases are automated through GitHub Actions.

You can view all released versions on the npm version pages of [@rspack/core](https://www.npmjs.com/package/@rspack/core?activeTab=versions) and [@rspack/cli](https://www.npmjs.com/package/@rspack/cli?activeTab=versions).

## Latest release

The latest stable release follows the Semantic Versioning specification (x.y.z).

The [full release workflow](https://github.com/web-infra-dev/rspack/actions/workflows/release.yml?query=is%3Asuccess) is triggered manually by Rspack maintainers on Tuesday with the complete release notes.

During the release, the binary artifacts below are built, grouped by the support tier that the [Node.js platform list](https://github.com/nodejs/node/blob/main/BUILDING.md#platform-list) gives to the platform they run on:

**Tier 1**

- x86\_64-unknown-linux-gnu
- aarch64-unknown-linux-gnu
- x86\_64-pc-windows-msvc
- aarch64-apple-darwin

**Tier 2**

- powerpc64le-unknown-linux-gnu
- s390x-unknown-linux-gnu
- aarch64-pc-windows-msvc
- x86\_64-apple-darwin

**Experimental**

- x86\_64-unknown-linux-musl
- riscv64gc-unknown-linux-gnu

**Others**

- aarch64-unknown-linux-musl
- riscv64gc-unknown-linux-musl
- i686-pc-windows-msvc

:::warning Platforms below Tier 1

For these platforms Rspack only guarantees that the binding is built successfully. CI verifies the build only and never runs the test suite on them, so a green CI run is not a guarantee that Rspack behaves correctly there.

:::

### Release steps

1. Create a new branch, for example `release/v1.0.0`.
2. Update the version using the `pnpm x version` command on the branch.

```bash
# Release a patch version
pnpm x version patch

# Release a minor version
pnpm x version minor

# Release a major version
pnpm x version major

# Release an alpha version
pnpm x version patch --pre alpha

# Release a beta version
pnpm x version patch --pre beta

# Release a rc version
pnpm x version patch --pre rc
```

3. Commit the code and push to the remote branch.

```bash
git add .
git commit -m "chore: release v1.0.0"
git push origin release/vx.y.z
```

4. Create a PR with the title `chore: release v1.0.0`.
5. Run the [Ecosystem CI workflow](https://github.com/web-infra-dev/rspack/actions/workflows/ecosystem-ci.yml) to ensure all ecosystem projects are working properly.
6. Run the full release workflow on the release branch:
   - [Release Full](https://github.com/web-infra-dev/rspack/actions/workflows/release.yml): Publish npm packages to registry
   - [Release Crates](https://github.com/web-infra-dev/rspack/actions/workflows/release-crates.yml): Publish Rust crates to crates.io
7. After the release, merge the PR to the `main` branch.
8. Use the `create-draft-release-notes` skill to create a draft [GitHub release note](https://github.com/web-infra-dev/rspack/releases).
9. Review the draft release note, optionally add release highlights, and publish it.

## Canary release

Canary is the pre-release version for testing and verifying new features.

Releasing a canary version does not require manually creating a branch or updating the version, it only requires Rspack maintainers to trigger the [Canary release workflow](https://github.com/web-infra-dev/rspack/actions/workflows/release-canary.yml).



---
url: /contribute/development/testing.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Testing

Because Rspack uses a mix of Rust and Node.js code, different testing strategies are used for each.

## Rust testing

:::tip
Rust test cases are only suitable for unit testing. To test the complete build process, please add Node.js test cases.
:::

### Running Rust tests

You can run the Rust code's test cases using `./x test rust` or `cargo test`.

### Writing Rust tests

Test cases are written within the Rust code. For example:

```rust
fn add(a: u8, b: u8) -> u8 {
  a + b
}

#[test]
fn test_add() {
  assert_eq!(add(1, 2), 3);
}
```

> For more information, please refer to: [Rust: How to Write Tests](https://doc.rust-lang.org/book/ch11-01-writing-tests.html)

## Node.js testing

Rspack's test cases include the following:

- Rspack core test cases are stored in the `tests/rspack-test` folder and will run the test cases by simulating the build process. In general, test cases should be added in this folder.
- Test cases for other Rspack packages are stored in the `packages/{name}/tests` folder and should only be added or modified when modifying that package.

You can run Rspack tests by running `./x test unit` or `pnpm run test:unit` at the root folder.

You can also go to the `tests/rspack-test` folder and run `npm run test` to run test cases and add some arguments:

- **When refreshing test snapshots is needed**: Add `-u`, like `npm run test -- -u`
- **When filtering test cases is needed**: Add `-t`. Pattern matching supports regex, see [rstest](https://rstest.rs/guide/basic/test-filter#filter-by-test-name) for details.

### Running tests

You can run these test cases in the following ways:

- Run `./x test unit` or `pnpm run test:unit` from the root directory.
- Or run `npm run test` from the `tests/rspack-test` directory.
- To update snapshots, run `npm run test -- -u` from the `tests/rspack-test` directory.
- To pass specific rstest cli arguments, run `npm run test -- {args}` from the `tests/rspack-test` directory.
- To filter specific test cases, run `npm run test -- -t ${testPath}` where `testPath` can be either an absolute or relative path.
  - For example:
    - `npm run test -- -t hotCases/json/error-in-json` (or `npm run test -- -t /Users/rspack/tests/rspack-test/hotCases/json/error-in-json`) will run all tests in the `error-in-json` test case.
    - `npm run test -- -t hotCases/json` (or `npm run test -- -t /Users/rspack/tests/rspack-test/hotCases/json`) will run all test cases in the `json` directory.
    - `npm run test -- -t hotCases` (or `npm run test -- -t /Users/rspack/tests/rspack-test/hotCases`) will run all test cases in the `hotCases` directory.
- To use Rspack Wasm for running test cases, you need to additionally configure the following environment variables:
  1. `NAPI_RS_FORCE_WASI=1`: Forces the use of Rspack Wasm instead of native binding
  2. `WASM=1`: Enables Wasm-specific test configurations
  3. `NODE_NO_WARNINGS=1`: Disables Node.js Wasm warnings.
  ```bash
  NAPI_RS_FORCE_WASI=1 WASM=1 NODE_NO_WARNINGS=1 pnpm run test:unit
  ```

### Directory structure

The structure of the `tests/rspack-test` folder is as follows:

```bash
.
├── js # Used to store build artifacts and temporary files
├── __snapshots__ # Used to store test snapshots
├── {Name}.test.js # Entry for normal testing
├── {Name}.hottest.js # Entry for hot snapshot testing
├── {Name}.difftest.js # Entry for diff testing
├── {name}Cases # Directory to store test cases
└── fixtures # General test files
```

The `{Name}.test.js` is the entry file for tests, which will walk the `{name}Cases` folder and run cases in it. Therefore, when you need to add or modify test cases, add them to the relevant `{name}Cases` folder based on the type of testing.

### Test types

The existing test types are:

- [Normal](#normal): Used to test core build processes without configuration changes. This type is used when testing does not require adding `rspack.config.js`.
- [Config](#config): Used to test build configuration options. If your test needs specific configuration added through `rspack.config.js` to run and does not fit other scenarios, use this test type.
- [Hot](#hot): Used to test whether HMR runs correctly. This type includes HotNode with a fixed `target=async-node`, HotWeb with a fixed `target=web`, and HotWorker with a fixed `target=webworker`.
- [HotSnapshot](#hotsnapshot): Used to test whether HMR can generate correct intermediate artifacts. This test type shares test cases with the Hot type and generates snapshots for incremental artifacts for each HMR.
- [Watch](#watch): Used to test incremental compilation after modifying files in Watch mode.
- [StatsOutput](#statsoutput): Used to test the console output log after the build ends.
- [StatsAPI](#stats-api): Used to test the Stats object generated after the build ends.
- [Diagnostic](#diagnostic): Used to test the formatted output information for warnings/errors generated during the build process.
- [Hash](#hash): Used to test whether hash generation works correctly.
- [Compiler](#compiler): Used to test Compiler/Compilation object APIs.
- [Defaults](#defaults): Used to test the interaction between configuration options.
- [Error](#error): Used to test the interaction between `compilation.errors` and `compilation.warnings`.
- [Hook](#hook): Used to test various hook functionalities.
- [TreeShaking](#treeshaking): Used to test Tree Shaking-related features.
- [Builtin](#builtin): Used to test plugins with built-in native implementations.

Please prioritize adding test cases within the above test types.

### Normal

| Test Entry            | `tests/Normal.test.js`                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Case Directory        | [`tests/normalCases`](https://github.com/web-infra-dev/rspack/tree/main/tests/rspack-test/normalCases)             |
| Output Directory      | `tests/js/normal`                                                                                                  |
| Default Configuration | [NormalProcessor](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-test-tools/src/case/normal.ts) |
| Run Output            | `Yes`                                                                                                              |

The writing of the case is the same as a regular rspack project, but it does not include the `rspack.config.js` file and will use the provided configuration for building.

### Config

| Test Entry            | `tests/Config.test.js`                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Case Directory        | [`tests/configCases`](https://github.com/web-infra-dev/rspack/tree/main/tests/rspack-test/configCases)             |
| Output Directory      | `tests/js/config`                                                                                                  |
| Default Configuration | [ConfigProcessor](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-test-tools/src/case/config.ts) |
| Run Output            | `Yes`                                                                                                              |

This test case is similar to a regular rspack project. You can specify the build configuration by adding a `rspack.config.js` and control various behaviors during testing by adding a `test.config.js`. The structure of the `test.config.js` file is as follows:

```ts {16-20} title="test.config.js"
type TConfigCaseConfig = {
  noTests?: boolean; // Do not run the test output and end the test
  beforeExecute?: () => void; // Callback before running the output
  afterExecute?: () => void; // Callback after running the output
  moduleScope?: (ms: IModuleScope) => IModuleScope; // Module context variables when running the output
  findBundle?: (
    // Function for obtaining output when running the output, can control the output at a finer granularity
    index: number, // Compiler index in multi-compiler scenario
    options: TCompilerOptions<T>, // Build configuration object
  ) => string | string[];
  bundlePath?: string[]; // Output file name when running the output (prior to findBundle)
  nonEsmThis?: (p: string | string[]) => Object; // this object during CJS output runtime, defaults to current module's module.exports if not specified
  modules?: Record<string, Object>; // Pre-added modules when running the output, will be prioritized when required
  timeout?: number; // Timeout for the test case
};

/** @type {import("../../../..").TConfigCaseConfig} */
module.exports = {
  // ...
};
```

### Hot

| Test Entry            | `Hot{Target}.test.js`                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| Case Directory        | [`tests/hotCases`](https://github.com/web-infra-dev/rspack/tree/main/tests/rspack-test/hotCases)             |
| Output Directory      | `tests/js/hot-{target}`                                                                                      |
| Default Configuration | [HotProcessor](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-test-tools/src/case/hot.ts) |
| Run Output            | `Yes`                                                                                                        |

This test case is similar to a regular rspack project. You can specify the build configuration by adding a `rspack.config.js`.

And also, within the file that has changed, use `---` to separate the code before and after the change:

```js file.js title="file.js"
module.exports = 1; // Initial build
---
module.exports = 2; // First hot update
---
module.exports = 3; // Second hot update
```

In the test case code, use the `NEXT_HMR` method to control the timing of file changes and add test code within it:

```js title="index.js"
import value from './file';

it('should hot update', done => {
  expect(value).toBe(1);
  // Use tests/rspack-test/hotCases/update.js to trigger update
  await NEXT_HMR();
  expect(value).toBe(2);
  await NEXT_HMR();
  expect(value).toBe(3);
});

module.hot.accept('./file');
```

### HotSnapshot

| Test Entry            | `HotSnapshot.hottest.js`                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| Case Directory        | [`tests/hotCases`](https://github.com/web-infra-dev/rspack/tree/main/tests/rspack-test/hotCases) |
| Output Directory      | `tests/js/hot-snapshot`                                                                          |
| Default Configuration | Same as [Hot](#hot)                                                                              |
| Run Output            | `Yes`                                                                                            |

Uses the same test cases as `Hot{Target}`, and generates a `__snapshots__/{target}/{step}.snap.txt` file in the case folder to perform snapshot testing on the incremental artifacts of each HMR.

The snapshot structure is as follows:

- **Changed Files**: Source code files that trigger this HMR build
- **Asset Files**: Artifact files of this HMR build
- **Manifest**: Contents of the `hot-update.json` metadata file for this HMR build, where:
  - `"c"`: Id of the chunks to be updated in this HMR
  - `"r"`: Id of the chunks to be removed in this HMR
  - `"m"`: Id of the modules to be removed in this HMR
- **Update**: Information about the `hot-update.js` patch file for this HMR build, including:
  - **Changed Modules**: List of modules included in the patch
  - **Changed Runtime Modules**: List of runtime modules included in the patch
  - **Changed Content**: Snapshot of the patch code

### Watch

| Entry File            | `Watch.test.js`                                                                                                  |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Case Directory        | [`tests/watchCases`](https://github.com/web-infra-dev/rspack/tree/main/tests/rspack-test/watchCases)             |
| Output Directory      | `tests/js/watch`                                                                                                 |
| Default Configuration | [WatchProcessor](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-test-tools/src/case/watch.ts) |
| Run Output            | `Yes`                                                                                                            |

As the Watch build needs to be performed in multiple steps, you can specify the build configuration by adding a `rspack.config.js`. The directory structure of its cases is special and will use incrementing numbers to represent change batches:

```bash
.
├── 0 # WATCH_STEP=0, initial code for the case
├── 1 # WATCH_STEP=1, diff files for the first change
├── 2 # WATCH_STEP=2, diff files for the second change
└── rspack.config.js
```

In the test code, you can use the `WATCH_STEP` variable to get the current batch number of changes.

### StatsOutput

| Test Entry            | `StatsOutput.test.js`                                                                                                   |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Case Directory        | [`tests/statsOutputCases`](https://github.com/web-infra-dev/rspack/tree/main/tests/rspack-test/statsOutputCases)        |
| Output Directory      | `tests/js/statsOutput`                                                                                                  |
| Default Configuration | [StatsProcessor](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-test-tools/src/case/stats-output.ts) |
| Run Output            | `No`                                                                                                                    |

The writing of the cases is the same as in a regular rspack project. After running, the console output information will be captured in snapshots and stored in `tests/rspack-test/__snapshots__/StatsOutput.test.js.snap`.

:::tip
As some StatsOutput test cases contain hashes, when you modify the output code, please use the `-u` parameter to update the snapshots for these cases.
:::

### Stats API

| Entry File            | `StatsAPI.test.js`                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| Case Directory        | `tests/statsAPICases`                                                                                        |
| Output Directory      | `None`                                                                                                       |
| Default Configuration | [`None`](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-test-tools/src/case/stats-api.ts) |
| Run Output            | `No`                                                                                                         |

This test uses `tests/rspack-test/fixtures` as the source code for the build, so the test case is written as a single file. Its structure is as follows:

```js title="{case}.js"
type TStatsAPICaseConfig = {
  description: string, // Case description
  options?: (context: ITestContext) => TCompilerOptions<T>, // Case build configuration
  build?: (context: ITestContext, compiler: TCompiler<T>) => Promise<void>, // Case build method
  check?: (stats: TCompilerStats<T>, compiler: TCompiler<T>) => Promise<void>, // Function to check the stats for the case
};

// [!code highlight:4]
/** @type {import('../..').TStatsAPICaseConfig} */
module.exports = {
  // ...
};
```

### Diagnostic

| Entry File            | `Diagnostics.test.js`                                                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Case Directory        | [`tests/diagnosticsCases`](https://github.com/web-infra-dev/rspack/tree/main/tests/rspack-test/diagnosticsCases)           |
| Output Directory      | `tests/js/diagnostics`                                                                                                     |
| Default Configuration | [DiagnosticProcessor](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-test-tools/src/case/diagnostic.ts) |
| Run Output            | `No`                                                                                                                       |

This test case is similar to a typical rspack project and can specify build configurations by adding a `rspack.config.js`. Additionally, it will add a `stats.err` file in the case directory to store snapshots of warnings/errors. To refresh, use the `-u` parameter.

### Hash

| Entry File            | `Hash.test.js`                                                                                                 |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| Case Directory        | [`tests/hashCases`](https://github.com/web-infra-dev/rspack/tree/main/tests/rspack-test/hashCases)             |
| Output Directory      | None                                                                                                           |
| Default Configuration | [HashProcessor](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-test-tools/src/case/hash.ts) |
| Run Output            | No                                                                                                             |

This test case is similar to a typical rspack project, but it will add a `test.config.js` file in the case directory and specify a `validate()` method to check the hash information in the `stats` object after the build is complete:

```js title="test.config.js"
type THashCaseConfig = {
  validate?: (stats: TCompilerStats<T>) => void,
};

// [!code highlight:4]
/** @type {import('../..').THashCaseConfig} */
module.exports = {
  // ...
};
```

### Compiler

| Entry File            | `Compiler.test.js`                                                                                         |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| Case Directory        | [`tests/compilerCases`](https://github.com/web-infra-dev/rspack/tree/main/tests/rspack-test/compilerCases) |
| Output Directory      | None                                                                                                       |
| Default Configuration | [None](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-test-tools/src/case/compiler.ts)  |
| Run Output            | No                                                                                                         |

This test uses `tests/rspack-test/fixtures` as the source code for the build, so the test case is written as a single file. Its structure is as follows:

```js title="{case.js}"
interface TCompilerCaseConfig {
  description: string; // Description of the test case
  options?: (context: ITestContext) => TCompilerOptions<T>; // Test case build configuration
  compiler?: (context: ITestContext, compiler: TCompiler<T>) => Promise<void>; // How the compiler is created for the test case
  build?: (context: ITestContext, compiler: TCompiler<T>) => Promise<void>; // Build method for the test case
  check?: (
    context: ITestContext,
    compiler: TCompiler<T>,
    stats: TCompilerStats<T>,
  ) => Promise<void>; // Check function for the test case
}

// [!code highlight:4]
/** @type {import('@rspack/core').TCompilerCaseConfig} */
module.exports = {
  // ...
};
```

### Defaults

| Entry File            | `Defaults.test.js`                                                                                        |
| --------------------- | --------------------------------------------------------------------------------------------------------- |
| Case Directory        | [`tests/defaultCases`](https://github.com/web-infra-dev/rspack/tree/main/tests/rspack-test/defaultCases)  |
| Output Directory      | None                                                                                                      |
| Default Configuration | [None](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-test-tools/src/case/defaults.ts) |
| Run Output            | No                                                                                                        |

This test does not execute real builds; it only generates build configurations and observes the differences from the default configuration. The basic default configuration will be snapshot and stored in `tests/rspack-test/__snapshots__/Defaults.test.js.snap`.

This test uses `tests/rspack-test/fixtures` as the source code for the build, so the test case is written as a single file. Its structure is as follows:

```js title="{case}.js"
interface TDefaultsCaseConfig {
  description: string; // Description of the test case
  cwd?: string; // process.cwd for generating the build configuration of the test case, default is the `tests/rspack-test` directory
  options?: (context: ITestContext) => TCompilerOptions<ECompilerType.Rspack>; // Test case build configuration
  diff: (
    diff: Assertion<Diff>,
    defaults: Assertion<TCompilerOptions<ECompilerType.Rspack>>,
  ) => Promise<void>; // Differences from the default configuration
}

// [!code highlight:4]
/** @type {import('../..').TDefaultsCaseConfig} */
module.exports = {
  // ...
};
```

The details for the Error test are as follows:

### Error

| Entry File            | `Error.test.js`                                                                                                  |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Case Directory        | [`tests/errorCases`](https://github.com/web-infra-dev/rspack/tree/main/tests/rspack-test/errorCases)             |
| Output Directory      | None                                                                                                             |
| Default Configuration | [ErrorProcessor](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-test-tools/src/case/error.ts) |
| Run Output            | No                                                                                                               |

This test uses `tests/rspack-test/fixtures` as the source code for the build, so the test case is written as a single file. Its structure is as follows:

```js title="{case}.js"
interface TErrorCaseConfig {
  description: string; // Description of the test case
  options?: (
    options: TCompilerOptions<T>,
    context: ITestContext,
  ) => TCompilerOptions<T>; // Test case configuration
  build?: (context: ITestContext, compiler: TCompiler<T>) => Promise<void>; // Test case build method
  check?: (stats: TStatsDiagnostics) => Promise<void>; // Function to check the test case
}

// [!code highlight:4]
/** @type {import('../..').TErrorCaseConfig} */
module.exports = {
  // ...
};
```

### Hook

| Entry File            | `Hook.test.js`                                                                                                 |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| Case Directory        | [`tests/hookCases`](https://github.com/web-infra-dev/rspack/tree/main/tests/rspack-test/hookCases)             |
| Output Directory      | None                                                                                                           |
| Default Configuration | [HookProcessor](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-test-tools/src/case/hook.ts) |
| Run Output            | No                                                                                                             |

This test records the input and output of the hook and stores it in the snapshot `hooks.snap.txt`. The snapshot of the final product code is stored in `output.snap.txt`.

This test uses `tests/rspack-test/fixtures` as the source code for the build, so the test case is written as a single file. Its structure is as follows:

```js title="{case}/test.js"
interface THookCaseConfig {
  description: string; // Description of the test case
  options?: (
    options: TCompilerOptions<T>,
    context: ITestContext,
  ) => TCompilerOptions<T>; // Test case configuration
  compiler?: (context: ITestContext, compiler: TCompiler<T>) => Promise<void>; // Callback after creating the compiler instance
  check?: (context: ITestContext) => Promise<void>; // Callback after the build is completed
}

// [!code highlight:4]
/** @type {import("@rspack/test-tools").THookCaseConfig} */
module.exports = {
  // ...
};
```

### TreeShaking

| Entry File            | `TreeShaking.test.js`                                                                                                        |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Case Directory        | `tests/treeShakingCases`                                                                                                     |
| Output Directory      | `tests/js/treeShaking`                                                                                                       |
| Default Configuration | [TreeShakingProcessor](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-test-tools/src/case/treeshaking.ts) |
| Run Output            | No                                                                                                                           |

In this test case, the configuration is similar to a regular rspack project. You can specify the build configuration by adding a `rspack.config.js`, but the final product is snapshot and stored in `__snapshots__/treeshaking.snap.txt`.

### Builtin

| Entry File            | `Builtin.test.js`                                                                                                    |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Case Directory        | `tests/builtinCases`                                                                                                 |
| Output Directory      | `tests/js/builtin`                                                                                                   |
| Default Configuration | [BuiltinProcessor](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-test-tools/src/case/builtin.ts) |
| Run Output            | No                                                                                                                   |

This test case is similar to a regular rspack project, and you can specify the build configuration by adding a `rspack.config.js`. However, depending on the directory, different snapshots of the products will be generated and stored in `__snapshots__/output.snap.txt`:

- **plugin-css**: Snapshots of files with a `.css` extension
- **plugin-css-modules**: Snapshots of files with `.css` and `.js` extensions
- **plugin-html**: Snapshots of files with `.html` extension
- **Other**: Snapshots of files with `.js` extension



---
url: /contribute/development/tracing.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Tracing

[`tracing`](https://crates.io/crates/tracing) is used to record the internal processes of Rspack compilation, which can be used for performance analysis as well as narrow down the location of a bug.

## Enabling tracing

Tracing can be enabled in two ways:

- If using [@rspack/cli](/api/cli.md) or Rsbuild: Enable it by setting the `RSPACK_PROFILE` environment variable:

```sh
# Rspack CLI
RSPACK_PROFILE=OVERVIEW rspack build # recommend
RSPACK_PROFILE=ALL rspack build # not recommend, may generate a large trace file for large projects

# Rsbuild
RSPACK_PROFILE=OVERVIEW rsbuild build
RSPACK_PROFILE=ALL rsbuild build
```

- If directly using `@rspack/core`: Enable it through `rspack.experiments.globalTrace.register` and `rspack.experiments.globalTrace.cleanup`. You can check how we implement [`RSPACK_PROFILE` in `@rspack/cli`](https://github.com/web-infra-dev/rspack/blob/main/packages/rspack-cli/src/utils/profile.ts) for more information.

When the `perfetto` layer is enabled, the generated `rspack.pftrace` file can be viewed and analyzed in [ui.perfetto.dev](https://ui.perfetto.dev/):

<img
src="https://assets.rspack.rs/rspack/assets/rspack-v1-4-tracing.png"
alt="tracing"
/>

## Tracing layer

Rspack supports two types of layers: `perfetto` and `logger`:

- `logger`: The default value, writes JSON Lines logs to a file, suitable for simple log analysis. In CI environments, upload or print the generated `rspack.log`, or set `RSPACK_TRACE_OUTPUT=stdout` / `stderr` explicitly to stream logger output.
- `perfetto`: Only available when using `@rspack-debug/core`. It generates a `rspack.pftrace` file conforming to the [`perfetto proto`](https://perfetto.dev/docs/reference/synthetic-track-event) format, which can be imported into Perfetto for complex performance analysis

`@rspack-debug/core` is a diagnostic variant of `@rspack/core` that includes extra debugging and tracing capabilities such as the `perfetto` layer. Use it when you need to collect Perfetto traces for local investigation, not as the default package for normal builds.

You can specify the layer through the `RSPACK_TRACE_LAYER` environment variable:

```sh
RSPACK_TRACE_LAYER=logger

# Only available with @rspack-debug/core
RSPACK_TRACE_LAYER=perfetto
```

## Tracing output

You can specify the output location for traces:

- The default output for the `logger` layer is `.rspack-profile-${timestamp}-${pid}/rspack.log`
- The default output for the `perfetto` layer is `.rspack-profile-${timestamp}-${pid}/rspack.pftrace`

You can customize the output location through the `RSPACK_TRACE_OUTPUT` environment variable:

```sh
RSPACK_TRACE_LAYER=logger RSPACK_TRACE_OUTPUT=log.txt rspack dev

# Only available with @rspack-debug/core
RSPACK_TRACE_LAYER=perfetto RSPACK_TRACE_OUTPUT=perfetto.pftrace rspack dev
```

When `RSPACK_TRACE_OUTPUT` is a relative file path, it is resolved inside the generated `.rspack-profile-${timestamp}-${pid}` directory. Absolute paths are used as-is. For the `logger` layer, set it to `stdout` or `stderr` explicitly if you need terminal output. The `perfetto` layer always requires a file path.

## Tracing filter

You can configure the data to be filtered through `RSPACK_PROFILE`. Rspack provides two preset options:

- `RSPACK_PROFILE=OVERVIEW`: The default value, only shows the core build process, generating a smaller JSON file
- `RSPACK_PROFILE=ALL`: Includes all trace events, used for more complex analysis, generating a larger JSON file

Apart from the presets, other strings will be passed directly to [Env Filter](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#example-syntax), supporting more complex filtering strategies:

### Tracing level filter

The supported tracing levels are: `TRACE`, `DEBUG`, `INFO`, `WARN`, and `ERROR`. You can filter by level:

```sh
# trace level is the highest level, outputting all logs
RSPACK_PROFILE=trace
# only output logs less than or equal to INFO level
RSPACK_PROFILE=info
```

### Module level filtering

```sh
# View rspack_resolver logs
RSPACK_TRACE_LAYER=logger RSPACK_PROFILE=rspack_resolver
```

### Mixed filtering

EnvFilter supports mixed use of multiple filtering conditions to implement more complex filtering strategies:

```sh
# View WARN level logs in the rspack_core crate
RSPACK_PROFILE=rspack_core=warn
# Keep INFO level logs for other crates but turn off logs for rspack_resolver
RSPACK_PROFILE=info,rspack_core=off
```



---
url: /contribute/index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Contributing guide

We are grateful for your interest in contributing to Rspack!

Every single contribution counts and helps us take Rspack to the next level.

## Asking questions

If you have any questions,
please do not hesitate to ask either in the [Discord](https://discord.gg/sYK4QjyZ4V) support channel or on the [GitHub discussion board](https://github.com/web-infra-dev/rspack/discussions).

### Minimal reproduction

The [Rspack repro template](https://github.com/web-infra-dev/rspack-repro) can be used to create a minimal reproducible example.

A minimal reproducible example (MRE) is a code that is:

- Short
- Self-contained
- Demonstrates the problem being encountered

An MRE is essential because it allows us to quickly understand and reproduce your issue.
This, in turn, increases the likelihood of getting a helpful and accurate response in a shorter amount of time.
It is important to note that an MRE should not include extraneous code related to unrelated functionality,
and should instead focus solely on the problem at hand.

> Please see also [How to create a Minimal, Reproducible Example](https://stackoverflow.com/help/minimal-reproducible-example) from Stack Overflow.

## What should I work on?

### Good first issue

If you are looking to dive into the codebase and get started,
we recommend checking out our issue list labeled with [good first issue](https://github.com/web-infra-dev/rspack/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22).
This will help you get acquainted with the project and start contributing.

### Tracking issue

If you are interested in understanding our project's direction and want to work on issues that are aligned with our priorities,
our [tracking issues list](https://github.com/web-infra-dev/rspack/issues?q=is%3Aopen+label%3A%22tracking+issue%22+sort%3Aupdated-desc)
provides an overview of our progress and current goals.

## Sending pull request

1. [Fork](https://help.github.com/articles/fork-a-repo/) the Rspack repository into your own GitHub account.
2. [Clone](https://help.github.com/articles/cloning-a-repository/) the repository to your local.
3. Checkout a new branch from `main`.
4. Set up the development environment, you can read the [Prerequisites](/contribute/development/prerequisites.md) section to learn about it.
5. If you've fixed a bug or added code that should be tested, then add some tests.
6. Make sure all the tests pass, you can read the [Testing](/contribute/development/testing.md) section below to learn about it.
7. Run `pnpm run lint:js` to check JS code, and run `pnpm run lint:rs` to check Rust code.
8. Submit the Pull Request, make sure all CI runs pass.
9. The maintainers will review your Pull Request soon.

When submitting a Pull Request, please note the following:

- Keep your PRs small enough, so that each PR only addresses a single issue or adds a single feature.
- Please include an appropriate description in the PR, and link related issues.

### Format of PR titles

The format of PR titles follow [Conventional Commits](https://www.conventionalcommits.org/).

An example:

```text
feat(core): Add `fooBar` config
^    ^      ^
|    |      |__ Subject
|    |_______ Scope (optional)
|____________ Type
```

If your PR contains any breaking changes, please append a `!` after the type/scope, then add the [release: breaking change](https://github.com/web-infra-dev/rspack/labels) GitHub label.

```text
fix!: remove deprecated `fooBar` config
fix(core)!: remove deprecated `fooBar` config
```

## Other ways to contribute

We are always looking for contributors, and that goes beyond just our main repository.

Check out these other ways to get involved and start making a difference today.

- The documentation site is at [web-infra-dev/rspack/website](https://github.com/web-infra-dev/rspack/tree/main/website)
- The community packages are at [github.com/rstackjs](https://github.com/rstackjs)
- Welcome to add Rspack related projects to [awesome-rstack](https://github.com/rstackjs/awesome-rstack)

***

As a reminder, all contributors are expected to follow our [Code of Conduct](https://github.com/web-infra-dev/rspack/blob/main/CODE_OF_CONDUCT.md).



---
url: /errors/swc-plugin-version.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# SWC plugin version mismatch

## Why this error occurred

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 to 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 the following error during the build process:

```text
The version of the SWC Wasm plugin you're using might not be compatible with 'builtin:swc-loader'
```

## Possible ways to fix it

If you encounter the above issues, a common solution is to upgrade both the Rspack and SWC plugins to the latest versions.

Alternatively, you can follow these steps to select a suitable SWC plugin version:

1. Check the current version of [@rspack/core](https://www.npmjs.com/package/@rspack/core) you are using.
2. Visit [plugins.swc.rs](https://plugins.swc.rs/) and select the version of Rspack you are currently using.
3. The website will list the range of SWC plugin versions that match to your current Rspack version. Then select the matched version of the SWC plugin to use.

If the SWC plugin you are using is not listed on [plugins.swc.rs](https://plugins.swc.rs/), you can find the version information of `swc_core` in the Cargo.toml file within the Rust code repository.

For example, in the Rspack repository, you can open [Cargo.toml](https://github.com/web-infra-dev/rspack/blob/main/Cargo.toml) and search for the keyword `swc_core` to find the version. Then read [SWC - Selecting the version](https://swc.rs/docs/plugin/selecting-swc-core) for further guidance.



---
url: /index.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

![background](https://assets.rspack.rs/rspack/assets/landingpage-background-compressed.png)

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

# Rspack

Fast Rust-based bundler for the web

Seamlessly replace webpack with modernized webpack API

Get Started[GitHubGitHub](https://github.com/web-infra-dev/rspack)

[![Fast Startup](/static/svg/Speedometer.e6ce5b2c32.svg)### Fast Startup

Parallelized Rust architecture for ultimate developer experience

](/guide/start/introduction)

[![Lightning HMR](/static/svg/Lightning.7b8c41ecd3.svg)### Lightning HMR

Built-in incremental build for superior HMR performance

](/guide/start/introduction)

[![Framework Agnostic](/static/svg/FrameCheck.ccc904a9ef.svg)### Framework Agnostic

Works with any frontend UI framework

](/guide/integrations/react)

[![Webpack Compatible](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgMTI4IDEyOCIgd2lkdGg9IjQyNCIKICBoZWlnaHQ9IjQyNCIgcHJlc2VydmVBc3BlY3RSYXRpbz0ieE1pZFlNaWQgbWVldCIKICBzdHlsZT0id2lkdGg6IDEwMCU7IGhlaWdodDogMTAwJTsgdHJhbnNmb3JtOiB0cmFuc2xhdGUzZCgwcHgsIDBweCwgMHB4KTsgY29udGVudC12aXNpYmlsaXR5OiB2aXNpYmxlOyBiYWNrZ3JvdW5kLWNvbG9yOiB0cmFuc3BhcmVudDsiPgogIDxkZWZzPgogICAgPGNsaXBQYXRoIGlkPSJfX2xvdHRpZV9lbGVtZW50XzMzIj4KICAgICAgPHJlY3Qgd2lkdGg9IjEyOCIgaGVpZ2h0PSIxMjgiIHg9IjAiIHk9IjAiIC8+CiAgICA8L2NsaXBQYXRoPgogIDwvZGVmcz4KICA8ZyBjbGlwLXBhdGg9InVybCgjX19sb3R0aWVfZWxlbWVudF8zMykiPgogICAgPGcgdHJhbnNmb3JtPSJtYXRyaXgoMC43NDAwMDAwMDk1MzY3NDMyLDAsMCwwLjc0MDAwMDAwOTUzNjc0MzIsMjMuMjk5OTk5MjM3MDYwNTQ3LDM4Ljg0MDAwMDE1MjU4Nzg5KSIgb3BhY2l0eT0iMSIKICAgICAgc3R5bGU9ImRpc3BsYXk6IGJsb2NrOyI+CiAgICAgIDxnIG9wYWNpdHk9IjEiIHRyYW5zZm9ybT0ibWF0cml4KDEsMCwwLDEsMjcsMzQpIj4KICAgICAgICA8cGF0aCBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0ibWl0ZXIiIGZpbGwtb3BhY2l0eT0iMCIgc3Ryb2tlLW1pdGVybGltaXQ9IjQiCiAgICAgICAgICBzdHJva2U9InJnYigyNTUsMTM4LDApIiBzdHJva2Utb3BhY2l0eT0iMSIgc3Ryb2tlLXdpZHRoPSI1IgogICAgICAgICAgZD0iIE0xMCwtMjcgQzEwLC0yNyAxNCwtMjcgMTQsLTI3IEMxNi44Mjc5OTkxMTQ5OTAyMzQsLTI3IDE4LjI0MzAwMDAzMDUxNzU3OCwtMjcgMTkuMTIxMDAwMjg5OTE2OTkyLC0yNi4xMjEwMDAyODk5MTY5OTIgQzIwLC0yNS4yNDMwMDAwMzA1MTc1NzggMjAsLTIzLjgyNzk5OTExNDk5MDIzNCAyMCwtMjEgQzIwLC0yMSAyMCwtMTMuNSAyMCwtMTMuNSBNLTEwLC0yNyBDLTEwLC0yNyAtMTQsLTI3IC0xNCwtMjcgQy0xNi44Mjc5OTkxMTQ5OTAyMzQsLTI3IC0xOC4yNDMwMDAwMzA1MTc1NzgsLTI3IC0xOS4xMjEwMDAyODk5MTY5OTIsLTI2LjEyMTAwMDI4OTkxNjk5MiBDLTIwLC0yNS4yNDMwMDAwMzA1MTc1NzggLTIwLC0yMy44Mjc5OTkxMTQ5OTAyMzQgLTIwLC0yMSBDLTIwLC0yMSAtMjAsLTEzLjUgLTIwLC0xMy41IE0tMjAsMTMuNSBDLTIwLDEzLjUgLTIwLDIxIC0yMCwyMSBDLTIwLDIzLjgyNzk5OTExNDk5MDIzNCAtMjAsMjUuMjQzMDAwMDMwNTE3NTc4IC0xOS4xMjEwMDAyODk5MTY5OTIsMjYuMTIxMDAwMjg5OTE2OTkyIEMtMTguMjQzMDAwMDMwNTE3NTc4LDI3IC0xNi44Mjc5OTkxMTQ5OTAyMzQsMjcgLTE0LDI3IEMtMTQsMjcgLTEwLDI3IC0xMCwyNyBNMTAsMjcgQzEwLDI3IDE0LDI3IDE0LDI3IEMxNi44Mjc5OTkxMTQ5OTAyMzQsMjcgMTguMjQzMDAwMDMwNTE3NTc4LDI3IDE5LjEyMTAwMDI4OTkxNjk5MiwyNi4xMjEwMDAyODk5MTY5OTIgQzIwLDI1LjI0MzAwMDAzMDUxNzU3OCAyMCwyMy44Mjc5OTkxMTQ5OTAyMzQgMjAsMjEgQzIwLDIxIDIwLDEzLjUgMjAsMTMuNSIgLz4KICAgICAgPC9nPgogICAgPC9nPgogICAgPGcgdHJhbnNmb3JtPSJtYXRyaXgoMC43NDAwMDAwMDk1MzY3NDMyLDAsMCwwLjc0MDAwMDAwOTUzNjc0MzIsNjQuNzM5OTk3ODYzNzY5NTMsMzguODQwMDAwMTUyNTg3ODkpIiBvcGFjaXR5PSIxIgogICAgICBzdHlsZT0iZGlzcGxheTogYmxvY2s7Ij4KICAgICAgPGcgb3BhY2l0eT0iMSIgdHJhbnNmb3JtPSJtYXRyaXgoMSwwLDAsMSwyNywzNCkiPgogICAgICAgIDxwYXRoIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJtaXRlciIgZmlsbC1vcGFjaXR5PSIwIiBzdHJva2UtbWl0ZXJsaW1pdD0iNCIKICAgICAgICAgIHN0cm9rZT0icmdiKDI1NSwxMzgsMCkiIHN0cm9rZS1vcGFjaXR5PSIxIiBzdHJva2Utd2lkdGg9IjUiCiAgICAgICAgICBkPSIgTS0yMCwtMTMuNSBDLTIwLC0xMy41IC0yMCwtMjEgLTIwLC0yMSBDLTIwLC0yMy44Mjc5OTkxMTQ5OTAyMzQgLTIwLC0yNS4yNDMwMDAwMzA1MTc1NzggLTE5LjEyMTAwMDI4OTkxNjk5MiwtMjYuMTIxMDAwMjg5OTE2OTkyIEMtMTguMjQzMDAwMDMwNTE3NTc4LC0yNyAtMTYuODI3OTk5MTE0OTkwMjM0LC0yNyAtMTQsLTI3IEMtMTQsLTI3IDE0LC0yNyAxNCwtMjcgQzE2LjgyNzk5OTExNDk5MDIzNCwtMjcgMTguMjQzMDAwMDMwNTE3NTc4LC0yNyAxOS4xMjEwMDAyODk5MTY5OTIsLTI2LjEyMTAwMDI4OTkxNjk5MiBDMjAsLTI1LjI0MzAwMDAzMDUxNzU3OCAyMCwtMjMuODI3OTk5MTE0OTkwMjM0IDIwLC0yMSBDMjAsLTIxIDIwLDIxIDIwLDIxIEMyMCwyMy44Mjc5OTkxMTQ5OTAyMzQgMjAsMjUuMjQzMDAwMDMwNTE3NTc4IDE5LjEyMTAwMDI4OTkxNjk5MiwyNi4xMjEwMDAyODk5MTY5OTIgQzE4LjI0MzAwMDAzMDUxNzU3OCwyNyAxNi44Mjc5OTkxMTQ5OTAyMzQsMjcgMTQsMjcgQzE0LDI3IC0xNCwyNyAtMTQsMjcgQy0xNi44Mjc5OTkxMTQ5OTAyMzQsMjcgLTE4LjI0MzAwMDAzMDUxNzU3OCwyNyAtMTkuMTIxMDAwMjg5OTE2OTkyLDI2LjEyMTAwMDI4OTkxNjk5MiBDLTIwLDI1LjI0MzAwMDAzMDUxNzU3OCAtMjAsMjMuODI3OTk5MTE0OTkwMjM0IC0yMCwyMSBDLTIwLDIxIC0yMCwxMy41IC0yMCwxMy41IiAvPgogICAgICA8L2c+CiAgICA8L2c+CiAgICA8ZyB0cmFuc2Zvcm09Im1hdHJpeCgwLjc0MDAwMDAwOTUzNjc0MzIsMCwwLDAuNzQwMDAwMDA5NTM2NzQzMiw0MC42ODk5OTg2MjY3MDg5ODQsNTIuOTAwMDAxNTI1ODc4OTA2KSIgb3BhY2l0eT0iMSIKICAgICAgc3R5bGU9ImRpc3BsYXk6IGJsb2NrOyI+CiAgICAgIDxnIG9wYWNpdHk9IjEiIHRyYW5zZm9ybT0ibWF0cml4KDEsMCwwLDEsNTguNSwxNSkiPgogICAgICAgIDxwYXRoIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIgZmlsbC1vcGFjaXR5PSIwIiBzdHJva2U9InJnYigyNDksNTcsMzIpIiBzdHJva2Utb3BhY2l0eT0iMSIKICAgICAgICAgIHN0cm9rZS13aWR0aD0iNiIgZD0iIE0tNCw4IEMtNCw4IDQsMCA0LDAgQzQsMCAtNCwtOCAtNCwtOCIgLz4KICAgICAgPC9nPgogICAgICA8ZyBvcGFjaXR5PSIxIiB0cmFuc2Zvcm09Im1hdHJpeCgxLDAsMCwxLDAsMCkiPgogICAgICAgIDxwYXRoIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJtaXRlciIgZmlsbC1vcGFjaXR5PSIwIiBzdHJva2UtbWl0ZXJsaW1pdD0iNCIKICAgICAgICAgIHN0cm9rZT0icmdiKDI0OSw1NywzMikiIHN0cm9rZS1vcGFjaXR5PSIxIiBzdHJva2Utd2lkdGg9IjYiIGQ9IiBNMy41LDE1IEMzLjUsMTUgNjIuNSwxNSA2Mi41LDE1IiAvPgogICAgICA8L2c+CiAgICA8L2c+CiAgPC9nPgo8L3N2Zz4=)### Webpack Compatible

Compatible with webpack plugins and loaders from community

](/plugins/community-plugin-compatibility)

# Lightning Fast

Combining Rust and TypeScript with a parallelized architecture to bring you the enjoyable developer experience

Rspack

1.36s dev

3.35s build

160ms hmr

Vite

6.50s dev

1.98s build

130ms hmr

webpack

21.40s dev

28.10s build

2.78s hmr

[See benchmark details](https://github.com/rstackjs/build-tools-performance)

# Fully Featured

Launched as a drop-in replacement for webpack, with more powerful features and exceptional productivity

[![0](data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB3aWR0aD0iMzJweCIgaGVpZ2h0PSIzMnB4IiB2aWV3Qm94PSIwIDAgMzIgMzIiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIgogIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIj4KICA8dGl0bGU+SWNvbj1Db2RlIFNwbGl0dGluZzwvdGl0bGU+CiAgPGcgaWQ9IlBhZ2UtMSIgc3Ryb2tlPSJub25lIiBzdHJva2Utd2lkdGg9IjEiIGZpbGw9Im5vbmUiIGZpbGwtcnVsZT0iZXZlbm9kZCI+CiAgICA8ZyBpZD0iSWNvbj1Db2RlLVNwbGl0dGluZyI+CiAgICAgIDxyZWN0IGlkPSJSZWN0YW5nbGUiIHg9IjAiIHk9IjAiIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiI+PC9yZWN0PgogICAgICA8ZyBpZD0ic3BsaXQtYXJyb3ciIHRyYW5zZm9ybT0idHJhbnNsYXRlKDUsIDQpIiBmaWxsPSIjMEIwQzBFIiBmaWxsLXJ1bGU9Im5vbnplcm8iPgogICAgICAgIDxwYXRoCiAgICAgICAgICBkPSJNMjAuMTcxOTI1MiwxLjkzNjgxMTE2ZS0wOCBMMTQuNzY3NDE3OSwwLjAwMTQwNTU1NTYyIEMxNC4xNTEwMjA3LDAuMDAxMjkzMDA3MTUgMTMuNjQ3OTkwNCwwLjQ5MTcxMDUxNSAxMy42MzYxNzYyLDEuMTA0MjgzIEMxMy42MjIwMzU2LDEuNzM0NDMxNzUgMTQuMTU0NjYyLDIuMjUwMjYzNTYgMTQuNzkwNTE0MSwyLjI1MDI2MzU2IEwxNy40NzEwODU2LDIuMjUwMjYzNTYgTDEyLjcxMzI3MTUsNi45Nzk0MjQ1MiBDMTIuMjcxNTI5NSw3LjQxODUzNTMzIDEyLjI3MTUyOTUsOC4xMzA0NDM3MyAxMi43MTMyNzE1LDguNTY5NTU0NTQgTDEyLjcxMzI3MTUsOC41Njk1NTQ1NCBDMTMuMTU1MDQyOCw5LjAwODYzNjIyIDEzLjg3MTI2NDUsOS4wMDg2MzYyMiAxNC4zMTMwMzU4LDguNTY5NTU0NTQgTDE5LjA3MDg0OTksMy44NDAzOTM1NyBMMTkuMDcwODQ5OSw2LjU1Nzc2MzY1IEMxOS4wNzA4NDk5LDcuMTc4NzY4NjQgMTkuNTc3MzI0MSw3LjY4MjE5MjY1IDIwLjIwMjA5MTYsNy42ODIxOTI2NSBMMjAuMjAyMDkxNiw3LjY4MjE5MjY1IEMyMC44MjY4NTkyLDcuNjgyMTkyNjUgMjEuMzMzMzMzMyw3LjE3ODc2ODY0IDIxLjMzMzMzMzMsNi41NTc3NjM2NSBMMjEuMzMzMzMzMywxLjE1NTM1MDgyIEMyMS4zMzMwNzM4LDAuNTE3NzQwODU5IDIwLjgxMzM5NzksMC4wMDA3NzUzMzQwMzEgMjAuMTcxOTI1MiwxLjkzNjgxMTE2ZS0wOCBMMjAuMTcxOTI1MiwxLjkzNjgxMTE2ZS0wOCBaIE0yLjI2MjQ4MzQzLDMuODQwMzkzNTcgTDIuMjYyNDgzNDMsNi41NTc3NjM2NSBDMi4yNjI0ODM0Myw3LjE3ODc2ODY0IDEuNzU2MDA5MjYsNy42ODIxOTI2NSAxLjEzMTI0MTcxLDcuNjgyMTkyNjUgTDEuMTMxMjQxNzEsNy42ODIxOTI2NSBDMC41MDY0NzQxNjcsNy42ODIxOTI2NSAwLDcuMTc4NzY4NjQgMCw2LjU1Nzc2MzY1IEwwLDEuMTU1MzUwODIgQzAuMDAwMjU5NTQ3MzE5LDAuNTE3NzQwODU5IDAuNTE5OTM1NDU5LDAuMDAwNzc1MzM0MDMxIDEuMTYxNDA4MTYsMCBMNi41NjgyNzIyMSwwIEM3LjE4NDY2OTM4LDAgNy42ODc2OTk2NSwwLjQ5MDMwNDk3OSA3LjY5OTUxMzkyLDEuMTAyODc3NDYgQzcuNzExMjk3NjksMS43MzQ0MzE3NSA3LjE3ODY3MTM4LDIuMjUwMjYzNTYgNi41NDI4MTkyNywyLjI1MDI2MzU2IEwzLjg2MjI0Nzc1LDIuMjUwMjYzNTYgTDExLjQ2Nzk2MjksOS44MDg3NjkgQzExLjY3OTk0MzUsMTAuMDIwMjA0IDExLjc5ODY0NDgsMTAuMzA2NzQyNiAxMS43OTc5MTE4LDEwLjYwNTIzOTUgTDExLjc5NzkxMTgsMjIuODc1NTcxIEMxMS43OTc5MTE4LDIzLjQ5NjU3NiAxMS4yOTE0MzQyLDI0IDEwLjY2NjY2NjcsMjQgQzEwLjA0MTg5OTEsMjQgOS41MzU0MjQ5NSwyMy40OTY1NzYgOS41MzU0MjQ5NSwyMi44NzU1NzEgTDkuNTM1NDI0OTUsMTEuMDY5MDY2NSBMMi4yNjI0ODM0MywzLjg0MDM5MzU3IFoiCiAgICAgICAgICBpZD0iU2hhcGUiPjwvcGF0aD4KICAgICAgPC9nPgogICAgPC9nPgogIDwvZz4KPC9zdmc+)## Code Splitting

Split code into smaller bundles to enable on-demand loading and improve performance.

](/guide/optimization/code-splitting)[![1](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICA8cGF0aAogICAgZD0iTTEyLjIyNzggNi45MDE0NUwxMi4yMjc2IDYuOTExMzVMMTIuMjI3NyA2LjkyMTI1QzEyLjIzNTQgNy40MzcxOCAxMi4xNDE0IDcuOTQ5NTYgMTEuOTUxIDguNDI5MTVDMTEuNzYwNiA4LjkwODczIDExLjQ3NzYgOS4zNDYxMSAxMS4xMTgyIDkuNzE2MzJDMTAuNzU4OCAxMC4wODY1IDEwLjMzIDEwLjM4MjMgOS44NTYyMiAxMC41ODY4QzkuMzg0NzIgMTAuNzkwMiA4Ljg3NzkyIDEwLjg5OTMgOC4zNjQ1IDEwLjkwNzhDNy44NTEwOCAxMC44OTkzIDcuMzQ0MjggMTAuNzkwMiA2Ljg3Mjc4IDEwLjU4NjhDNi4zOTkwMyAxMC4zODIzIDUuOTcwMiAxMC4wODY1IDUuNjEwNzggOS43MTYzMkM1LjI1MTM1IDkuMzQ2MTEgNC45NjgzOCA4LjkwODczIDQuNzc4MDEgOC40MjkxNUM0LjU4NzY1IDcuOTQ5NTYgNC40OTM2MiA3LjQzNzE4IDQuNTAxMyA2LjkyMTI1TDQuNTAxNDUgNi45MTEzNUw0LjUwMTIgNi45MDE0NkM0LjQ4ODM1IDYuMzgxNjggNC41Nzg1MiA1Ljg2NDUgNC43NjY1MSA1LjM3OTc0QzQuOTU0NSA0Ljg5NDk4IDUuMjM2NTggNC40NTIyMyA1LjU5NjUgNC4wNzcwMUM1Ljk1NjQzIDMuNzAxNzkgNi4zODcwNiAzLjQwMTUzIDYuODYzNTggMy4xOTM1NEM3LjMzNzUyIDIuOTg2NjggNy44NDc1MyAyLjg3NTE2IDguMzY0NSAyLjg2NTMxQzguODgxNDcgMi44NzUxNiA5LjM5MTQ3IDIuOTg2NjggOS44NjU0MSAzLjE5MzU0QzEwLjM0MTkgMy40MDE1MyAxMC43NzI2IDMuNzAxNzkgMTEuMTMyNSA0LjA3NzAxTDExLjQ5MzMgMy43MzA4OUwxMS4xMzI1IDQuMDc3MDFDMTEuNDkyNCA0LjQ1MjIzIDExLjc3NDUgNC44OTQ5OCAxMS45NjI1IDUuMzc5NzRDMTIuMTUwNSA1Ljg2NDUgMTIuMjQwNiA2LjM4MTY4IDEyLjIyNzggNi45MDE0NVpNOC4zODExOSA0LjA0NzA4TDguMzY0NjkgNC4wNDY1M0w4LjM0ODE5IDQuMDQ3MDdDNy45ODI0NCA0LjA1OTAxIDcuNjIyNzIgNC4xNDM2MiA3LjI5IDQuMjk1OTZDNi45NTcyOCA0LjQ0ODMxIDYuNjU4MiA0LjY2NTM1IDYuNDEwMTkgNC45MzQ0NEM2LjE2MjE5IDUuMjAzNTIgNS45NzAyMSA1LjUxOTI4IDUuODQ1NDYgNS44NjMzQzUuNzIyMjQgNi4yMDMwNiA1LjY2NzAyIDYuNTYzNjkgNS42ODI5IDYuOTI0NjhDNS42ODI1NSA3LjYzNzY5IDUuOTU4MzggOC4zMjMzNCA2LjQ1MjgyIDguODM3NTVDNi45NTAzOSA5LjM1NTAzIDcuNjMwMTMgOS42NTgwOSA4LjM0NzYgOS42ODIzNkw4LjM2NDQzIDkuNjgyOTNMOC4zODEyNiA5LjY4MjM3QzkuMTA4MDkgOS42NTc5OSA5Ljc5NTg4IDkuMzQ3NTMgMTAuMjk0OSA4LjgxODUzQzEwLjc5MDkgOC4yOTI4MyAxMS4wNjA1IDcuNTkzNiAxMS4wNDYyIDYuODcxMzhDMTEuMDY0MSA2LjE0Njg4IDEwLjc5NiA1LjQ0NDI0IDEwLjI5OTcgNC45MTU2NUw5LjkzNTE3IDUuMjU3OUwxMC4yOTk3IDQuOTE1NjVDOS44MDAyNCA0LjM4Mzc2IDkuMTEwNCA0LjA3MTQ0IDguMzgxMTkgNC4wNDcwOFpNNy43NzM3MSAyMC43NDVWMTMuNzczMUg4Ljk1NTI4VjE3LjI4NzJWMTguNTU0OEw5LjgyMDY1IDE3LjYyODVDMTAuNDcyNiAxNi45MzA3IDExLjI2MDYgMTYuMzczOCAxMi4xMzYgMTUuOTkyMUMxMy4wMTEyIDE1LjYxMDUgMTMuOTU1MyAxNS40MTIxIDE0LjkxIDE1LjQwOTNIMTguMTgxNlYxNS40MDk0TDE4LjE5MjYgMTUuNDA5MkMxOS4zNDYzIDE1LjM4MzcgMjAuNDU0NiAxNC45NTQzIDIxLjMyNDIgMTQuMTk1NkMyMi4xOTM4IDEzLjQzNjkgMjIuNzY5NiAxMi4zOTcxIDIyLjk1MTIgMTEuMjU3NUwyMy4wMiAxMC44MjU4TDIyLjYwMTMgMTAuNjk5OUMyMS43Nzk4IDEwLjQ1MzEgMjEuMDYwMiA5Ljk0Njg2IDIwLjU1MDMgOS4yNTcwNEMyMC4wNDA0IDguNTY3MjMgMTkuNzY3NCA3LjczMDg3IDE5Ljc3MjMgNi44NzMwNEwxOS43NzI1IDYuODczMDRMMTkuNzcyMyA2Ljg2Mjc0QzE5Ljc1NjggNS44MTk1MyAyMC4xNTU3IDQuODEyNzcgMjAuODgxNSA0LjA2MzMzQzIxLjYwNTQgMy4zMTU5MyAyMi41OTU1IDIuODg1MzMgMjMuNjM1NSAyLjg2NTMyQzI0LjE1MjUgMi44NzUxNyAyNC42NjI1IDIuOTg2NjggMjUuMTM2NCAzLjE5MzU0QzI1LjYxMjkgMy40MDE1MyAyNi4wNDM2IDMuNzAxNzkgMjYuNDAzNSA0LjA3NzAxQzI2Ljc2MzQgNC40NTIyMiAyNy4wNDU1IDQuODk0OTggMjcuMjMzNSA1LjM3OTc0QzI3LjQyMTUgNS44NjQ1IDI3LjUxMTYgNi4zODE2OCAyNy40OTg4IDYuOTAxNDVMMjcuNDk4NiA2LjkwOTU1TDI3LjQ5ODcgNi45MTc2NUMyNy41MDU0IDcuODAyNjMgMjcuMjE2NSA4LjY2NDU0IDI2LjY3NzcgOS4zNjY2QzI2LjEzODggMTAuMDY4NyAyNS4zODEgMTAuNTcwNyAyNC41MjQzIDEwLjc5M0wyNC4xOTUxIDEwLjg3ODRMMjQuMTUzNyAxMS4yMTYxQzIzLjk3MzcgMTIuNjgyOSAyMy4yNjkxIDE0LjAzNTEgMjIuMTcgMTUuMDIzQzIxLjA3MTggMTYuMDEwMSAxOS42NTM5IDE2LjU2NjkgMTguMTc3NiAxNi41OTA4SDE0LjkwOTJWMTYuNTkwOEwxNC45MDAyIDE2LjU5MDlDMTMuNjUxNiAxNi42MTM0IDEyLjQ0MTYgMTcuMDI3OSAxMS40NDE1IDE3Ljc3NTlDMTAuNDQxNCAxOC41MjM4IDkuNzAxNzkgMTkuNTY3MyA5LjMyNzM0IDIwLjc1ODdMOS4xODQ4OCAyMS4yMTE5TDkuNjMwMjggMjEuMzc3M0MxMC41MDE3IDIxLjcwMDkgMTEuMjMzNCAyMi4zMTc1IDExLjcgMjMuMTIxNUMxMi4xNjY1IDIzLjkyNTQgMTIuMzM4OSAyNC44NjY2IDEyLjE4NzYgMjUuNzgzOEMxMi4wMzYzIDI2LjcwMDkgMTEuNTcwNyAyNy41MzY4IDEwLjg3MDUgMjguMTQ4M0MxMC4xNzMzIDI4Ljc1NzIgOS4yODY2NiAyOS4xMDU3IDguMzYxNjEgMjkuMTM0N0M3Ljg0NzMxIDI5LjEyNDUgNy4zMzk5NiAyOS4wMTM3IDYuODY4MjEgMjguODA4NEM2LjM5Mjk4IDI4LjYwMTYgNS45NjMyMiAyOC4zMDMxIDUuNjAzNTUgMjcuOTI5OUM1LjI0Mzg4IDI3LjU1NjggNC45NjEzOCAyNy4xMTYzIDQuNzcyMjMgMjYuNjMzOEM0LjU4MzA4IDI2LjE1MTMgNC40OTEgMjUuNjM2MiA0LjUwMTI2IDI1LjExOEw0LjUwMTQgMjUuMTEwOUw0LjUwMTM0IDI1LjEwMzlDNC40OTM4NyAyNC4yMjgxIDQuNzc0NSAyMy4zNzQxIDUuMyAyMi42NzM0QzUuODI1NSAyMS45NzI3IDYuNTY2NzUgMjEuNDY0MiA3LjQwOTYyIDIxLjIyNjJMNy43NzM3MSAyMS4xMjMzVjIwLjc0NVpNMjEuNzA1MSA4LjgxODUzQzIyLjA5MTggOS4yMjg0NCAyMi41OTE4IDkuNTA3MTMgMjMuMTM1NSA5LjYyMzE4VjkuNzQyOThMMjMuNjUxOSA5LjcyNjAxQzI0LjAxNjUgOS43MTQwMyAyNC4zNzUxIDkuNjI5ODQgMjQuNzA2OSA5LjQ3ODMzQzI1LjAzODcgOS4zMjY4MSAyNS4zMzcyIDkuMTEwOTggMjUuNTg1IDguODQzMzNDMjUuODMyOCA4LjU3NTY3IDI2LjAyNTEgOC4yNjE1MiAyNi4xNTA3IDcuOTE5MDRMMjUuNjgxMiA3Ljc0NjkxTDI2LjE1MDcgNy45MTkwNEMyNi4yNzUgNy41ODAwMSAyNi4zMzE1IDcuMjE5OSAyNi4zMTcgNi44NTkxNUMyNi4zMTQxIDYuMTUxOTMgMjYuMDMxOSA1LjQ3NDMxIDI1LjUzMTcgNC45NzQwMkMyNS4wMjg4IDQuNDcxMTMgMjQuMzQ2NyA0LjE4ODYxIDIzLjYzNTUgNC4xODg2MUMyMi45MjQzIDQuMTg4NjEgMjIuMjQyMiA0LjQ3MTEzIDIxLjczOTMgNC45NzQwMkMyMS4yMzc5IDUuNDc1NDUgMjAuOTU1NiA2LjE1NTAyIDIwLjk1MzkgNi44NjM5OEMyMC45Mzc2IDcuNTg4ODMgMjEuMjA3NCA4LjI5MTAzIDIxLjcwNTEgOC44MTg1M1oiCiAgICBmaWxsPSIjMEIwQzBFIiBzdHJva2U9IiMwQjBDMEUiIC8+Cjwvc3ZnPg==)## Tree Shaking

Detect and eliminate unused code from the final bundles to reduce output size.

](/guide/optimization/tree-shaking)[![2](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICA8cGF0aAogICAgZD0iTTI3LjE4MDMgMTEuODMxTDI3LjE2NjggMTEuODM3OEwyNy4xNTM4IDExLjg0NTNMMTYuMzY0MSAxOC4wNzk0QzE2LjI4NSAxOC4xMTggMTYuMjQ1NiAxOC4xMjc2IDE2LjIxNzkgMTguMTMyMkMxNi4xNzY0IDE4LjEzOTEgMTYuMTI5OSAxOC4xNDA0IDE2IDE4LjE0MDRDMTUuODcwMSAxOC4xNDA0IDE1LjgyMzYgMTguMTM5MSAxNS43ODIxIDE4LjEzMjJDMTUuNzU0NCAxOC4xMjc2IDE1LjcxNSAxOC4xMTggMTUuNjM1OSAxOC4wNzk0TDQuODUwMjUgMTEuODQ3NkM0LjUyNDgzIDExLjY1MDIgNC40MDggMTEuMjM0NyA0LjU3MjY2IDEwLjgwMjZDNC42MTI1OCAxMC43MjU3IDQuNjQxMjkgMTAuNjg5NCA0LjY2NDU1IDEwLjY2NjFDNC42ODk2MiAxMC42NDExIDQuNzI5ODIgMTAuNjA5NyA0LjgxOTcgMTAuNTY0N0w0LjgzMzE4IDEwLjU1OEw0Ljg0NjIzIDEwLjU1MDRMMTUuNjQ5OSA0LjMwODMxTDE1LjY2MzggNC4zMDAyOUwxNS42NzcxIDQuMjkxNEMxNS44NjkzIDQuMTYzMjggMTYuMTMwNyA0LjE2MzI4IDE2LjMyMjkgNC4yOTE0TDE2LjMzNjIgNC4zMDAyOUwxNi4zNTAxIDQuMzA4MzFMMjcuMTQ5NyAxMC41NDgxQzI3LjQ3NTIgMTAuNzQ1NSAyNy41OTIgMTEuMTYxMSAyNy40MjczIDExLjU5MzJDMjcuMzg3NCAxMS42NzAxIDI3LjM1ODcgMTEuNzA2NCAyNy4zMzU0IDExLjcyOTZDMjcuMzEwNCAxMS43NTQ3IDI3LjI3MDIgMTEuNzg2MSAyNy4xODAzIDExLjgzMVpNNC44NDYyMyAxNi42NDdMNC44MzMxOCAxNi42Mzk0TDQuODE5NyAxNi42MzI3QzQuNzI5ODIgMTYuNTg3NyA0LjY4OTYyIDE2LjU1NjMgNC42NjQ1NSAxNi41MzEzQzQuNjQxMjkgMTYuNTA4IDQuNjEyNTggMTYuNDcxNyA0LjU3MjY2IDE2LjM5NDhDNC40MTI5OSAxNS45NzU4IDQuNTE4IDE1LjU3MjQgNC44MjEyIDE1LjM2ODNMMTUuMTM2OCAyMS4zNDY3QzE1LjY1ODMgMjEuNjg2MSAxNi4zNDE3IDIxLjY4NjEgMTYuODYzMiAyMS4zNDY3TDI3LjE4MTMgMTUuMzY2OUMyNy4yNzA1IDE1LjQxMTYgMjcuMzEwNSAxNS40NDI4IDI3LjMzNTQgMTUuNDY3OEMyNy4zNTg3IDE1LjQ5MSAyNy4zODc0IDE1LjUyNzMgMjcuNDI3MyAxNS42MDQyQzI3LjU5MiAxNi4wMzYzIDI3LjQ3NTIgMTYuNDUxOSAyNy4xNDk4IDE2LjY0OTNMMTYuMzUwMSAyMi44ODkxTDE2LjMzNjIgMjIuODk3MUwxNi4zMjI5IDIyLjkwNkMxNi4xMzA3IDIzLjAzNDEgMTUuODY5MyAyMy4wMzQxIDE1LjY3NzEgMjIuOTA2TDE1LjY2MzggMjIuODk3MUwxNS42NDk5IDIyLjg4OTFMNC44NDYyMyAxNi42NDdaTTQuODQ2MjMgMjEuNDQ4Nkw0LjgzMzE4IDIxLjQ0MTFMNC44MTk3IDIxLjQzNDNDNC43Mjk4MiAyMS4zODk0IDQuNjg5NjIgMjEuMzU4IDQuNjY0NTUgMjEuMzMyOUM0LjY0MTI5IDIxLjMwOTcgNC42MTI1OCAyMS4yNzM0IDQuNTcyNjYgMjEuMTk2NUM0LjQxMjk5IDIwLjc3NzUgNC41MTggMjAuMzc0MSA0LjgyMTIgMjAuMTdMMTUuMTM2OCAyNi4xNDgzQzE1LjY1ODMgMjYuNDg3OCAxNi4zNDE3IDI2LjQ4NzggMTYuODYzMiAyNi4xNDgzTDI3LjE4MTMgMjAuMTY4NUMyNy4yNzA1IDIwLjIxMzIgMjcuMzEwNSAyMC4yNDQ0IDI3LjMzNTQgMjAuMjY5NEMyNy4zNTg3IDIwLjI5MjcgMjcuMzg3NCAyMC4zMjkgMjcuNDI3MyAyMC40MDU5QzI3LjU5MiAyMC44MzggMjcuNDc1MiAyMS4yNTM1IDI3LjE0OTggMjEuNDUwOUwxNi4zNTAxIDI3LjY5MDdMMTYuMzM2MiAyNy42OTg4TDE2LjMyMjkgMjcuNzA3N0MxNi4xMzA3IDI3LjgzNTggMTUuODY5MyAyNy44MzU4IDE1LjY3NzEgMjcuNzA3N0wxNS42NjM4IDI3LjY5ODhMMTUuNjQ5OSAyNy42OTA3TDQuODQ2MjMgMjEuNDQ4NloiCiAgICBmaWxsPSIjMEIwQzBFIiBzdHJva2U9IiMwQjBDMEUiIC8+Cjwvc3ZnPg==)## Plugins

Offer rich plugin hooks and compatibility with most webpack plugins.

](/guide/features/plugin)[![3](/static/svg/moduleFederation.84a325aa99.svg)## Module Federation

Share code between web applications and collaborate more efficiently.

](/guide/advanced/module-federation)

[![0](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICA8cGF0aAogICAgZD0iTTguMjk5NDMgOS4wMzk0MlY5LjM5OThMOC42NDEzMiA5LjUxMzc2QzkuNTUyMTIgOS44MTczNiAxMC4xNzM5IDEwLjUyODMgMTAuNDkxNCAxMS4zNzUyQzExLjExNTEgMTMuMDM4MyAxMC4yODQ1IDE0Ljc3MiA4LjY1MDI5IDE1LjI4MjdMOC4yOTk0MyAxNS4zOTI0VjE1Ljc2VjI2LjgwMDhDOC4yOTk0MyAyNy4wNDcyIDguMjE5NDggMjcuMjEzNyA4LjExNTg1IDI3LjMxNzNDOC4wMTIyMiAyNy40MjEgNy44NDU3NCAyNy41MDA5IDcuNTk5MzQgMjcuNTAwOUM3LjM1MjkzIDI3LjUwMDkgNy4xODY0NSAyNy40MjEgNy4wODI4MiAyNy4zMTczQzYuOTc5MTkgMjcuMjEzNyA2Ljg5OTI0IDI3LjA0NzIgNi44OTkyNCAyNi44MDA4VjE1Ljc2VjE1LjQxMzVMNi41NzQ4IDE1LjI5MThDNS43Mjc5OSAxNC45NzQyIDUuMDE3MDEgMTQuMzUyNSA0LjcxMzQxIDEzLjQ0MTdMNC43MTA0OCAxMy40MzI5TDQuNzA3MjMgMTMuNDI0MkM0LjA4MzU0IDExLjc2MSA0LjkxNDIyIDEwLjAyNzMgNi41NDgzOCA5LjUxNjY2TDYuODk5MjQgOS40MDcwMlY5LjAzOTQyVjUuMTk5MTJDNi44OTkyNCA0Ljk1MjcxIDYuOTc5MTkgNC43ODYyMyA3LjA4MjgyIDQuNjgyNkM3LjE4NjQ1IDQuNTc4OTggNy4zNTI5MyA0LjQ5OTAyIDcuNTk5MzQgNC40OTkwMkM3Ljg0NTc0IDQuNDk5MDIgOC4wMTIyMiA0LjU3ODk4IDguMTE1ODUgNC42ODI2QzguMjE5NDggNC43ODYyMyA4LjI5OTQzIDQuOTUyNzEgOC4yOTk0MyA1LjE5OTEyVjkuMDM5NDJaTTI3LjI4NjYgMTMuNzU3OUwyNy4yODk1IDEzLjc2NjdMMjcuMjkyOCAxMy43NzUzQzI3LjkxNjUgMTUuNDM4NSAyNy4wODU4IDE3LjE3MjIgMjUuNDUxNiAxNy42ODI5TDI1LjEwMDggMTcuNzkyNVYxOC4xNjAxVjI2LjgwMDhDMjUuMTAwOCAyNy4wNDcyIDI1LjAyMDggMjcuMjEzNyAyNC45MTcyIDI3LjMxNzNDMjQuODEzNiAyNy40MjEgMjQuNjQ3MSAyNy41MDA5IDI0LjQwMDcgMjcuNTAwOUMyNC4xNTQzIDI3LjUwMDkgMjMuOTg3OCAyNy40MjEgMjMuODg0MiAyNy4zMTczQzIzLjc4MDUgMjcuMjEzNyAyMy43MDA2IDI3LjA0NzIgMjMuNzAwNiAyNi44MDA4VjE4LjE2MDFWMTcuODEzNkwyMy4zNzYxIDE3LjY5MkMyMi41MjkzIDE3LjM3NDQgMjEuODE4MyAxNi43NTI3IDIxLjUxNDcgMTUuODQxOUwyMS41MTE4IDE1LjgzMzFMMjEuNTA4NiAxNS44MjQ0QzIwLjg4NDkgMTQuMTYxMiAyMS43MTU2IDEyLjQyNzUgMjMuMzQ5NyAxMS45MTY5TDIzLjcwMDYgMTEuODA3MlYxMS40Mzk2VjUuMTk5MTJDMjMuNzAwNiA0Ljk1MjcxIDIzLjc4MDUgNC43ODYyMyAyMy44ODQxIDQuNjgyNkMyMy45ODc4IDQuNTc4OTggMjQuMTU0MyA0LjQ5OTAyIDI0LjQwMDcgNC40OTkwMkMyNC42NDcxIDQuNDk5MDIgMjQuODEzNiA0LjU3ODk4IDI0LjkxNzIgNC42ODI2QzI1LjAyMDggNC43ODYyMyAyNS4xMDA4IDQuOTUyNzEgMjUuMTAwOCA1LjE5OTEyVjExLjQzOTZWMTEuNzg2MUwyNS40MjUyIDExLjkwNzhDMjYuMjcyIDEyLjIyNTMgMjYuOTgzIDEyLjg0NzEgMjcuMjg2NiAxMy43NTc5Wk0xNi43MDAxIDE4LjY0MDJWMTkuMDAwNkwxNy4wNDIgMTkuMTE0NUMxNy45NTI4IDE5LjQxODEgMTguNTc0NSAyMC4xMjkxIDE4Ljg5MjEgMjAuOTc1OUMxOS41MTU4IDIyLjYzOTEgMTguNjg1MSAyNC4zNzI4IDE3LjA1MSAyNC44ODM1TDE2LjcwMDEgMjQuOTkzMVYyNS4zNjA3VjI2LjgwMDhDMTYuNzAwMSAyNy4wNDcyIDE2LjYyMDEgMjcuMjEzNyAxNi41MTY1IDI3LjMxNzNDMTYuNDEyOSAyNy40MjEgMTYuMjQ2NCAyNy41MDA5IDE2IDI3LjUwMDlDMTUuNzUzNiAyNy41MDA5IDE1LjU4NzEgMjcuNDIxIDE1LjQ4MzUgMjcuMzE3M0MxNS4zNzk5IDI3LjIxMzcgMTUuMjk5OSAyNy4wNDcyIDE1LjI5OTkgMjYuODAwOFYyNS4zNjA3VjI1LjAxNDJMMTQuOTc1NSAyNC44OTI1QzE0LjEyODcgMjQuNTc1IDEzLjQxNzcgMjMuOTUzMiAxMy4xMTQxIDIzLjA0MjRMMTMuMTExMSAyMy4wMzM2TDEzLjEwNzkgMjMuMDI1QzEyLjQ4NDIgMjEuMzYxOCAxMy4zMTQ5IDE5LjYyODEgMTQuOTQ5IDE5LjExNzRMMTUuMjk5OSAxOS4wMDc4VjE4LjY0MDJWNS4xOTkxMkMxNS4yOTk5IDQuOTUyNzEgMTUuMzc5OSA0Ljc4NjIzIDE1LjQ4MzUgNC42ODI2QzE1LjU4NzEgNC41Nzg5OCAxNS43NTM2IDQuNDk5MDIgMTYgNC40OTkwMkMxNi4yNDY0IDQuNDk5MDIgMTYuNDEyOSA0LjU3ODk4IDE2LjUxNjUgNC42ODI2QzE2LjYyMDEgNC43ODYyMyAxNi43MDAxIDQuOTUyNzEgMTYuNzAwMSA1LjE5OTEyVjE4LjY0MDJaIgogICAgZmlsbD0iIzBCMEMwRSIgc3Ryb2tlPSIjMEIwQzBFIiAvPgo8L3N2Zz4=)## Asset Management

Handles and optimizes static assets like images, fonts and stylesheets.

](/guide/features/asset-module)[![1](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICA8cGF0aAogICAgZD0iTTI3LjQzMDQgMTQuODcwOUwyNy40MzA0IDE0Ljg3MDlMMjcuNDMxIDE0Ljg3NjRDMjguMTI1NCAyMS4yMTAxIDIzLjQ5NjggMjYuODU0MyAxNy4xMjc0IDI3LjQzMDRMMTcuMTI3NCAyNy40MzAzTDE3LjExNzUgMjcuNDMxNEMxMS4wNTU5IDI4LjEwMTUgNS41MjY4MSAyMy43ODMgNC41NzExMSAxNy43MjY3SDE1LjQ3NzdMMTMuNTU2OSAxOS42Mzc5QzEyLjg3NzEgMjAuMzE0MyAxMi44NzcxIDIxLjM1MzcgMTMuNTU2OSAyMi4wMzAyQzE0LjIzNTQgMjIuNzA1MiAxNS4yNzU3IDIyLjcwNTIgMTUuOTU0MSAyMi4wMzAyTDIwLjc4ODEgMTcuMjIwNEMyMS40Njc5IDE2LjU0NCAyMS40Njc5IDE1LjUwNDYgMjAuNzg4MSAxNC44MjgyTDE1Ljk1NDEgMTAuMDE4NEMxNS4yNzU3IDkuMzQzMzkgMTQuMjM1NCA5LjM0MzM5IDEzLjU1NjkgMTAuMDE4NEMxMi44NzcxIDEwLjY5NDkgMTIuODc3MSAxMS43MzQzIDEzLjU1NjkgMTIuNDEwN0wxNS40Nzc3IDE0LjMyMTlINC41NjVDNS4zOTAwMyA4LjcxNzg0IDEwLjI0MjEgNC41IDE1Ljk2NCA0LjVDMjEuODcxMyA0LjUgMjYuODUxNSA4Ljk5NTYgMjcuNDMwNCAxNC44NzA5WiIKICAgIGZpbGw9IiMwQjBDMEUiIHN0cm9rZT0iIzBCMEMwRSIgLz4KPC9zdmc+)## Loaders

Fully compatible with webpack loaders, reusing the entire ecosystem.

](/guide/features/loader)[![2](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICA8cGF0aAogICAgZD0iTTguMDU1NzYgNy42MTA0OUMxMS43NDM5IDQuMjY4MTIgMTcuMjY5NCAzLjQ2NzEzIDIxLjc1MTYgNS45OTM5NUMyNS4zMTU2IDguMDY0NjIgMjcuNSAxMS44NTg4IDI3LjUgMTZDMjcuNSAxNi4yNDY0IDI3LjQyMDEgMTYuNDEyOCAyNy4zMTY0IDE2LjUxNjRDMjcuMjEyOCAxNi42MjAxIDI3LjA0NjQgMTYuNyAyNi44IDE2LjdDMjYuNTUzNiAxNi43IDI2LjM4NzIgMTYuNjIwMSAyNi4yODM2IDE2LjUxNjRDMjYuMTc5OSAxNi40MTI4IDI2LjEgMTYuMjQ2NCAyNi4xIDE2QzI2LjEgMTAuNDQzOSAyMS41NTYxIDUuOSAxNiA1LjlDMTMuMjIzNSA1LjkgMTAuNTcwOSA3LjAzNTkzIDguNjc1MjMgOS4wNTgwM0w3Ljg4NTg4IDkuOUg5LjA0SDExLjkyQzEyLjE2NjQgOS45IDEyLjMzMjggOS45Nzk5NCAxMi40MzY0IDEwLjA4MzZDMTIuNTQwMSAxMC4xODcyIDEyLjYyIDEwLjM1MzYgMTIuNjIgMTAuNkMxMi42MiAxMC44NDY0IDEyLjU0MDEgMTEuMDEyOCAxMi40MzY0IDExLjExNjRDMTIuMzMyOCAxMS4yMjAxIDEyLjE2NjQgMTEuMyAxMS45MiAxMS4zSDYuNTJDNi4yNzM2MiAxMS4zIDYuMTA3MTYgMTEuMjIwMSA2LjAwMzU1IDExLjExNjRDNS44OTk5NCAxMS4wMTI4IDUuODIgMTAuODQ2NCA1LjgyIDEwLjZWNS4yQzUuODIgNC45NTM2MiA1Ljg5OTk0IDQuNzg3MTYgNi4wMDM1NSA0LjY4MzU1QzYuMTA3MTYgNC41Nzk5NCA2LjI3MzYyIDQuNSA2LjUyIDQuNUM2Ljc2NjM4IDQuNSA2LjkzMjg0IDQuNTc5OTQgNy4wMzY0NSA0LjY4MzU1QzcuMTQwMDYgNC43ODcxNiA3LjIyIDQuOTUzNjIgNy4yMiA1LjJWNy4yNFY4LjM2NzlMOC4wNTU3NiA3LjYxMDQ5Wk0yMy4zMjQ4IDIyLjk0MkwyNC4xMTQxIDIyLjFIMjIuOTZIMjAuMDhDMTkuODMzNiAyMi4xIDE5LjY2NzIgMjIuMDIwMSAxOS41NjM2IDIxLjkxNjRDMTkuNDU5OSAyMS44MTI4IDE5LjM4IDIxLjY0NjQgMTkuMzggMjEuNEMxOS4zOCAyMS4xNTM2IDE5LjQ1OTkgMjAuOTg3MiAxOS41NjM2IDIwLjg4MzZDMTkuNjY3MiAyMC43Nzk5IDE5LjgzMzYgMjAuNyAyMC4wOCAyMC43SDI1LjQ4QzI1LjgzNjkgMjAuNyAyNi4xOCAyMC45ODgxIDI2LjE4IDIxLjRWMjYuOEMyNi4xOCAyNy4wNDY0IDI2LjEwMDEgMjcuMjEyOCAyNS45OTY0IDI3LjMxNjRDMjUuODkyOCAyNy40MjAxIDI1LjcyNjQgMjcuNSAyNS40OCAyNy41QzI1LjIzMzYgMjcuNSAyNS4wNjcyIDI3LjQyMDEgMjQuOTYzNiAyNy4zMTY0QzI0Ljg1OTkgMjcuMjEyOCAyNC43OCAyNy4wNDY0IDI0Ljc4IDI2LjhWMjQuNjRWMjMuNDc3NkwyMy45MzYxIDI0LjI3N0MyMS43NDQ0IDI2LjM1MzQgMTguOTg1OSAyNy41IDE2IDI3LjVDOS42NzYxNCAyNy41IDQuNSAyMi4zMjM5IDQuNSAxNkM0LjUgMTUuNzUzNiA0LjU3OTk0IDE1LjU4NzIgNC42ODM1NSAxNS40ODM2QzQuNzg3MTYgMTUuMzc5OSA0Ljk1MzYyIDE1LjMgNS4yIDE1LjNDNS40NDYzOCAxNS4zIDUuNjEyODQgMTUuMzc5OSA1LjcxNjQ1IDE1LjQ4MzZDNS44MjAwNiAxNS41ODcyIDUuOSAxNS43NTM2IDUuOSAxNkM1LjkgMjEuNTU2MSAxMC40NDM5IDI2LjEgMTYgMjYuMUMxOC43NzY1IDI2LjEgMjEuNDI5MSAyNC45NjQxIDIzLjMyNDggMjIuOTQyWk0xNiAxMi45QzE3Ljc2MzkgMTIuOSAxOS4xIDE0LjIzNjEgMTkuMSAxNkMxOS4xIDE3Ljc2MzkgMTcuNzYzOSAxOS4xIDE2IDE5LjFDMTQuMjM2MSAxOS4xIDEyLjkgMTcuNzYzOSAxMi45IDE2QzEyLjkgMTQuMjM2MSAxNC4yMzYxIDEyLjkgMTYgMTIuOVoiCiAgICBmaWxsPSIjMEIwQzBFIiBzdHJva2U9IiMwQjBDMEUiIC8+Cjwvc3ZnPg==)## HMR

Hot updating of modules at runtime without the need for a full refresh.

](/api/runtime-api/hmr)[![3](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICA8cGF0aAogICAgZD0iTTI3LjM5MzEgMTguNzYwNUwyNy40MDU3IDE4Ljc5ODFDMjcuNDk4MSAxOS4wNzUzIDI3LjUgMTkuMjQ0NiAyNy41IDE5LjZWMjQuNEMyNy41IDI2LjE2MzkgMjYuMTYzOSAyNy41IDI0LjQgMjcuNUg3LjZDNS44MzYxNCAyNy41IDQuNSAyNi4xNjM5IDQuNSAyNC40VjE5LjZDNC41IDE5LjI0NDYgNC41MDE5NCAxOS4wNzUzIDQuNTk0MzQgMTguNzk4MUw0LjYwNjg4IDE4Ljc2MDVMNC42MTMzMyAxOC43MjE0TDYuNTMxMzMgNy4wOTM1MkM2Ljg1MTE1IDUuNjI1MDEgOC4xMDM5MSA0LjUgOS42NCA0LjVIMjIuMzZDMjMuOTI2NyA0LjUgMjUuMjYyNCA1LjY1MjExIDI1LjQ2NSA3LjA3MDcxTDI1LjQ2NDkgNy4wNzA3M0wyNS40NjY3IDcuMDgxMzdMMjcuMzg2NyAxOC43MjE0TDI3LjM5MzEgMTguNzYwNVpNNi4yODY0NSAxOC42NDY0TDYuMTQgMTguNzkyOVYxOC44NjYxQzYuMTI5ODYgMTguODgwMiA2LjExOTY4IDE4Ljg5NTQgNi4xMSAxOC45MTE1QzYuMDkxMjUgMTguOTQyOCA2LjA3NTA3IDE4Ljk3NTggNi4wNjE4MiAxOS4wMTA1QzUuODk5MjkgMTkuMjQxNiA1Ljg5OTc2IDE5LjQ3NDcgNS44OTk5OCAxOS41ODgzQzUuODk5OTkgMTkuNTkyMyA1LjkgMTkuNTk2MiA1LjkgMTkuNlYyNC40QzUuOSAyNC44NzM2IDYuMDYwMDYgMjUuMzA3MiA2LjM3NjQ1IDI1LjYyMzZDNi42OTI4NCAyNS45Mzk5IDcuMTI2MzggMjYuMSA3LjYgMjYuMUgyNC40QzI0Ljg3MzYgMjYuMSAyNS4zMDcyIDI1LjkzOTkgMjUuNjIzNiAyNS42MjM2QzI1LjkzOTkgMjUuMzA3MiAyNi4xIDI0Ljg3MzYgMjYuMSAyNC40VjE5LjcyQzI2LjEgMTkuNjA4MSAyNi4wNzIzIDE5LjUxNTUgMjYuMDQ5NCAxOS40NTQ0QzI2LjAyODcgMTkuMzk5MSAyNi4wMDMxIDE5LjM0ODIgMjUuOTg5NyAxOS4zMjEzTDI1Ljk4NzIgMTkuMzE2NEMyNS45ODI5IDE5LjMwNzkgMjUuOTc5NiAxOS4zMDEyIDI1Ljk3NjkgMTkuMjk1N0MyNS45Njc0IDE5LjE5ODQgMjUuOTM2NyAxOS4xMDk0IDI1Ljg5IDE5LjAzMTVDMjUuODcyOSAxOS4wMDMxIDI1Ljg1NDMgMTguOTc3NiAyNS44MzcxIDE4Ljk1NjFMMjUuODA3MiAxOC44OTY0QzI1LjczMjEgMTguNzQ2MiAyNS42NDM1IDE4LjYwNjQgMjUuNTE4NiAxOC40ODE0QzI1LjQ0MjEgMTguNDA1IDI1LjM2IDE4LjM0MjEgMjUuMjczNSAxOC4yODc2QzI1LjIwNDIgMTguMTg2MiAyNS4xMTY2IDE4LjEyNDMgMjUuMDQzNiAxOC4wODc4QzI1LjAyNzQgMTguMDc5NyAyNS4wMTE1IDE4LjA3MjYgMjQuOTk2IDE4LjA2NjRDMjQuNzYyNyAxNy44OTkzIDI0LjUyNjMgMTcuODk5OCAyNC40MTE3IDE3LjlDMjQuNDA3NyAxNy45IDI0LjQwMzggMTcuOSAyNC40IDE3LjlINy42QzcuNDg4MDkgMTcuOSA3LjM5NTUgMTcuOTI3NyA3LjMzNDQ0IDE3Ljk1MDZDNy4yNzkwOCAxNy45NzEzIDcuMjI4MjEgMTcuOTk2OCA3LjIwMTMxIDE4LjAxMDNMNy4xOTYzOSAxOC4wMTI4QzcuMTkwODUgMTguMDE1NiA3LjE4NjEgMTguMDE3OSA3LjE4MTkzIDE4LjAySDYuNzRWMTguMjQ4MkM2LjcwMDAzIDE4LjI3MTYgNi42NjY0OCAxOC4yOTUxIDYuNjQgMTguMzE1QzYuNTUwODQgMTguMzgxOSA2LjQ2ODc3IDE4LjQ2NCA2LjQxNDk0IDE4LjUxOEM2LjQxMjAyIDE4LjUyMDkgNi40MDkxOSAxOC41MjM3IDYuNDA2NDUgMTguNTI2NEw2LjI4NjQ1IDE4LjY0NjRaTTYuMjMwNzUgMTguNzYyMUM2LjIzMjY2IDE4Ljc2IDYuMjMzNzggMTguNzU4OCA2LjIzMzgzIDE4Ljc1ODhDNi4yMzM4OCAxOC43NTg4IDYuMjMyOTQgMTguNzU5OCA2LjIzMDc1IDE4Ljc2MjFaTTI1Ljc2NjIgMTguODc4OEMyNS43NjYzIDE4Ljg3ODkgMjUuNzY3NCAxOC44OCAyNS43NjkzIDE4Ljg4MjFDMjUuNzY3IDE4Ljg3OTggMjUuNzY2MSAxOC44Nzg3IDI1Ljc2NjIgMTguODc4OFpNMjEuMyAyMkMyMS4zIDIxLjc1MzYgMjEuMzc5OSAyMS41ODcyIDIxLjQ4MzYgMjEuNDgzNkMyMS41ODcyIDIxLjM3OTkgMjEuNzUzNiAyMS4zIDIyIDIxLjNDMjIuMjQ2NCAyMS4zIDIyLjQxMjggMjEuMzc5OSAyMi41MTY0IDIxLjQ4MzZDMjIuNjIwMSAyMS41ODcyIDIyLjcgMjEuNzUzNiAyMi43IDIyQzIyLjcgMjIuMjQ2NCAyMi42MjAxIDIyLjQxMjggMjIuNTE2NCAyMi41MTY0QzIyLjQxMjggMjIuNjIwMSAyMi4yNDY0IDIyLjcgMjIgMjIuN0MyMS43NTM2IDIyLjcgMjEuNTg3MiAyMi42MjAxIDIxLjQ4MzYgMjIuNTE2NEMyMS4zNzk5IDIyLjQxMjggMjEuMyAyMi4yNDY0IDIxLjMgMjJaIgogICAgZmlsbD0iIzBCMEMwRSIgc3Ryb2tlPSIjMEIwQzBFIiAvPgo8L3N2Zz4=)## Dev Server

Provides a mature, high-performance dev server for local development.

](/guide/features/dev-server)

[![0](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNiIgaGVpZ2h0PSIzMCIgdmlld0JveD0iMCAwIDI2IDMwIiBmaWxsPSJub25lIj4KICA8cGF0aAogICAgZD0iTTQuNjY5MTYgMjIuNzIyMkg1LjE2OTE2VjIyLjIyMjJWMS42NjY2N0M1LjE2OTE2IDEuMDIwNTkgNS42ODk3NSAwLjUgNi4zMzU4MyAwLjVDNi45ODE5MSAwLjUgNy41MDI1IDEuMDIwNTkgNy41MDI1IDEuNjY2NjdWMjIuMjIyMlYyMi43MjIySDguMDAyNUgxMC43ODAzQzExLjI1NTQgMjIuNzIyMiAxMS42ODM3IDIzLjAxMSAxMS44NjIyIDIzLjQ0NTVDMTIuMDQwNSAyMy44Nzk2IDExLjk0MDggMjQuMzc2OCAxMS42MDQ1IDI0LjcxMzFMNy4xNjAwNiAyOS4xNTc2QzcuMDcwMzMgMjkuMjQ3MyA2Ljk3MjM1IDI5LjMyIDYuODU5NCAyOS4zNzc4SDYuODQ4MDNMNi43NTY1NyAyOS40MTU0QzYuNjIzMzYgMjkuNDcwMyA2LjQ4Nzg0IDI5LjUgNi4zMzU4MyAyOS41QzYuMTgzODIgMjkuNSA2LjA0ODMgMjkuNDcwMyA1LjkxNTA5IDI5LjQxNTRMNS44MjM2MyAyOS4zNzc4SDUuODE2NDhDNS43MDAwNCAyOS4zMTY2IDUuNTk2MzMgMjkuMjQyMyA1LjUxMTYgMjkuMTU3NkwxLjA2NzE2IDI0LjcxMzFMMS4wNjcxOSAyNC43MTMxTDEuMDYyOTggMjQuNzA5QzAuNzI4ODM2IDI0LjM4MjYgMC42MjM0OTggMjMuODc5NiAwLjgwNjUxNCAyMy40NTI1QzAuOTk3NTAyIDIzLjAwNjkgMS40MjE0IDIyLjcyMjIgMS44OTEzOSAyMi43MjIySDQuNjY5MTZaTTI0LjkzNzggNS4yODY4OUwyNC45Mzc4IDUuMjg2OTFMMjQuOTQyIDUuMjkxMDJDMjUuMjcwNCA1LjYxMTgxIDI1LjM3NDUgNi4xMTQ2NiAyNS4xOTcgNi41NTA5OUMyNS4wMDUzIDYuOTk0NjIgMjQuNTgyNCA3LjI3Nzc4IDI0LjExMzYgNy4yNzc3OEgyMS4zMzU4SDIwLjgzNThWNy43Nzc3OFYyOC4zMzMzQzIwLjgzNTggMjguOTc5NCAyMC4zMTUyIDI5LjUgMTkuNjY5MiAyOS41QzE5LjAyMzEgMjkuNSAxOC41MDI1IDI4Ljk3OTQgMTguNTAyNSAyOC4zMzMzVjcuNzc3NzhWNy4yNzc3OEgxOC4wMDI1SDE1LjIyNDdDMTQuNzQ5NiA3LjI3Nzc4IDE0LjMyMTMgNi45ODkwMSAxNC4xNDI4IDYuNTU0NDhDMTMuOTY0NSA2LjEyMDM3IDE0LjA2NDEgNS42MjMyNCAxNC40MDA1IDUuMjg2ODlMMTguODQ0OSAwLjg0MjQ0MkMxOC45MzQ3IDAuNzUyNzE2IDE5LjAzMjYgMC42ODAwMjQgMTkuMTQ1NiAwLjYyMjIyMkgxOS4xNTdMMTkuMjQ4NCAwLjU4NDU2MUMxOS4zODE2IDAuNTI5NzExIDE5LjUxNzIgMC41IDE5LjY2OTIgMC41QzE5LjgyMTIgMC41IDE5Ljk1NjcgMC41Mjk3MTEgMjAuMDg5OSAwLjU4NDU2MUwyMC4xODE0IDAuNjIyMjIySDIwLjE4ODVDMjAuMzA0OSAwLjY4MzM1OCAyMC40MDg3IDAuNzU3NzE0IDIwLjQ5MzQgMC44NDI0NDJMMjQuOTM3OCA1LjI4Njg5WiIKICAgIGZpbGw9IiMwQjBDMEUiIHN0cm9rZT0iIzBCMEMwRSIgLz4KPC9zdmc+)## Parallel Builds

Run multiple builds in parallel for different build targets or environments.

](/api/javascript-api/#multicompiler)[![1](/static/svg/swc.36b5f8b0b1.svg)## SWC

Utilizes the Rust-based SWC for faster JavaScript and TypeScript transpilation.

](/guide/features/builtin-swc-loader)[![2](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICA8cGF0aAogICAgZD0iTTE2Ljk2MTQgMTEuNTcxNEwxNi43NjgzIDEyLjIxNTFIMTcuNDQwM0gyMi40Mjg2QzIyLjYzMTkgMTIuMjE1MSAyMi44MTk2IDEyLjMyMjkgMjIuOTIxOCAxMi40OTc4QzIzLjAyNDQgMTIuNjczMyAyMy4wMjYyIDEyLjg4OTggMjIuOTI2OCAxMy4wNjY0TDIyLjkyNjYgMTMuMDY2NUwxMy4yODM4IDMwLjIwODZDMTMuMTgwMyAzMC4zOTI2IDEyLjk4NzUgMzAuNSAxMi43ODUyIDMwLjVDMTIuNzE3NiAzMC41IDEyLjY0NzUgMzAuNDg3NyAxMi41Nzg4IDMwLjQ2MTRDMTIuMzE0IDMwLjM1ODYgMTIuMTY0OCAzMC4wNzcgMTIuMjI4NyAyOS43OTk5QzEyLjIyODcgMjkuNzk5OSAxMi4yMjg3IDI5Ljc5OTkgMTIuMjI4NyAyOS43OTk4TDE1LjE0MDYgMTcuMTg0NUwxNS4yODIgMTYuNTcySDE0LjY1MzRIOS41NzE0NEM5LjM1ODc1IDE2LjU3MiA5LjE2Mzg2IDE2LjQ1MzkgOS4wNjU1IDE2LjI2NTlMOS4wNjUwOSAxNi4yNjUxQzguOTY2ODYgMTYuMDc4MSA4Ljk4MDQyIDE1Ljg1MDggOS4xMDE3MiAxNS42NzVDOS4xMDE3NyAxNS42NzQ5IDkuMTAxODIgMTUuNjc0OCA5LjEwMTg3IDE1LjY3NDhMMTguNzQ0NCAxLjc0NzI3TDE4Ljc0NDYgMS43NDY5NUMxOC45MDUyIDEuNTE0NjIgMTkuMjA3NyAxLjQzNDU3IDE5LjQ2MDYgMS41NTcyOUwxOS40NjI0IDEuNTU4MTZDMTkuNzE1MyAxLjY3OTU2IDE5Ljg0MjQgMS45Njc1OCAxOS43NjE4IDIuMjM2NTRDMTkuNzYxOCAyLjIzNjU3IDE5Ljc2MTggMi4yMzY2IDE5Ljc2MTggMi4yMzY2M0wxNi45NjE0IDExLjU3MTRaIgogICAgZmlsbD0iIzBCMEMwRSIgc3Ryb2tlPSIjMEIwQzBFIiAvPgo8L3N2Zz4=)## Lightning CSS

Integrate Lightning CSS for fast CSS processing and advanced optimizations.

](/plugins/lightning-css-minimizer-rspack-plugin)[![3](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KICA8cGF0aAogICAgZD0iTTYuOSA3Ljk1TDYgNy4wNUgxNkMxOC43IDcuMDUgMjEuMjUgOC4yNSAyMi45NSAxMC4zNUwyMy43NSA5LjdDMjEuODUgNy4zNSAxOS4wNSA2IDE2IDZINkw2LjkgNS4xTDYuMTUgNC40TDQgNi41NUw2LjE1IDguN0w2LjkgNy45NVpNMjUuODUgMjMuM0wyNS4xIDI0LjA1TDI2IDI0Ljk1SDE2QzEzLjMgMjQuOTUgMTAuNzUgMjMuNzUgOS4wNSAyMS42NUw4LjI1IDIyLjNDMTAuMTUgMjQuNjUgMTIuOTUgMjYgMTYgMjZIMjZMMjUuMSAyNi45TDI1Ljg1IDI3LjY1TDI4IDI1LjVMMjUuODUgMjMuM1oiCiAgICBmaWxsPSIjMEIwQzBFIiAvPgogIDxwYXRoCiAgICBkPSJNMjQuOTUgNlYxNkMyNC45NSAxOC43IDIzLjc1IDIxLjI1IDIxLjY1IDIyLjk1TDIyLjMgMjMuNzVDMjQuNjUgMjEuODUgMjYgMTkuMDUgMjYgMTZWNkwyNi45IDYuOUwyNy42NSA2LjE1TDI1LjQ1IDRMMjMuMyA2LjE1TDI0LjA1IDYuOUwyNC45NSA2Wk03LjA1IDI2VjE2QzcuMDUgMTMuMyA4LjI1IDEwLjc1IDEwLjM1IDkuMDVMOS43IDguMjVDNy4zNSAxMC4xNSA2IDEyLjk1IDYgMTZWMjZMNS4xIDI1LjFMNC4zNSAyNS44NUw2LjU1IDI4TDguNyAyNS44NUw3Ljk1IDI1LjFMNy4wNSAyNlpNMTAuMiAxNS43TDEyLjI1IDE2Ljc1VjE0LjNMMTAuMiAxMy4yNVYxNS43Wk0xNS40NSAxMy4yNUwxMy40IDE0LjNWMTYuNzVMMTUuNDUgMTUuN1YxMy4yNVpNMTQuNzUgMTIuM0wxMi44NSAxMS4zTDEwLjkgMTIuM0wxMi44NSAxMy4zTDE0Ljc1IDEyLjNaTTE1LjQ1IDE5LjdMMTMuNCAxOC42NVYyMS4xTDE1LjQ1IDIyLjE1VjE5LjdaTTIxLjggMTMuMjVMMTkuNzUgMTQuM1YxNi43NUwyMS44IDE1LjdWMTMuMjVaTTIxLjEgMTIuM0wxOS4xNSAxMS4zTDE3LjI1IDEyLjNMMTkuMTUgMTMuM0wyMS4xIDEyLjNaTTE4LjYgMTQuM0wxNi41NSAxMy4yNVYxNS43TDE4LjYgMTYuNzVWMTQuM1pNMTcuOTUgMTcuN0wxNiAxNi43TDE0LjA1IDE3LjdMMTYgMTguN0wxNy45NSAxNy43Wk0xOC42IDE4LjY1TDE2LjU1IDE5LjdWMjIuMTVMMTguNiAyMS4xVjE4LjY1WiIKICAgIGZpbGw9IiMwQjBDMEUiIC8+CiAgPHBhdGgKICAgIGQ9Ik02LjkgNy45NUw2IDcuMDVIMTZDMTguNyA3LjA1IDIxLjI1IDguMjUgMjIuOTUgMTAuMzVMMjMuNzUgOS43QzIxLjg1IDcuMzUgMTkuMDUgNiAxNiA2SDZMNi45IDUuMUw2LjE1IDQuNEw0IDYuNTVMNi4xNSA4LjdMNi45IDcuOTVaTTI1Ljg1IDIzLjNMMjUuMSAyNC4wNUwyNiAyNC45NUgxNkMxMy4zIDI0Ljk1IDEwLjc1IDIzLjc1IDkuMDUgMjEuNjVMOC4yNSAyMi4zQzEwLjE1IDI0LjY1IDEyLjk1IDI2IDE2IDI2SDI2TDI1LjEgMjYuOUwyNS44NSAyNy42NUwyOCAyNS41TDI1Ljg1IDIzLjNaIgogICAgc3Ryb2tlPSIjMEIwQzBFIiBzdHJva2Utd2lkdGg9IjAuNSIgLz4KICA8cGF0aAogICAgZD0iTTI0Ljk1IDZWMTZDMjQuOTUgMTguNyAyMy43NSAyMS4yNSAyMS42NSAyMi45NUwyMi4zIDIzLjc1QzI0LjY1IDIxLjg1IDI2IDE5LjA1IDI2IDE2VjZMMjYuOSA2LjlMMjcuNjUgNi4xNUwyNS40NSA0TDIzLjMgNi4xNUwyNC4wNSA2LjlMMjQuOTUgNlpNNy4wNSAyNlYxNkM3LjA1IDEzLjMgOC4yNSAxMC43NSAxMC4zNSA5LjA1TDkuNyA4LjI1QzcuMzUgMTAuMTUgNiAxMi45NSA2IDE2VjI2TDUuMSAyNS4xTDQuMzUgMjUuODVMNi41NSAyOEw4LjcgMjUuODVMNy45NSAyNS4xTDcuMDUgMjZaTTEwLjIgMTUuN0wxMi4yNSAxNi43NVYxNC4zTDEwLjIgMTMuMjVWMTUuN1pNMTUuNDUgMTMuMjVMMTMuNCAxNC4zVjE2Ljc1TDE1LjQ1IDE1LjdWMTMuMjVaTTE0Ljc1IDEyLjNMMTIuODUgMTEuM0wxMC45IDEyLjNMMTIuODUgMTMuM0wxNC43NSAxMi4zWk0xNS40NSAxOS43TDEzLjQgMTguNjVWMjEuMUwxNS40NSAyMi4xNVYxOS43Wk0yMS44IDEzLjI1TDE5Ljc1IDE0LjNWMTYuNzVMMjEuOCAxNS43VjEzLjI1Wk0yMS4xIDEyLjNMMTkuMTUgMTEuM0wxNy4yNSAxMi4zTDE5LjE1IDEzLjNMMjEuMSAxMi4zWk0xOC42IDE0LjNMMTYuNTUgMTMuMjVWMTUuN0wxOC42IDE2Ljc1VjE0LjNaTTE3Ljk1IDE3LjdMMTYgMTYuN0wxNC4wNSAxNy43TDE2IDE4LjdMMTcuOTUgMTcuN1pNMTguNiAxOC42NUwxNi41NSAxOS43VjIyLjE1TDE4LjYgMjEuMVYxOC42NVoiCiAgICBzdHJva2U9IiMwQjBDMEUiIHN0cm9rZS13aWR0aD0iMC41IiAvPgo8L3N2Zz4=)## JavaScript API

Provides programmatic access to the build API to customize the build processes.

](/api/javascript-api/)

# Rstack

The fast, unified JavaScript toolchain for developers and agents

[![Rspack](https://assets.rspack.rs/rspack/rspack-logo.svg)RspackA fast Rust-based bundler for the web, with a modernized webpack API

rspack.rs](https://rspack.rs)[![Rsbuild](https://assets.rspack.rs/rsbuild/rsbuild-logo.svg)RsbuildA fast, extensible build tool for modern web development, powered by Rspack

rsbuild.rs](https://rsbuild.rs)[![Rslib](https://assets.rspack.rs/rslib/rslib-logo.svg)RslibAn Rsbuild-based library development tool for creating libraries and UI components

rslib.rs](https://rslib.rs)[![Rspress](https://assets.rspack.rs/rspress/rspress-logo-480x480.png)RspressAn Rsbuild-based static site generator for creating documentation sites

rspress.rs](https://rspress.rs)[![Rsdoctor](https://assets.rspack.rs/rsdoctor/rsdoctor-logo-480x480.png)RsdoctorAn AI-friendly build analyzer that makes the build process transparent

rsdoctor.rs](https://rsdoctor.rs)[![Rstest](https://assets.rspack.rs/rstest/rstest-logo.svg)RstestA JavaScript testing framework powered by Rspack, with a Jest-compatible API

rstest.rs](https://rstest.rs/)[![Rslint](https://assets.rspack.rs/rslint/rslint-logo.svg)RslintA high-performance, ESLint-compatible linter for JavaScript and TypeScript

rslint.rs](https://rslint.rs/)

## Trusted By Innovators

[![Microsoft](/static/svg/microsoft.063aca0f2a.svg)](https://www.microsoft.com)[![Amazon](/static/svg/amazon.6fba21b2c9.svg)](https://amazon.com/)[![ByteDance](/static/svg/bytedance.680c2fd62d.svg)](https://www.bytedance.com)[![TikTok](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNDAwIDEwMDAiPjxkZWZzPjxzdHlsZT4uY2xzLTF7ZmlsbDpibGFjazt9PC9zdHlsZT48L2RlZnM+PGcgaWQ9IkxPR09TIj48cGF0aCBjbGFzcz0iY2xzLTEiIGQ9Ik02NDAuOTIsMzc0Ljg2YTk4LjU2LDk4LjU2LDAsMCwxLTQ0Ljg2LTgyLjU1aC03MC44bC0uMTIsMjgzLjc2YTU5LjQ4LDU5LjQ4LDAsMSwxLTU5LjQtNjEuNzYsNTguNjUsNTguNjUsMCwwLDEsMTcuNTYsMi43NVY0NDQuNzhhMTMwLjQxLDEzMC40MSwwLDAsMC0xNy41Ni0xLjI4Yy03MS44NiwwLTEzMC4zMiw1OC40Ny0xMzAuMzIsMTMwLjMzYTEzMC4zMiwxMzAuMzIsMCwxLDAsMjYwLjY0LDBWNDI5Ljk0YTE2OC40MSwxNjguNDEsMCwwLDAsOTguNTEsMzEuNjhWMzkwLjgxQTk3Ljk0LDk3Ljk0LDAsMCwxLDY0MC45MiwzNzQuODZaIi8+PHBhdGggY2xhc3M9ImNscy0xIiBkPSJNNzYyLjE5LDM5MS4xNkg5ODUuNDZMOTY1LDQ1NSw5MDcsNDU1VjY5MS4xOEg4MzQuODZWNDU1bC03Mi42Mi4xNFoiLz48cGF0aCBjbGFzcz0iY2xzLTEiIGQ9Ik0xMzUxLjIsMzkxLjE2aDIyOC40M0wxNTU5LjEzLDQ1NWwtNjMsMFY2OTEuMThoLTcyLjI4VjQ1NWwtNzIuNjIuMTRaIi8+PHBvbHlnb24gY2xhc3M9ImNscy0xIiBwb2ludHM9Ijk5OS4wNyA0ODYuNTkgMTA3MC42NiA0ODYuNTkgMTA3MC41OCA2OTEuMTggOTk5LjUgNjkxLjE4IDk5OS4wNyA0ODYuNTkiLz48cGF0aCBjbGFzcz0iY2xzLTEiIGQ9Ik0xMDk5LDM5MC4zMmg3MS41MVY1MzBsNzAuODYtNjkuNTRoODUuMzVsLTg5LjYzLDg3LDEwMC4zOSwxNDMuNjloLTc4Ljc4bC02Ny05OS42NS0yMS4xOSwyMC42MXY3OUgxMDk5WiIvPjxwYXRoIGNsYXNzPSJjbHMtMSIgZD0iTTE4MjYuMSwzOTAuMzJoNzEuNTFWNTMwbDcwLjg2LTY5LjU0aDg1LjM1bC04OS42Myw4NywxMDAuMzksMTQzLjY5SDE5ODUuOGwtNjctOTkuNjUtMjEuMTksMjAuNjF2NzlIMTgyNi4xWiIvPjxjaXJjbGUgY2xhc3M9ImNscy0xIiBjeD0iMTAzNC44NCIgY3k9IjQyNy4xOCIgcj0iMzYuMDMiLz48cGF0aCBjbGFzcz0iY2xzLTEiIGQ9Ik0xNjc0LjU3LDQ0Ni4yNEExMjIuNDcsMTIyLjQ3LDAsMSwwLDE3OTcsNTY4LjcxLDEyMi40NywxMjIuNDcsMCwwLDAsMTY3NC41Nyw0NDYuMjRabTAsMTgyYTU5LjU0LDU5LjU0LDAsMSwxLDU5LjUzLTU5LjUzQTU5LjU0LDU5LjU0LDAsMCwxLDE2NzQuNTcsNjI4LjI0WiIvPjwvZz48L3N2Zz4=)](https://www.tiktok.com)[![Google](data:image/svg+xml;base64,PHN2ZyBoZWlnaHQ9IjMwIiB2aWV3Qm94PSIwIDAgOTIgMzAiIHdpZHRoPSI5MiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMzguOSAxNS41MWMwIDQuMjYtMy4zMiA3LjM5LTcuNCA3LjM5cy03LjQtMy4xNC03LjQtNy4zOWMwLTQuMjggMy4zMi03LjM5IDcuNC03LjM5czcuNCAzLjEgNy40IDcuMzl6bS0zLjI0IDBjMC0yLjY2LTEuOTMtNC40OC00LjE2LTQuNDgtMi4yMyAwLTQuMTYgMS44Mi00LjE2IDQuNDggMCAyLjYzIDEuOTMgNC40OCA0LjE2IDQuNDggMi4yMyAwIDQuMTYtMS44NSA0LjE2LTQuNDh6IiBmaWxsPSJibGFjayI+PC9wYXRoPjxwYXRoIGQ9Ik0xMS45NiAyMi45OEM1LjYzIDIyLjk4LjMxIDE3LjgzLjMxIDExLjVTNS42My4wMiAxMS45Ni4wMmMzLjUgMCA1Ljk5IDEuMzcgNy44NyAzLjE2TDE3LjYyIDUuNGMtMS4zNC0xLjI2LTMuMTYtMi4yNC01LjY2LTIuMjQtNC42MiAwLTguMjMgMy43Mi04LjIzIDguMzQgMCA0LjYyIDMuNjEgOC4zNCA4LjIzIDguMzQgMyAwIDQuNy0xLjIgNS43OS0yLjMuOS0uOSAxLjQ5LTIuMiAxLjc0LTQuMTdIMTJ2LTMuMTRoMTAuNTJjLjExLjU2LjE3IDEuMjMuMTcgMS45NiAwIDIuMzUtLjY0IDUuNDktMi43MiA3LjU2LTIuMDIgMi4xMS00LjU5IDMuMjMtOC4wMSAzLjIzeiIgZmlsbD0iYmxhY2siPjwvcGF0aD48cGF0aCBkPSJNNTQuOSAxNS41MWMwIDQuMjYtMy4zMiA3LjM5LTcuNCA3LjM5cy03LjQtMy4xNC03LjQtNy4zOWMwLTQuMjggMy4zMi03LjM5IDcuNC03LjM5czcuNCAzLjEgNy40IDcuMzl6bS0zLjI0IDBjMC0yLjY2LTEuOTMtNC40OC00LjE2LTQuNDgtMi4yMyAwLTQuMTYgMS44Mi00LjE2IDQuNDggMCAyLjYzIDEuOTMgNC40OCA0LjE2IDQuNDggMi4yMyAwIDQuMTYtMS44NSA0LjE2LTQuNDh6IiBmaWxsPSJibGFjayI+PC9wYXRoPjxwYXRoIGQ9Ik03MCA4LjU2djEzLjI3YzAgNS40Ni0zLjA1IDcuNy02Ljg2IDcuNy0zLjU4IDAtNS43NC0yLjQxLTYuNTUtNC4zN2wyLjgzLTEuMThjLjUgMS4yIDEuNzQgMi42MyAzLjcyIDIuNjMgMi40NCAwIDMuNzgtMS41MSAzLjc4LTQuMzR2LTEuMDZoLS4xMWMtLjczLjktMi4wNCAxLjY4LTMuODEgMS42OC0zLjcgMC03LTMuMjItNy03LjM2IDAtNC4xNyAzLjMtNy40MiA3LTcuNDIgMS43NiAwIDMuMDguNzggMy44MSAxLjY1aC4xMXYtMS4ySDcwem0tMi44NiA2Ljk3YzAtMi42LTEuNzQtNC41MS0zLjk1LTQuNTEtMi4yNCAwLTMuOTUgMS45LTMuOTUgNC41MSAwIDIuNTggMS43MSA0LjQ1IDMuOTUgNC40NSAyLjIyLjAxIDMuOTUtMS44NyAzLjk1LTQuNDV6IiBmaWxsPSJibGFjayI+PC9wYXRoPjxwYXRoIGQ9Ik03NSAxLjE3VjIyLjloLTNWMS4xN2gzeiIgZmlsbD0iYmxhY2siPjwvcGF0aD48cGF0aCBkPSJNODcuNSAxNy45NGwyLjQ4IDEuNjhjLS44IDEuMi0yLjczIDMuMjgtNi4wNiAzLjI4LTQuMTMgMC03LjIyLTMuMjUtNy4yMi03LjM5IDAtNC40IDMuMTEtNy4zOSA2Ljg2LTcuMzkgMy43OCAwIDUuNjIgMy4wNSA2LjIzIDQuN2wuMzEuODUtOS43MSA0LjA4Yy43NCAxLjQ4IDEuOSAyLjI0IDMuNTMgMi4yNHMyLjc2LS44MiAzLjU4LTIuMDV6bS03LjYzLTIuNjZsNi41LTIuNzRjLS4zNi0uOTItMS40My0xLjU3LTIuNy0xLjU3LTEuNjIgMC0zLjg4IDEuNDYtMy44IDQuMzF6IiBmaWxsPSJibGFjayI+PC9wYXRoPjwvc3ZnPg==)](https://google.com)[![GitHub](data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNDE2IiBoZWlnaHQ9Ijk1IiB2aWV3Qm94PSIwIDAgNDE2IDk1IiBmaWxsPSJub25lIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgo8ZyBjbGlwLXBhdGg9InVybCgjY2xpcDBfNzMwXzI3MTI4KSI+CjxwYXRoIGQ9Ik00MS42Mzk0IDY5LjM4NDhDMjkuMDA2NiA2Ny44NTM1IDIwLjEwNjIgNTguNzYxNyAyMC4xMDYyIDQ2Ljk5MDJDMjAuMTA2MiA0Mi4yMDUxIDIxLjgyODkgMzcuMDM3MSAyNC43IDMzLjU5MThDMjMuNDU1OCAzMC40MzM2IDIzLjY0NzIgMjMuNzM0NCAyNS4wODI4IDIwLjk1OUMyOC45MTA5IDIwLjQ4MDUgMzQuMDc4OSAyMi40OTAyIDM3LjE0MTQgMjUuMjY1NkM0MC43NzgxIDI0LjExNzIgNDQuNjA2MiAyMy41NDMgNDkuMjk1NyAyMy41NDNDNTMuOTg1MSAyMy41NDMgNTcuODEzMiAyNC4xMTcyIDYxLjI1ODUgMjUuMTY5OUM2NC4yMjUzIDIyLjQ5MDIgNjkuNDg5IDIwLjQ4MDUgNzMuMzE3MSAyMC45NTlDNzQuNjU3IDIzLjU0MyA3NC44NDg0IDMwLjI0MjIgNzMuNjA0MiAzMy40OTYxQzc2LjY2NjcgMzcuMTMyOCA3OC4yOTM3IDQyLjAxMzcgNzguMjkzNyA0Ni45OTAyQzc4LjI5MzcgNTguNzYxNyA2OS4zOTMzIDY3LjY2MjEgNTYuNTY5MSA2OS4yODkxQzU5LjgyMyA3MS4zOTQ1IDYyLjAyNDIgNzUuOTg4MyA2Mi4wMjQyIDgxLjI1Mkw2Mi4wMjQyIDkxLjIwNTFDNjIuMDI0MiA5NC4wNzYyIDY0LjQxNjcgOTUuNzAzMSA2Ny4yODc4IDk0LjU1NDdDODQuNjEwMSA4Ny45NTEyIDk4LjIgNzAuNjI4OSA5OC4yIDQ5LjE5MTRDOTguMiAyMi4xMDc0IDc2LjE4ODIgNi42OTUzOWUtMDcgNDkuMTA0MiA0LjMwOWUtMDdDMjIuMDIwMyAxLjkyMjYxZS0wNyAwLjE5OTk1MSAyMi4xMDc0IDAuMTk5OTUxIDQ5LjE5MTRDMC4xOTk5NTEgNzAuNDM3NSAxMy42OTQxIDg4LjA0NjkgMzEuODc3NyA5NC42NTA0QzM0LjQ2MTcgOTUuNjA3NCAzNi45NSA5My44ODQ4IDM2Ljk1IDkxLjMwMDhMMzYuOTUgODMuNjQ0NUMzNS42MTAxIDg0LjIxODggMzMuODg3NSA4NC42MDE2IDMyLjM1NjIgODQuNjAxNkMyNi4wMzk4IDg0LjYwMTYgMjIuMzA3NCA4MS4xNTYzIDE5LjYyNzcgNzQuNzQ0MUMxOC41NzUgNzIuMTYwMiAxNy40MjY1IDcwLjYyODkgMTUuMjI1MyA3MC4zNDE4QzE0LjA3NjkgNzAuMjQ2MSAxMy42OTQxIDY5Ljc2NzYgMTMuNjk0MSA2OS4xOTM0QzEzLjY5NDEgNjguMDQ0OSAxNS42MDgyIDY3LjE4MzYgMTcuNTIyMiA2Ny4xODM2QzIwLjI5NzYgNjcuMTgzNiAyMi42OTAyIDY4LjkwNjMgMjUuMTc4NSA3Mi40NDczQzI3LjA5MjUgNzUuMjIyNyAyOS4xMDIzIDc2LjQ2NjggMzEuNDk0OSA3Ni40NjY4QzMzLjg4NzUgNzYuNDY2OCAzNS40MTg3IDc1LjYwNTUgMzcuNjE5OSA3My40MDQzQzM5LjI0NjggNzEuNzc3MyA0MC40OTEgNzAuMzQxOCA0MS42Mzk0IDY5LjM4NDhaIiBmaWxsPSJibGFjayIvPgo8ZyBjbGlwLXBhdGg9InVybCgjY2xpcDFfNzMwXzI3MTI4KSI+CjxwYXRoIGQ9Ik0xODguOTM3IDgzLjAwNDVMMTg4LjkzNyAzMy4yODI3TDIwMi45MTUgMzMuMjgyN0wyMDIuOTE1IDgzLjAwNDVMMTg4LjkzNyA4My4wMDQ1Wk0yMzAuMDE2IDgzLjAwNDVDMjIwLjcyNyA4My4wMDQ1IDIxNy4wOTkgNzkuMDIzMiAyMTcuMDk5IDcwLjYxODNMMjE3LjA5OSA0NC45NjExTDIwOC4yNTIgNDQuOTYxMUwyMDguMjUyIDMzLjI4MjdMMjE3LjA5OSAzMy4yODI3TDIxNy4wOTkgMjMuMzczN0wyMzEuMDc4IDIwLjEwMDJMMjMxLjA3OCAzMy4yODI3TDI0MS40MjkgMzMuMjgyN0wyNDEuNDI5IDQ0Ljk2MTFMMjMxLjA3OCA0NC45NjExTDIzMS4wNzggNjcuNTIxN0MyMzEuMDc4IDcwLjI2NDQgMjMyLjMxNyA3MS4zMjYxIDIzNS4wNTkgNzEuMzI2MUwyNDEuNDI5IDcxLjMyNjFMMjQxLjQyOSA4My4wMDQ1TDIzMC4wMTYgODMuMDA0NVpNMzI3LjQ3IDgzLjg4OTJDMzE2LjU4OCA4My44ODkyIDMxMC42NiA3Ny44NzMxIDMxMC42NiA2Ni45MDI0TDMxMC42NiAzMy4yODI3TDMyNC43MjggMzMuMjgyN0wzMjQuNzI4IDYzLjE4NjZDMzI0LjcyOCA2OS4yOTEyIDMyNy40NyA3Mi42NTMyIDMzMi42OSA3Mi42NTMyQzMzOC43MDYgNzIuNjUzMiAzNDMuMzA3IDY3LjA3OTQgMzQzLjMwNyA1OS40NzA3TDM0My4zMDcgMzMuMjgyN0wzNTcuMzc0IDMzLjI4MjdMMzU3LjM3NCA4My4wMDQ1TDM0My4zMDcgODMuMDA0NUwzNDMuMzA3IDc0LjU5OTZDMzQwLjY1MyA3OS45OTY0IDMzNC4yODMgODMuODg5MiAzMjcuNDcgODMuODg5MlpNMzk0LjYxMyA4My44ODkyQzM4Ny44MzIgODMuODg5MiAzODEuNjM5IDc5Ljk5NjQgMzc4LjY4NyA3NC40MjI2TDM3OC42ODcgODMuMDA0NUwzNjQuNzA5IDgzLjAwNDVMMzY0LjcwOSAxMy42NDE3TDM3OC43NzYgMTMuNjQxN0wzNzguNzc2IDQyLjM5NTRDMzgxLjYzOSAzNi4zNzkyIDM4OC4wOTggMzIuMTMyNSAzOTQuNjEzIDMyLjEzMjVDNDA4LjE4MSAzMi4xMzI1IDQxNS4zNDggNDEuNTEwNyA0MTQuODczIDU4LjA1NTFDNDE1LjM0OCA3NC40MjI2IDQwNy45MTYgODMuODg5MiAzOTQuNjEzIDgzLjg4OTJaTTM4OS42NTggNzIuMTIyM0MzOTYuOTQ1IDcyLjEyMjMgNDAwLjkyNiA2Ni43MjU1IDQwMC40NTIgNTguMDU1MUM0MDAuOTI2IDQ5LjI5NjMgMzk2Ljk0NSA0My44OTk0IDM4OS42NTggNDMuODk5NEMzODMuODUxIDQzLjg5OTQgMzc5LjI1MSA0OS41NjE3IDM3OC43NzYgNTcuMzQ3M0wzNzguNzc2IDU4LjE0MzZDMzc5LjI1MSA2Ni4xOTQ2IDM4My44NTEgNzIuMTIyMyAzODkuNjU4IDcyLjEyMjNaTTI4OC43MzQgMTMuNjQxN0wyODguNzM0IDQxLjc3NjFMMjYyLjM2OSA0MS43NzYxTDI2Mi4zNjkgMTMuNjQxN0wyNDcuMzI5IDEzLjY0MTdMMjQ3LjMyOSA4My4wMDQ1TDI2Mi4zNjkgODMuMDA0NUwyNjIuMzY5IDU1LjIyNEwyODguNzM0IDU1LjIyNEwyODguNzM0IDgzLjAwNDVMMzAzLjc3NSA4My4wMDQ1TDMwMy43NzUgMTMuNjQxN0wyODguNzM0IDEzLjY0MTdaTTE1MC42MjggODQuMzMxNkMxMzAuMTAyIDg0LjMzMTYgMTE3LjE4NSA3MC4yNjQ0IDExNy4xODUgNDguMjM0NkMxMTcuMTg1IDI2LjIwNDggMTMwLjM2OCAxMi4zMTQ2IDE1MS4yNDcgMTIuMzE0NkMxNjguMjM0IDEyLjMxNDYgMTc4LjQ5NyAxOS41NjkzIDE4MS43NyAzMS43Nzg2TDE2Ni41NTMgMzUuNDA2QzE2NC42OTUgMjguNzcwNSAxNTkuMzg3IDI1LjE0MzEgMTUxLjI0NyAyNS4xNDMxQzEzOS4xMjYgMjUuMTQzMSAxMzIuNTc5IDMzLjEwNTcgMTMyLjU3OSA0OC4yMzQ2QzEzMi41NzkgNjMuMzYzNSAxMzguOTQ5IDcxLjUwMyAxNTAuODkzIDcxLjUwM0MxNjEuODY0IDcxLjUwMyAxNjguNDExIDY0Ljc3OTEgMTY4LjQxMSA1My4zNjZMMTY4LjQxMSA1MC43MTE5TDE3Mi4zMDQgNTYuMTA4N0wxNDkuNjU1IDU2LjEwODdMMTQ5LjY1NSA0My4zNjg2TDE4My42MjggNDMuMzY4NkwxODMuNjI4IDUxLjQxOTZDMTgzLjYyOCA3Mi41NjQ3IDE3MS4zMzEgODQuMzMxNiAxNTAuNjI4IDg0LjMzMTZaTTE5NS45MjYgMjguNTkzNkMyMDAuNjE1IDI4LjU5MzYgMjA0LjI0MyAyNC45NjYyIDIwNC4yNDMgMjAuMjc3MUMyMDQuMjQzIDE1LjU4ODEgMjAwLjYxNSAxMS45NjA3IDE5NS45MjYgMTEuOTYwN0MxOTEuMjM3IDExLjk2MDcgMTg3LjYxIDE1LjU4ODEgMTg3LjYxIDIwLjI3NzFDMTg3LjYxIDI0Ljk2NjIgMTkxLjIzNyAyOC41OTM2IDE5NS45MjYgMjguNTkzNloiIGZpbGw9ImJsYWNrIi8+CjwvZz4KPC9nPgo8ZGVmcz4KPGNsaXBQYXRoIGlkPSJjbGlwMF83MzBfMjcxMjgiPgo8cmVjdCB3aWR0aD0iNDE2IiBoZWlnaHQ9Ijk1IiBmaWxsPSJ3aGl0ZSIvPgo8L2NsaXBQYXRoPgo8Y2xpcFBhdGggaWQ9ImNsaXAxXzczMF8yNzEyOCI+CjxyZWN0IHdpZHRoPSIyOTguMDY4IiBoZWlnaHQ9Ijc1Ljk0MDgiIGZpbGw9IndoaXRlIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxMTcuMTg1IDkuNDkyNTgpIi8+CjwvY2xpcFBhdGg+CjwvZGVmcz4KPC9zdmc+Cg==)](https://github.com)[![Alibaba](/static/svg/alibaba.6237449d74.svg)](https://www.alibaba.com)[![bit.dev](/static/svg/bit.d7c631e153.svg)bit.dev](https://bit.dev/)[![Intuit](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNDEiIGhlaWdodD0iNDEiIHZpZXdCb3g9IjAgMCAxNDEgNDEiIGZpbGw9Im5vbmUiPgogIDxwYXRoIGZpbGwtcnVsZT0iZXZlbm9kZCIgY2xpcC1ydWxlPSJldmVub2RkIgogICAgZD0iTTEzOC43NTIgMzkuNjk2NEMxMzguMjk2IDM5LjY5NDYgMTM3Ljg1OCAzOS41MTI0IDEzNy41MzYgMzkuMTg5N0MxMzcuMjEzIDM4Ljg2NjkgMTM3LjAzMSAzOC40Mjk2IDEzNy4wMjkgMzcuOTczMUMxMzcuMDQ5IDM3LjUyOTQgMTM3LjIzOSAzNy4xMTA1IDEzNy41NiAzNi44MDM2QzEzNy44ODEgMzYuNDk2NiAxMzguMzA4IDM2LjMyNTMgMTM4Ljc1MiAzNi4zMjUzQzEzOS4xOTYgMzYuMzI1MyAxMzkuNjIzIDM2LjQ5NjYgMTM5Ljk0NCAzNi44MDM2QzE0MC4yNjUgMzcuMTEwNSAxNDAuNDU2IDM3LjUyOTQgMTQwLjQ3NiAzNy45NzMxQzE0MC40NzYgMzguOTE3MSAxMzkuNzA1IDM5LjY5NjQgMTM4Ljc1MiAzOS42OTY0Wk0xMzguNzUyIDM1LjkzNTdDMTM3LjYyMyAzNS45MzU3IDEzNi43MDYgMzYuODQyIDEzNi43MDYgMzcuOTczMUMxMzYuNzA2IDM5LjEwNiAxMzcuNjIzIDM5Ljk5MTcgMTM4Ljc1MiAzOS45OTE3QzEzOS44ODUgMzkuOTkxNyAxNDAuOCAzOS4xMDQyIDE0MC44IDM3Ljk3MzFDMTQwLjggMzYuODQyIDEzOS44ODMgMzUuOTM1NyAxMzguNzUyIDM1LjkzNTdaTTEzOC4zNjYgMzcuODIwNFYzNy4xNjY0SDEzOC43NDRDMTM4Ljk2IDM3LjE2NjQgMTM5LjIwMiAzNy4yMzEzIDEzOS4yMDIgMzcuNDgwNEMxMzkuMjAyIDM3Ljc1ODcgMTM4LjkzMyAzNy44MjA0IDEzOC42OTkgMzcuODIwNEgxMzguMzY2Wk0xMzkuNjE0IDM3LjQ4NzZDMTM5LjYxNCAzNi45OTY1IDEzOS4xOTQgMzYuODE0NyAxMzguNzYzIDM2LjgxNDdIMTM3Ljk1NlYzOS4xMTE0SDEzOC4zNjZWMzguMTUxOUgxMzguNjYzTDEzOS4yMDIgMzkuMTEzSDEzOS43MDVMMTM5LjA4MyAzOC4xMDcyQzEzOS40MSAzOC4wMzcyIDEzOS42MTQgMzcuODE4NCAxMzkuNjE0IDM3LjQ4NzZaTTEyNi43MjkgOC4zNjg0N0MxMjcuMjg1IDguMzc5NzIgMTI3LjgzOCA4LjI3OTgyIDEyOC4zNTYgOC4wNzQ2N0MxMjguODczIDcuODY5NTMgMTI5LjM0NSA3LjU2MzIxIDEyOS43NDIgNy4xNzM2OUMxMzAuMTQgNi43ODQxNiAxMzAuNDU2IDYuMzE5MjcgMTMwLjY3MSA1LjgwNjE3QzEzMC44ODcgNS4yOTMwNyAxMzAuOTk4IDQuNzQyMTIgMTMwLjk5OCA0LjE4NTU0QzEzMC45OTggMy42Mjg5NSAxMzAuODg3IDMuMDc3ODkgMTMwLjY3MiAyLjU2NDcxQzEzMC40NTYgMi4wNTE1MiAxMzAuMTQxIDEuNTg2NDggMTI5Ljc0MyAxLjE5Njc5QzEyOS4zNDYgMC44MDcxMDggMTI4Ljg3NSAwLjUwMDY2OCAxMjguMzU3IDAuMjk1MzFDMTI3Ljg0IDAuMDg5OTUyMiAxMjcuMjg3IC0wLjAxMDIwNDUgMTI2LjczMSAwLjAwMDgyMDcwN0MxMjUuNjM1IDAuMDIyNzM5OCAxMjQuNTkzIDAuNDczMTY1IDEyMy44MjYgMS4yNTUzOUMxMjMuMDU5IDIuMDM3NjIgMTIyLjYzIDMuMDg5MzEgMTIyLjYzIDQuMTg0NjVDMTIyLjYzIDUuMjc5OTggMTIzLjA1OSA2LjMzMTY3IDEyMy44MjYgNy4xMTM5QzEyNC41OTMgNy44OTYxMyAxMjUuNjM0IDguMzQ2NTUgMTI2LjcyOSA4LjM2ODQ3Wk0xMTUuNTAzIDExLjk4MTRWMTguMTE5NEgxMjMuMjY1VjM5LjY5ODRIMTMwLjE5MVYxOC4xMTk0SDEzNy45NTRWMTEuOTgxNEgxMTUuNTAzWk01NS4wODAxIDguMzY4NDdDNTUuNjI5NiA4LjM2ODYxIDU2LjE3MzggOC4yNjA1MiA1Ni42ODE1IDguMDUwMzJDNTcuMTg5MiA3Ljg0MDEzIDU3LjY1MDYgNy41MzE5MSA1OC4wMzkyIDcuMTQzNEM1OC40Mjc4IDYuNzU0ODggNTguNzM2MSA2LjI5MzY0IDU4Ljk0NjQgNS43ODU5N0M1OS4xNTY3IDUuMjc4MyA1OS4yNjUgNC43MzQxNiA1OS4yNjUgNC4xODQ2NUM1OS4yNjUgMy42MzUxMyA1OS4xNTY3IDMuMDkwOTkgNTguOTQ2NCAyLjU4MzMyQzU4LjczNjEgMi4wNzU2NSA1OC40Mjc4IDEuNjE0NDEgNTguMDM5MiAxLjIyNTlDNTcuNjUwNiAwLjgzNzM4IDU3LjE4OTIgMC41MjkxNjMgNTYuNjgxNSAwLjMxODk2OEM1Ni4xNzM4IDAuMTA4NzczIDU1LjYyOTYgMC4wMDA2ODM4NTQgNTUuMDgwMSAwLjAwMDgyMDcwN0M1My45ODUgMC4wMjI3Mzk4IDUyLjk0MjEgMC40NzMxNjUgNTIuMTc1NCAxLjI1NTM5QzUxLjQwODcgMi4wMzc2MiA1MC45NzkyIDMuMDg5MzEgNTAuOTc5MiA0LjE4NDY1QzUwLjk3OTIgNS4yNzk5OCA1MS40MDg3IDYuMzMxNjcgNTIuMTc1NCA3LjExMzlDNTIuOTQyMSA3Ljg5NjEzIDUzLjk4NSA4LjM0NjU1IDU1LjA4MDEgOC4zNjg0N1pNNDMuODUzIDE4LjExNzdINTEuNjE2NFYzOS42OTg0SDU4LjU0MDRWMTguMTE5NEg2Ni4zMDU2VjExLjk4MTRINDMuODU0N0w0My44NTMgMTguMTE3N1pNMTAzLjcyNCAzOS42OTg0SDExMC42NTFWMTEuOTk4N0gxMDMuNzI1TDEwMy43MjQgMzkuNjk4NFpNODkuNzEwOCAyNy4yMzM2Qzg5LjcxMDggMzAuOTI3NCA4Ny42MzA0IDM0LjczNDQgODMuMjQ2NyAzNC43MzQ0Qzc4LjgwMjkgMzQuNzM0NCA3OC4wNTI4IDMwLjYzOSA3OC4wNTI4IDI3LjM0ODZWMTEuOTk4N0g3MS4xMjdWMjkuMzEwNkM3MS4xMjcgMzQuOTY3OSA3NC4xMjczIDQwLjUwNjggODEuMzQzMSA0MC41MDY4Qzg1LjQzODYgNDAuNTA2OCA4OC43Mjg5IDM4LjAyNDggODkuOTQwNyAzNS4yNTQ1SDkwLjA1NTZWMzkuNjk4NEg5Ni42MzQ2VjExLjk5ODdIODkuNzEwNkw4OS43MTA4IDI3LjIzMzZaTTMwLjExMTMgMTEuMTkwMkMyNi4wMTQyIDExLjE5MDIgMjIuNzI1NiAxMy42NzIyIDIxLjUxMzcgMTYuNDQyNUgyMS4zOTdWMTEuOTk4N0gxNC44MTk2VjM5LjY5ODRIMjEuNzQzN1YyNC40NjMzQzIxLjc0MzcgMjAuNzY5NiAyMy44MjIzIDE2Ljk2MDggMjguMjA3OCAxNi45NjA4QzMyLjY0OTkgMTYuOTYwOCAzMy40MDE3IDIxLjA1OCAzMy40MDE3IDI0LjM0ODRWMzkuNjk4NEg0MC4zMjU3VjIyLjM4MzFDNDAuMzI1NyAxNi43MjkyIDM3LjMyNzIgMTEuMTkwMiAzMC4xMTEzIDExLjE5MDJaTTAuNzk5OTI3IDM5LjY5ODRINy43MjM5OVYxMS45OTg3SDAuNzk5OTI3VjM5LjY5ODRaIgogICAgZmlsbD0iYmxhY2siIC8+Cjwvc3ZnPg==)](https://www.intuit.com)[![Discord](/static/svg/discord.444d0c4288.svg)](https://discord.com)[![NIO](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHg9IjBweCIgeT0iMHB4IiB2aWV3Qm94PSIwIDAgMTU1Ni45IDU0MCIgc3R5bGU9ImVuYWJsZS1iYWNrZ3JvdW5kOm5ldyAwIDAgMTU1Ni45IDU0MDsiPgo8Zz4KCTxnPgoJCTxwYXRoIGQ9Ik01NTIuNCw0MjAuOGMtMjMuNy0yMy43LTk1LjUtOTUuNS0xMDcuNy0xMDcuN2MtMjIuNS0yMi41LTIwLjYtMjEuNy01Mi41LTIxLjdIMTkwLjRjLTMxLjksMC0zMC0wLjgtNTIuNSwyMS43CgkJCUMxMjUuOCwzMjUuMyw1NCwzOTcsMzAuMyw0MjAuOGMyNC44LDUwLjEsNjMuMSw5MS4xLDEwOS4xLDExOS4yYzI3LjYtMjcuNiwxMTAuMi0xMTAuMiwxMjQtMTI0YzExLjMtMTEuMywxNi4zLTE1LjcsMjIuNC0xNy41CgkJCWMxLjktMC42LDMuNS0xLDUuNS0xYzIsMCwzLjUsMC40LDUuNSwxYzYuMSwxLjksMTEuMSw2LjIsMjIuNCwxNy41YzEzLjgsMTMuOCw5Ni41LDk2LjUsMTI0LDEyNAoJCQlDNDg5LjQsNTExLjgsNTI3LjYsNDcwLjksNTUyLjQsNDIwLjh6Ii8+CgkJPHBhdGggZD0iTTE1My42LDI4MC44YzguMS04LjgsNy0xNi4yLDE0LjktMzYuOWM3LjItMTguNywxOC40LTM1LjIsMzIuNi00OC41YzI1LTIzLjUsNTcuNC0zNS44LDkwLjMtMzUuOHM2NS4zLDEyLjMsOTAuMywzNS44CgkJCWMxNC4xLDEzLjMsMjUuNCwyOS44LDMyLjYsNDguNWM4LDIwLjYsNi44LDI4LjEsMTQuOSwzNi45YzcuOSw4LjUsMTYuMiwxMC42LDQyLjEsMTAuNmgxMTEuNWMwLTg0LjItMzYuMi0xNjEuMy05NC40LTIxNC43CgkJCUM0MzMuNSwyNi4zLDM2Mi44LDAsMjkxLjQsMGMtNzEuNCwwLTE0Mi4xLDI2LjMtMTk3LDc2LjdDMzYuMiwxMzAuMSwwLDIwNy4yLDAsMjkxLjRoMTExLjVDMTM3LjMsMjkxLjQsMTQ1LjYsMjg5LjQsMTUzLjYsMjgwLjh6CgkJCSIvPgoJPC9nPgoJPGc+CgkJPGc+CgkJCTxwYXRoIGQ9Ik0xMzk1LjMsMTMxLjVjLTg5LjEsMC0xNjEuNiw3MS42LTE2MS42LDE1OS43YzAsODguMSw3Mi41LDE1OS43LDE2MS42LDE1OS43Yzg5LjEsMCwxNjEuNy03MS42LDE2MS43LTE1OS43CgkJCQlDMTU1Ni45LDIwMy4yLDE0ODQuNCwxMzEuNSwxMzk1LjMsMTMxLjV6IE0xMzk1LjYsMzc0LjljLTQ2LjEsMC04My43LTM3LjUtODMuNy04My43czM3LjUtODMuNyw4My43LTgzLjcKCQkJCWM0Ni4xLDAsODMuNywzNy41LDgzLjcsODMuN1MxNDQxLjcsMzc0LjksMTM5NS42LDM3NC45eiIvPgoJCTwvZz4KCQk8cGF0aCBkPSJNMTExMS45LDE2NWMwLDkyLjQsMCwxODQuNywwLDI3Ny4xYzI1LjIsMCw1MC40LDAsNzUuNywwYzAtMTAwLjksMC0yMDEuOCwwLTMwMi43Yy0xNi43LDAtMzMuMywwLTUwLDAKCQkJYy00LjQsMC03LjYsMC4xLTExLDEuMWMtMy4yLDEtNi4xLDIuNy04LjUsNS4xYy0yLjQsMi40LTQuMSw1LjMtNS4xLDguNUMxMTEyLDE1Ny40LDExMTEuOSwxNjAuNSwxMTExLjksMTY1eiIvPgoJCTxwYXRoIGQ9Ik03NDIuNCwxMzkuNGMwLDEwMC45LDAsMjAxLjgsMCwzMDIuN2MxNi43LDAsMzMuNSwwLDUwLjIsMGM0LjQsMCw3LjYtMC4xLDExLTEuMWMzLjItMSw2LjEtMi43LDguNS01LjFzNC4xLTUuMyw1LjEtOC41CgkJCWMxLTMuNCwxLjEtNi41LDEuMS0xMWMwLTUzLjUsMC0xMDYuOSwwLTE2MC40Qzg2OC4xLDMxMy4xLDkxOC4xLDM3MCw5NjgsNDI3YzQuNyw1LjMsOC42LDkuNSwxNC42LDEyLjJjNi4xLDIuOCwxMS43LDMsMTguOCwzCgkJCWMxOC40LDAsMzYuOCwwLDU1LjIsMGMwLTEwMC45LDAtMjAxLjgsMC0zMDIuN2MtMTYuNywwLTMzLjUsMC01MC4yLDBjLTQuNCwwLTcuNiwwLjEtMTEsMS4xYy0zLjIsMS02LjEsMi43LTguNSw1LjEKCQkJYy0yLjQsMi40LTQuMSw1LjMtNS4xLDguNWMtMSwzLjQtMS4xLDYuNS0xLjEsMTFjMCw1My41LDAsMTA2LjksMCwxNjAuNGMtNDkuOS01Ny05OS45LTExMy45LTE0OS44LTE3MC44CgkJCWMtNC43LTUuMy04LjYtOS41LTE0LjYtMTIuMmMtNi4xLTIuOC0xMS43LTMtMTguOC0zQzc3OS4xLDEzOS40LDc2MC44LDEzOS40LDc0Mi40LDEzOS40eiIvPgoJPC9nPgo8L2c+Cjwvc3ZnPgo=)](https://nio.com)[![ABB](/static/svg/abb.4369dcad86.svg)](https://abb-bank.az/en)[![Sequoia](/static/svg/sequoia.a34c3373e1.svg)](https://www.sequoia.com/)[![Getaround](data:image/svg+xml;base64,PHN2ZyBoZWlnaHQ9IjI2IiB3aWR0aD0iMTEwIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIj4KICA8cGF0aCBkPSJtMTkuOSA0LjZjLTMuOSAwLTYuNCAyLjYtNi40IDYuMiAwIDMuOCAyLjUgNi4zIDYuNiA2LjMgMS44IDAgMy45LS42IDUuMS0xLjlsLTEuOS0xLjhjLS43LjctMi4xIDEuMS0zLjIgMS4xLTIuMSAwLTMuNC0xLjEtMy41LTIuNWg5LjRjLjUtNS0yLjEtNy40LTYuMS03LjR6bS0zLjIgNC45Yy41LTEuNSAxLjgtMi4zIDMuNC0yLjMgMS43IDAgMi45LjggMy4xIDIuM3ptMTUuMiA0LjhjLS45IDAtMS41LS41LTEuNS0xLjd2LTUuMWgzLjN2LTIuNWgtMy4zdi0zLjNsLTMgLjN2MTAuN2MwIDMgMS43IDQuNCA0LjMgNC4zLjkgMCAxLjYtLjIgMi41LS41bC0uOS0yLjVjLS40LjItLjkuMy0xLjQuM3ptMjIuNC05LjdjLTEuMiAwLTIuNS4yLTMuNCAxLjdsLS4yLTEuM2gtMi44djExLjloM3YtNi4yYzAtMi4yIDEuNS0zIDMtMyAxIDAgMS40LjIgMiAuNmwxLjMtMi41Yy0uNi0uOC0xLjctMS4xLTIuOS0xLjJ6bTguNy4xYy0zLjggMC02LjIgMi44LTYuMiA2LjJzMi4zIDYuMiA2LjIgNi4yIDYuMi0yLjcgNi4yLTYuMmMuMS0zLjQtMi40LTYuMi02LjItNi4yem0uMSA5LjdjLTIuMSAwLTMuMi0xLjctMy4yLTMuNXMxLjItMy41IDMuMi0zLjUgMy4yIDEuOCAzLjIgMy41YzAgMS44LTEuMSAzLjUtMy4yIDMuNXptMTYuMy0zLjRjMCAxLjgtMS4yIDMuNC0zLjEgMy40cy0yLjktMS40LTIuOS0zLjJ2LTYuMmgtM3Y2LjJjMCAzLjcgMi4xIDUuOCA0LjkgNS44IDEuNyAwIDIuOC0uNiA0LjEtMS44bC4yIDEuNmgyLjZ2LTExLjhoLTIuOXptMTEuMy02LjNjLTEuNSAwLTIuNy42LTMuOSAxLjhsLS4yLTEuNmgtMi42djExLjloMi45di02LjFjMC0xLjggMS4yLTMuNCAzLjEtMy40czIuOSAxLjQgMi45IDMuMnY2LjJoM3YtNi4yYy0uMS0zLjYtMi4zLTUuOC01LjItNS44em0xNi4zLTQuN3Y2LjZjLS43LTEuMi0yLjctMS45LTMuOS0xLjktMy41IDAtNi4xIDIuMS02LjEgNi4yIDAgMy45IDIuNiA2LjIgNi4xIDYuMiAxLjUgMCAyLjktLjUgMy44LTEuOWwuMiAxLjZoMi44di0xNi44em0tMy43IDE0LjNjLTEuOSAwLTMuNC0xLjQtMy40LTMuNXMxLjUtMy40IDMuNC0zLjRjMS44IDAgMy41IDEuNCAzLjUgMy40IDAgMi4yLTEuNiAzLjUtMy41IDMuNXptLTU5LTkuMmMtMS40LS44LTQuMi0uOC01LjgtLjUtMS45LjUtMy4xIDItMy4yIDMuOGwyLjguNmMuMy0xLjMuNi0xLjggMS45LTIgLjgtLjIgMi4xLS4xIDIuOC42LjQuNC40LjUuNCAxLjIgMCAuMy0uNi40LTEgLjUtMS4zLjMtMy40LjUtNC43LjgtMi41LjctMi45IDMuNy0xLjYgNS4zczQuNiAyIDYuNC44Yy4zLS4yLjUtLjQuOS0uNnYxLjFoMy4xdi0zYzAtMS44LjEtMy42IDAtNS40LS4xLTEuNC0uOC0yLjUtMi0zLjJ6bS0yLjMgOWMtLjQuMi0uOC4zLTEuMi41LS41LjEtMS4yLjItMS43LjEtLjQtLjEtLjgtLjMtMS0uNi0uMi0uMi0uMi0uNC0uMi0uNyAwLS4yLjEtLjQuMi0uNnMuNC0uNC42LS41Yy44LS4zIDEuNi0uNSAyLjUtLjVsMS40LS4yaC40Yy4xIDAgLjEgMCAuMS4xIDAgLjIgMCAuNC0uMS42IDAgLjItLjEuNC0uMi42LS4xLjQtLjQuOC0uOCAxLjJ6bS0zNS44IDNjLTMuOSAwLTYuMi0yLjctNi4yLTYuMnMyLjQtNi4yIDYuMi02LjJoNy40cy0uMyAxLjktMi4xIDIuN2gtNS4zYy0yLjEgMC0zLjMgMS44LTMuMyAzLjUgMCAxLjggMS4xIDMuNSAzLjIgMy41czMuMi0xLjcgMy4yLTMuNWMwLTEtLjQtMi0xLjEtMi42aDMuNWMuNC44LjUgMS43LjUgMi42IDAgMi0uOCAzLjctMi4xIDQuOCAxLjcgMSAyLjEgMi40IDIuMSAzLjggMCAzLjQtMi42IDUuNS02LjEgNS41LTMuNCAwLTUuOS0xLjktNi4yLTQuOGwzLS4zYy4yIDEuNCAxLjUgMi40IDMuMiAyLjQgMS44IDAgMy4xLS45IDMuMS0yLjcuMi0xLjgtMS40LTIuNS0zLTIuNXoiIC8+Cjwvc3ZnPgo=)](https://getaround.com)[![Trellis](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0MzIgMTY1LjI1IiBmaWxsPSJub25lIj4KICAgIDxkZWZzPgogICAgICAgIDxzdHlsZT4KICAgICAgICAgICAgLmNscy0xIHsKICAgICAgICAgICAgZmlsbDogYmxhY2s7CiAgICAgICAgICAgIH0KCiAgICAgICAgICAgIC5jbHMtMiB7CiAgICAgICAgICAgIGZpbGw6IGJsYWNrOwogICAgICAgICAgICB9CiAgICAgICAgPC9zdHlsZT4KICAgIDwvZGVmcz4KICAgIDx0aXRsZT5sb2dvX3JlZzwvdGl0bGU+CiAgICA8ZyBpZD0iTGF5ZXJfMiIgZGF0YS1uYW1lPSJMYXllciAyIj4KICAgICAgICA8ZyBpZD0iTGF5ZXJfMS0yIiBkYXRhLW5hbWU9IkxheWVyIDEiPgogICAgICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTEiIGQ9Ik0yNTIuODMsMTU2cS01Ljc5LDkuMjItMTcuNTcsOS4yMy04LjgzLDAtMTMuOTQtNS43OXQtNS4xMS0xNXEwLTEyLDQuNzItMzQuNDZMMjQwLjY2LDE2SDI2NWwtMjAuMjMsOTcuODdxLTQuMzIsMjAuOTMtNC4zMiwyOS44NWExMS42OSwxMS42OSwwLDAsMCwzLjUzLDlBMTIuNDksMTIuNDksMCwwLDAsMjUyLjgzLDE1NloiLz4KICAgICAgICAgICAgPHBhdGggY2xhc3M9ImNscy0xIiBkPSJNMjk5LjYxLDE1NnEtNS43OCw5LjIyLTE3LjU2LDkuMjMtOC44NSwwLTEzLjk1LTUuNzl0LTUuMS0xNXEwLTEyLDQuNzEtMzQuNDZMMjg3LjQ0LDE2aDI0LjM1bC0yMC4yMiw5Ny44N3EtNC4zMiwyMC45My00LjMyLDI5Ljg1YTExLjY5LDExLjY5LDAsMCwwLDMuNTMsOUExMi41LDEyLjUsMCwwLDAsMjk5LjYxLDE1NloiLz4KICAgICAgICAgICAgPHBhdGggY2xhc3M9ImNscy0xIiBkPSJNMzM4LjU4LDE0My42OWMwLTYsMS43Ny0xNi4yMiw0LjY1LTMwLjE2bDMuNjYtMTcuNjVoMGw3LjgtMzYuODJoLTM1LjNsLTQuMTIsMTkuNzNoMTAuMzVsLTUuMzEsMjQuNjUtMS4yNiw2LjQ3cS00LjcxLDIyLjUtNC43MiwzNC40NiwwLDkuMjMsNS4xMSwxNXQxMy45NCw1Ljc5cTExLjc4LDAsMTcuNTctOS4yNGExMi40NiwxMi40NiwwLDAsMS04LjgzLTMuMjhBMTEuNjYsMTEuNjYsMCwwLDEsMzM4LjU4LDE0My42OVoiLz4KICAgICAgICAgICAgPHBhdGggY2xhc3M9ImNscy0xIiBkPSJNMjA2LjY1LDYzLjgzUTE5OC4xOSw1NywxODMsNTdhNDcuNjIsNDcuNjIsMCwwLDAtMjgsOC43OHEtMTIuNTEsOC43OC0xOS44MiwyNC44N2E4Myw4MywwLDAsMC03LjMyLDM0Ljc5cTAsMTguOCwxMC40MywyOS4yN3QyOSwxMC40OGguMTJ2MGMuMTgsMCwuNjctLjA3LDIuMTctLjI4LDcuMzktLjgsMTUtMy43NSwxOS44OS0xMC4yLDMuMTQtNC4wOCwzLjgtMTIsMS0xOGExNC4zOSwxNC4zOSwwLDAsMS0yLjIxLDIuNjRjLS4xNy4xNy0uMzUuMzEtLjUxLjQ2YTguNDIsOC40MiwwLDAsMS0uODcuNzFjLTEyLjU5LDEwLjQtMzQuMzctLjIzLTM2LjM4LTEyLjMtLjA3LS45Mi0uMTktMS44MS0uMTktMi44MXYtMi43NGwuMTktMi45Mmg0LjA2cTI5LjA3LDAsNDQuNzktOS42OHQxNS43Mi0yNi44NlEyMTUuMDksNzAuNjgsMjA2LjY1LDYzLjgzWm0tMjMsMzQuNjVxLTEwLDUuMDUtMjcuNzUsNWgtMi43NHEzLjUtMTMuMzEsMTEuNDctMjEuNDJ0MTctOC4xM3E2LDAsOSwyLjY5YTkuNTIsOS41MiwwLDAsMSwzLDcuNTFRMTkzLjY3LDkzLjQzLDE4My42NSw5OC40OFoiLz4KICAgICAgICAgICAgPHBhdGggY2xhc3M9ImNscy0xIiBkPSJNNDEuNjgsNTkuMjEsNDguNTksMjcuNSwyMC42NywzNy43MWwtNC41OSwyMS41SDQuMjJMMCw3OC45NEgxMS44MUw1LjE1LDExMC4xMUMyLjUyLDEyMi42NiwwLDEzMi4wOSwwLDE0MUEyNC4yMywyNC4yMywwLDAsMCwxNS40NSwxNjNoMGwuMTMsMGMuNzYuMywxLjU1LjU4LDIuMzkuODJsLjc0LjE5Yy43Mi4yLDEuNDUuMzcsMi4yMi41My41OC4xLDEuMTkuMTcsMS44LjI2LjQ1LjA2Ljg2LjE1LDEuMzMuMmguMDZhNDIuMzEsNDIuMzEsMCwwLDAsNC4zNC4yM2wuMywwYzEuMjYsMCwyLjQzLS4wOCwzLjU0LS4xOGwuNDUtLjA3YTI5Ljg0LDI5Ljg0LDAsMCwwLDMuMTEtLjQ5aDBjNS4xLTEuMDksOC41LTMuMjcsMTAuNzMtNS44NS4zOS0uNS43Ny0xLDEuMTEtMS41MWwuMDgtLjFhMTguNDksMTguNDksMCwwLDAsLjkyLTEuNjFjLjEtLjIuMjEtLjM5LjMtLjU5YTYuNjYsNi42NiwwLDAsMCwuMzEtLjczLDIxLDIxLDAsMCwwLDEuNDItOC42M2MwLS41My0uMDYtMS4wNi0uMTMtMS42YTE0LjM1LDE0LjM1LDAsMCwxLTIuOSwxLjg2Yy0uMjEuMTItLjQyLjItLjYyLjNsLS4xMi4wNWMtOS45LDQuODMtMjAuNS40LTIxLjM1LTUuMTJhMjIsMjIsMCwwLDEsLjM5LTguMjRsMS42Ni03Ljg5LDAtLjE1djBsOS42Ny00NS43Mkg2NS43N0w3MCw1OS4yMkg0MS42OFoiLz4KICAgICAgICAgICAgPHBhdGggY2xhc3M9ImNscy0xIiBkPSJNMTMyLjU3LDU3LjFjLTEwLjQ1LDAtMjAuMzcsMy45Mi0yOSwxMS4ybDEuODEtOS4wOUg4MS4yNWwtMTAuNjIsNTAuN3EtNC43MSwyMi41LTQuNzEsMzQuNDYsMCw5LjIzLDUuMSwxNXQxNCw1Ljc5cTExLjc3LDAsMTcuNTctOS4yNGExMi41LDEyLjUsMCwwLDEtOC44NC0zLjI4LDExLjY3LDExLjY3LDAsMCwxLTMuNTMtOWMwLTYsLjYxLTE1LjM1LDMuNDktMjkuMjhMOTYuMTIsMTAzbDEuMjMtMy40N2E0NS44Miw0NS44MiwwLDAsMSw5LjQ0LTEzLjY5cTcuOTItOC4zLDE3LjQzLTguMjlhMTguNzksMTguNzksMCwwLDEsOC4xOSwxLjI3bDQuNDItMjEuMzdBNDAsNDAsMCwwLDAsMTMyLjU3LDU3LjFaIi8+CiAgICAgICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtMSIgZD0iTTQxNy4wNSwxMDYuNTVxLTUuNzEtMy4xOC0xNi4zNS04LjU4Yy03LjEtMy42MS0xMC42NS03LjMzLTEwLjY1LTExLjJxMC00LjcxLDQuNDctNy41MWExOS4zOSwxOS4zOSwwLDAsMSwxMC41NS0yLjhxOS44MSwwLDIxLjU5LDEwLjMxbC4xOC0uMzRMNDMyLDYxLjg3QzQyMS43OCw1OCw0MTMuMjQsNTYsNDA2LjQ0LDU2cS0xNy43OCwwLTMwLDkuMDlUMzY0LjIzLDg5LjUyYTIzLDIzLDAsMCwwLDMuNjgsMTIuNzFBMjkuNzUsMjkuNzUsMCwwLDAsMzc4LjY2LDExMmMyLjg0LDEuNiw2LDMuMzEsOS4zMyw1LjExLDQuMjcsMi4xOSwyMC44MSw2LjYsMTUuMTcsMTkuMDZsLS4xNS4zYy01LjgzLDEyLjM3LTI0LjE2LDkuMjgtMjcuNCw4LjM1YTIzLDIzLDAsMCwxLTguNjQtNC4yMmMtLjMtLjIxLS41OC0uNDYtLjg3LS43MXMtLjM0LS4zLS41MS0uNDdhMTQuMzgsMTQuMzgsMCwwLDEtMi4yMS0yLjYzYy0yLjgsNS45NS0yLjI3LDEzLjU4LDEsMTgsNC42Miw2LjI2LDEyLjUxLDkuMzQsMTkuODksMTAuMTRsMi4xNy4zaC4xMnExMi4xNywwLDIwLjgzLTQuNUE0My42Nyw0My42NywwLDAsMCw0MTcsMTU1LjFxMTMtMTAsMTMtMjcuMzlhMjIuMDYsMjIuMDYsMCwwLDAtMy42My0xMi41MkEyNi44OCwyNi44OCwwLDAsMCw0MTcuMDUsMTA2LjU1WiIvPgogICAgICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik0zNjcuNjQsMEMzNjMuNzgsOS43NywzNTQsMTIuNTMsMzQ2LjM2LDEyLjQ3Yy01Ljg3LDAtMTQuMDYtLjgzLTE5LjgsOC44NWwwLC4wNWgwbDAsMEExNy44LDE3LjgsMCwwLDAsMzI0LDMwLjY0YzAsMS42NiwxLjQsOC4xOCwzLjIzLDYuNEE0MC42MSw0MC42MSwwLDAsMSwzNDAsMjhjOS4zOS00LDI1LTQuNzMsMjcuODUtMTkuODIuMS0uNS40LS42OC4zOS0uMS0uNTUsMTEuMzMtNSwxNi40Ny0yMi40NiwyMi41Ny03LjQxLDIuNTktMTUuODUsOC4xOC0xNS43MiwxMS45MXM1Ljg3LDYuMTQsMTEuODMsNkMzNjQsNDcuOSwzNzIuNTUsMzEsMzcyLjU1LDE3LjI2UzM2Ny42NCwwLDM2Ny42NCwwWiIvPgogICAgICAgIDwvZz4KICAgIDwvZz4KPC9zdmc+Cg==)](https://trellis.org)[![Kuaishou](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0MzIgODAiPjxwYXRoIGQ9Ik00NiAzOS43aDMuNWM2LjggMCAxMiAwIDE3LjEgNC44IDUuNiA3LjIgNSAxNC44IDQuNCAyMy41YTE1LjggMTUuOCAwIDAgMS02LjggMTAuMmMtNS42IDMtMTIgMi4zLTE4LjMgMi4yaC0zLjhjLTcuOSAwLTEzLS41LTE5LTZMMjEgNzJsLTIgMWMtOS4yIDUtOS4yIDUtMTUgNC0yLjgtMi4xLTMuOS0zLjMtNC41LTYuOFY2MGwtLjEtMy42di02LjZjLjYtMi44LjYtMi44IDMtNS4yQzUgNDMgNSA0MyA4LjMgNDNjMy42IDEgNi41IDIuNCA5LjggNC4zIDIgMSAyIDEgNC44LS4zbDIuNC0yLjRjNS45LTUuOCAxMi43LTUgMjAuNS01Wk0zMS4xIDUwLjNjLTIuMSAzLTEuNyA2LjYtMS43IDEwLjJ2Mi4zYy0uMSAzLjUgMCA1LjYgMi4zIDguMiA0LjggMS41IDkuMyAxLjQgMTQuMyAxLjNoM2M2LjIgMCA2LjIgMCAxMS45LTIuMyAxLjYtMy4xIDEuMi02LjUgMS4zLTEwdi0yYy4xLTQgLjEtNC0xLjUtNy42LTIuNi0xLjgtNC41LTEuNy03LjctMS43SDM1LjdjLTIuNy4yLTIuNy4yLTQuNSAxLjdaTTkgNTNjLTEuMyAxLjEtMS4zIDEuMS0xLjEgNHY3LjJMOCA2N2wyIDFjMi43LTEuMiAyLjctMS4yIDUuNi0zIDEtLjUgMi0xIDMtMS43TDIxIDYydi00bC00LjktMi41LTIuNy0xLjRDMTEgNTIuOSAxMSA1Mi45IDkgNTNaIiBmaWxsPSJibGFjayIvPjxwYXRoIGQ9Ik0zNC4xLjhBNjQgNjQgMCAwIDEgNDQgOGwyLjUtMS41YzUuMi0yLjIgOS4yLTIuMyAxNC42LS40IDQuNCAyLjkgOCA2IDkuNiAxMS4xLjggNS4zIDAgOS0yLjcgMTMuOC0zLjMgMy44LTYuMiA2LjYtMTEuNCA3LjNBMjYgMjYgMCAwIDEgNDAgMzNsLTIuMyAyYy01LjEgMy45LTEwLjUgMy41LTE2LjcgMy01LjgtMS44LTkuNi02LjEtMTMtMTFhMjEuNSAyMS41IDAgMCAxIC42LTE2LjFDMTMuOCAxLjUgMjMuNi0zIDM0IC44Wk0xNyAxNGMtMS44IDMuNS0xIDcuMyAwIDExIDIuMyAyLjYgNC4yIDMuNyA3LjQgNSAzLjggMCA2LjMtMS4xIDkuNi0zIDIuMy0yLjcgMy00LjUgMy40LTgtLjUtMy44LTItNi00LjQtOS02LjMtMy4xLTExLjktMS40LTE2IDRabTMxIDJjLTIuMyAyLjktMi4zIDIuOS0yIDYuNiAxLjEgNCAxLjEgNCA0IDYuNCAyLjYgMS4xIDMuOCAxIDYuNi4zIDIuOC0xLjUgNC0yLjQgNS40LTUuMyAwLTMuOC0uMi02LTIuNy05LTQuNS0yLTcuMi0xLjgtMTEuMiAxWiIgZmlsbD0iYmxhY2siLz48cGF0aCBkPSJNMzczLjQgMjBjNiA0LjUgOSA4LjcgMTAuNiAxNiAxIDkuMyAxLjQgMjAtNCAyOGEyMS43IDIxLjcgMCAwIDEtMTUgOC4yIDI2IDI2IDAgMCAxLTE1LTMuMiAyNS44IDI1LjggMCAwIDEtOC4zLTE5IDQyIDQyIDAgMCAxIDUtMjQuOGM3LjUtNy4xIDE3LTguMiAyNi43LTUuMVptLTE3LjggMTBhMzYuNiAzNi42IDAgMCAwLTIuNiAyNGMxLjUgNC4xIDMgNyA3IDkgMy45LjQgNi45LjQgMTAtMiAzLjMtNS4yIDMuNS05LjYgMy40LTE1LjVWNDNjMC01LS41LTguNy0zLjQtMTMtNC42LTMtOS45LTMuNi0xNC40LS4xWk0yOTMgMTloMTB2MjJoMjBWMTloMTB2NTJoLTEwVjUwaC0yMHYyMWgtMTBWMTlabS05NS44LS4xaDcuOGwzIC4xIDEuNSA0LjYgMSAzQTIwODczLjIgMjA4NzMuMiAwIDAgMSAyMjMuMyA2N2MuNiAyLjEuNiAyLjEuNiA0LjFoLTExbC00LTEyLTE3LTEtMS40IDZjLTEuNSA1LjktMS41IDUuOS0yLjYgN2E5MS41IDkxLjUgMCAwIDEtNy44IDBIMTc4YTIwNSAyMDUgMCAwIDEgNS0xOWwuOS0yLjhBMzMzMyAzMzMzIDAgMCAxIDE5MCAyOWwuOS0yLjcuNy0yLjUuNy0yLjFjMS0zIDEuNC0yLjcgNC44LTIuOFpNMjAwIDI5bC0yLjUgOC45LS43IDIuNS0uNyAyLjUtLjYgMi4yYy0uNiAxLjktLjYgMS45LS41IDMuOWgxMWMtLjYtNy0yLjktMTMuNC01LTIwaC0xWk05MSAxOWgxMGwxIDIxIDYuMi0xMGM1LjItOC41IDUuMi04LjUgNy44LTExIDIuOC0uNSAyLjgtLjUgNS44LS4zbDMgLjEgMi4yLjJhNDAuMiA0MC4yIDAgMCAxLTYuOSAxMi4zIDU2MS41IDU2MS41IDAgMCAxLTUuNSA4bC0xLjcgMi40Yy0xLjIgMi4zLTEuMiAyLjMtLjIgNC44YTU2IDU2IDAgMCAwIDQuMyA2LjhsMS43IDIuMyAxLjggMi41IDMuNSA0LjcgMS42IDIuMmMxLjMgMiAyLjQgMy45IDMuNCA2LTQuNSAxLjQtOC43IDIuMi0xMyAwLTUuOC02LTkuOS0xMy43LTE0LTIxbC0xIDIxSDkxVjE5Wm0zMDIgMGgxMHYzLjNhMjAwMy41IDIwMDMuNSAwIDAgMCAuNSAyNS4xdjIuNGMuMSA0LjUuNyA3LjYgMy41IDExLjIgMi42IDEuMSA1LjIgMS4yIDggMSAzLTEgMy0xIDUtMyAxLjMtNCAxLjItOC4xIDEuMy0xMi4zdi0yLjRBMzAxNi4yIDMwMTYuMiAwIDAgMCA0MjIgMTloMTBhMjE3OC42IDIxNzguNiAwIDAgMSAuMyAyOXYyLjRjMCA2LjYtMS4zIDExLjEtNS41IDE2LjRhMjQuNiAyNC42IDAgMCAxLTE3LjYgNS41Yy01LjMtLjctOS41LTIuMi0xMy4xLTYuM2ExNSAxNSAwIDAgMS0zLjItMTAuMXYtNS4yQTM0ODk4Mzk1Mi4zIDM0ODk4Mzk1Mi4zIDAgMCAwIDM5MyAxOVptLTI1OSAwaDEwdjMuMWEyNzcyIDI3NzIgMCAwIDAgLjYgMjUuOWMuMSA0LjMuNyA4IDIuNCAxMiAzLjEgMi40IDYuMiAyLjIgMTAgMiAyLjMtLjQgMi4zLS40IDQtMSAxLjItNC4yIDEuMi04LjQgMS4zLTEyLjd2LTIuNUEzMzQ2LjMgMzM0Ni4zIDAgMCAwIDE2MyAxOWgxMGEyNDQ2LjggMjQ0Ni44IDAgMCAxIC4zIDMwLjd2Mi41YzAgNS0uNSA4LjQtMy4zIDEyLjhhMjMuNSAyMy41IDAgMCAxLTE3IDcuMyAyMCAyMCAwIDAgMS0xMy44LTVjLTMuNS0zLjktNS4zLTctNS4zLTEyLjN2LTVhMzMxNTUxNjc3LjMgMzMxNTUxNjc3LjMgMCAwIDAgLjEtMzFabTE0NS44IDIgMy4yIDJhMTggMTggMCAwIDEtNSA5bC02LTMtNC0uMmgtMi4xYy0yLjEgMC0yLjEgMC0zLjkgMi4yLS4zIDIuNS0uMyAyLjUgMSA1IDIuNCAxLjkgNSAzLjIgNy44IDQuNSAxMiA2LjIgMTIgNi4yIDE0LjIgMTIuNS41IDUgMCA4LjMtMi43IDEyLjQtMyAzLjYtNy42IDYtMTIuMyA2LjZhMzAgMzAgMCAwIDEtMjItNmMxLjUtMy4xIDMuMi02IDUtOWwxLjYuOEwyNTcgNTlsMy4zIDEuN2ExOCAxOCAwIDAgMCAxMS43LjNjMS4yLTEgMS4yLTEgMS42LTMuMy0uMy0yLjctLjMtMi43LTItNGExMjAgMTIwIDAgMCAwLTktNWMtNS0yLjYtOC43LTQuNy0xMS42LTkuNy0xLTUtLjYtOC44IDEuNi0xMy40YTIyLjIgMjIuMiAwIDAgMSAyNy4yLTQuNlpNMjMwIDE5aDExdjUyaC0xMVYxOVoiIGZpbGw9ImJsYWNrIi8+PC9zdmc+)](https://ir.kuaishou.com/)[![DeepSeek](/static/svg/deepseek.ffd6a2bd14.svg)](https://deepseek.com)[![Khan Academy](/static/svg/khan-academy.1dc4c96f14.svg)](https://khanacademy.org/)[![Verkada](/static/image/verkada.2f739d8722.png)](https://verkada.com)[![Miro](data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyBpZD0iTGF5ZXJfMSIgZGF0YS1uYW1lPSJMYXllciAxIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA3MDMgMjU4Ij4KICA8ZGVmcz4KICAgIDxzdHlsZT4KICAgICAgLmNscy0xIHsKICAgICAgICBmaWxsOiAjZmZmOwogICAgICAgIGZpbGwtcnVsZTogZXZlbm9kZDsKICAgICAgfQoKICAgICAgLmNscy0yIHsKICAgICAgICBmaWxsOiAjMDIwNTA0OwogICAgICB9CiAgICA8L3N0eWxlPgogIDwvZGVmcz4KICA8Zz4KICAgIDxwYXRoIGNsYXNzPSJjbHMtMiIgZD0iTTUzMi4zNywxMzEuNTV2NTYuNzVoMjMuMjJ2LTUzLjI2YzAtMjMuNzQsMzIuMjgtMjMuNzQsMzIuMjgtMjMuNzR2LTIzLjA3cy05LjAxLjQyLTE2LjE0LDIuMDNjLTIwLjIsNC41My0zOS4zNiwxNC41My0zOS4zNiw0MS4zNHYtLjA1WiIvPgogICAgPHBhdGggY2xhc3M9ImNscy0yIiBkPSJNMzU3LjE2LDg3LjAzYzkuMDYsMCwyMC4zNiw1LjEsMjYuNSwxNC4xMSw2LjM1LTguMTcsMTYuODctMTMuNzUsMjkuODMtMTMuOTUsMTYuNDUtLjIxLDM2LjgxLDEwLjA1LDM2LjgxLDQwLjc3djYwLjE5aC0yMy4yMnYtNjAuMTljMC0xMC4yNi03LjM5LTE3LjYtMTguNDgtMTcuNnMtMTguNDksNy4zNC0xOC40OSwxNy42djYwLjE5aC0yMy4yMnYtNjAuMTljMC0xMC4yNi03LjM5LTE3LjYtMTguNDgtMTcuNnMtMTguNjksNy4zNC0xOC42OSwxNy42djYwLjE5aC0yNC40MnYtOTguMTVoMjQuNDJ2OS44NGM2LjYxLTcuOTcsMTYuMjQtMTIuOTEsMjcuNTQtMTIuOTFsLS4xLjFaIi8+CiAgICA8cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik01MDMuNzksOTEuM3Y5Ni45NWgtMjMuNjR2LTk2Ljk1aDIzLjY0WiIvPgogICAgPHBhdGggY2xhc3M9ImNscy0yIiBkPSJNNDkxLjkxLDc1Ljg5YzcuMjksMCwxMy4xNy01Ljg4LDEzLjE3LTEzLjEycy01Ljg4LTEzLjEyLTEzLjE3LTEzLjEyLTEzLjE3LDUuODgtMTMuMTcsMTMuMTIsNS44OCwxMy4xMiwxMy4xNywxMy4xMloiLz4KICAgIDxwYXRoIGNsYXNzPSJjbHMtMiIgZD0iTTY1MC45OCw4Ni44M2MtMjguNjQsMC01MS44MSwyMy4wNy01MS44MSw1MS41NXMyMy4yMiw1MS41NSw1MS44MSw1MS41NSw1MS44MS0yMy4wNyw1MS44MS01MS41NS0yMy4yMi01MS41NS01MS44MS01MS41NVpNNjUwLjk4LDE2Ni43NWMtMTYuMTksMC0yOS4zMS0xMy4wNy0yOS4zMS0yOS4yMXMxMy4xMi0yOS4yMSwyOS4zMS0yOS4yMSwyOS4zMiwxMy4wNywyOS4zMiwyOS4yMS0xMy4xMiwyOS4yMS0yOS4zMiwyOS4yMVoiLz4KICA8L2c+CiAgPGc+CiAgICA8cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik0uNSw2NC44NUMuNSwyOS40NSwyOS4yNC43LDY0LjY0LjdoMTI4LjNjMzUuNDEsMCw2NC4xNSwyOC43NCw2NC4xNSw2NC4xNXYxMjguMjljMCwzNS40MS0yOC43NCw2NC4xNS02NC4xNSw2NC4xNUg2NC42NEMyOS4yNCwyNTcuMy41LDIyOC41NS41LDE5My4xNVY2NC44NVoiLz4KICAgIDxwYXRoIGNsYXNzPSJjbHMtMSIgZD0iTTE3MS4wNyw0OS42NWgtMjMuMjdsMTkuNDIsMzQuMS00Mi43LTM0LjFoLTIzLjI3bDIxLjM1LDQxLjY1LTQ0LjYyLTQxLjY1aC0yMy4yN2wyMy4yNyw1My4wNi0yMy4yNywxMDYuMTFoMjMuMjdsNDQuNjItMTEzLjY2LTIxLjM1LDExMy42NmgyMy4yN2w0Mi43LTEyMS4yNy0xOS40MiwxMjEuMjdoMjMuMjdsNDIuNy0xMzIuNjItNDIuNy0yNi41di0uMDVaIi8+CiAgPC9nPgo8L3N2Zz4=)](https://miro.com)[![Snap](/static/svg/snap.bbf5e520f1.svg)](https://www.snap.com/)[![Cloudflare](/static/svg/cloudflare.6f1f022a9f.svg)](https://cloudflare.com)[![YouMind](/static/svg/youmind.a6693dacbc.svg)](https://youmind.com)

## Guide

- [Quick Start](/guide/start/quick-start)
- [Features](/guide/features/asset-module)
- [Migration](/guide/migration/webpack)
- [Compatibility](/plugins/community-plugin-compatibility)

## API

- [CLI](/api/cli)
- [Plugin API](/api/plugin-api/)
- [Loader API](/api/loader-api/)
- [JavaScript API](/api/javascript-api)

## Toolchain

- [Rsbuild](https://rsbuild.rs/)
- [Rslib](https://rslib.rs/)
- [Rspress](https://rspress.rs/)
- [Rsdoctor](https://rsdoctor.rs/)
- [Rstest](https://rstest.rs/)

## Community

- [GitHub](https://github.com/web-infra-dev/rspack)
- [Discord](https://discord.gg/sYK4QjyZ4V)
- [Twitter (X)](https://twitter.com/rspack_dev)
- [BlueSky](https://bsky.app/profile/rspack.dev)
- [Awesome Rspack](https://github.com/rstackjs/awesome-rstack)

Rspack is free and open source software released under the MIT license.

© 2022-present ByteDance Inc.




---
url: /misc/branding/license.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# License

## Rspack

Rspack is [MIT licensed](https://github.com/web-infra-dev/rspack/blob/main/LICENSE).

## Rspack documentation

Unless otherwise noted, the content of the documents is from [Rspack website contributors](https://github.com/web-infra-dev/rspack/graphs/contributors) and is licensed under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/deed.en) license.

## Third-party documentation

Some pages contain modified content adapted from [webpack documentation](https://webpack.js.org/) under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) license. Each affected page links to its original source in an attribution note at the bottom.



---
url: /misc/faq.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# FAQ

## What will be the relationship between Rspack and webpack in the future?

**We have established a partnership with the webpack team.** Rspack is an attempt to optimize webpack performance using Rust, and it has already made good progress.

We will continue to explore more possibilities for optimizing webpack with the webpack team.

## Will compatibility with JavaScript or webpack ecosystem cause performance loss?

We place more emphasis on bringing performance improvements to existing web projects at a lower migration cost than simply chasing benchmark metrics.

Compatibility with the webpack ecosystem will result in some performance loss, but according to our verification results, this loss is within an acceptable range.

## How to achieve compatibility fallback compilation without using babel-loader?

Rspack internally uses SWC to perform code downgrade compilation which you can configure by [builtin:swc-loader](/guide/features/builtin-swc-loader.md), so there is no need to use babel-loader to perform code downgrade compilation.

## Is Rspack 100% compatible with webpack API?

No, the goal of Rspack is not to be 100% compatible with 100% of the webpack API. Based on the Pareto principle, we prioritize the implementation of APIs that are commonly used in most projects and support other APIs based on user needs.

## What are the advantages of Rspack compared to webpack + SWC-loader?

Even if webpack + SWC-loader solves the performance problem of babel-loader, webpack itself still has many performance bottlenecks, such as the make and seal stages, which are single-threaded. However, Rspack breaks through these limitations, so Rspack has better performance than webpack + SWC-loader, especially in multi-core scenarios.

## Do custom plugins and custom loaders need to be developed using Rust?

You can develop plugins and loaders using JavaScript, just like developing webpack plugins and loaders. Meanwhile, Rspack also supports developing plugins and loaders using Rust. Please refer to [rspack-binding-template](https://github.com/rstackjs/rspack-binding-template).



---
url: /misc/glossary.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Glossary

Below are some common terms used with Rspack and webpack.

## asset

An asset is a resource that is used in your application, such as images, fonts, videos, etc. They typically end up as files in your output directory which may need further processing such as being transformed into base64 string and inlined in the output bundle.

## asset module

An "asset module" is a special module type used to process static assets, such as pictures, fonts, videos, etc.

- [Asset modules](/guide/features/asset-module.md)

## async chunk

An async chunk refers to a [chunk](#chunk) that is loaded asynchronously. When you use dynamic imports, Rspack will bundle the module into an async chunk.

## bundle

Historically bundlers produced a single output file called a "bundle." The concept of chunks was introduced later as part of a feature for automatically decomposing bundles into smaller files that can be loaded on demand.

## bundle splitting

Bundle splitting is a technique that allows you to split or merge your code into multiple bundles, which is useful for parallel request and better browser caching, it's not used for reducing the initialize bundle size.

- [Code splitting](/guide/optimization/code-splitting.md)

## built-in module type

In Rspack, built-in module types refer to module types that can be supported without relying on loaders or plugins, such as JavaScript, CSS, JSON, Assets, etc. However, module types that require loaders or plugins to support, such as TypeScript, HTML, Markdown, YAML, etc., are not built-in module types.

- [Asset modules](/guide/features/asset-module.md)
- [CSS](/guide/languages/css.md)
- [JSON](/guide/languages/json.md)
- [rules\[\].type](/config/module-rules.md#rulestype)

## chunk

In bundling terminology, a chunk is a group of modules that get combined into a single data file. Rspack will bundle the modules that are related to each other into a chunk, and then generate a corresponding file.

## chunk graph

Chunk graph is a data structure that represents the relationship between chunks. It is a directed graph, and each node in the graph represents a chunk, and each edge represents the dependency relationship between chunks.

## code splitting

Code splitting is a technique that allows you to split your code into multiple chunks, and only load the necessary chunks when the application is running. This can help you reduce the size of the initial bundle and speed up the application load time.

- [Code splitting](/guide/optimization/code-splitting.md)

## context module

A context module represents a set of modules that can be loaded through a dynamic request. Rspack creates one for expressions such as `import('./locales/' + name + '.js')` and for [`require.context()`](/api/runtime-api/module-methods.md#requirecontext). It defines which directory to search, whether to search subdirectories, and which relative requests are available.

## dependency

Dependency is parsed from the transformed code of a module. It is used to store the import relationships of modules for recursively generating the module graph. When code generation, it can inject code of module imports and exports. It can also be used for code replacement and injecting runtime requirements.

## initial chunk

Initial chunk is a [chunk](#chunk) that is loaded synchronously, including the entry module of the page and the modules imported statically.

## loader

In bundling terminology, a loader is like a plugin but specifically tasked with transforming module content. For example, we can use a loader to transform a TypeScript module into a JavaScript module, or to transform a CSS module into a JavaScript module that injects the CSS into the page.

- [Loader](/guide/features/loader.md)

## module

An application can be split into multiple files called modules, which may be JavaScript source files or other assets such as images or CSS. These files can share and reuse module content by importing and exporting, which helps organize your code into independent parts and define formalized interfaces for communication between them.

## module type

A module's type determines how it will be parsed and handled by the bundler. For example, we can tell Rspack that the module is a JavaScript module by specifying the module type as JavaScript, and Rspack will use the JavaScript parser to parse the module. If the specified module type is CSS, then Rspack will use a CSS parser to parse the module.

- [rules\[\].type](/config/module-rules.md#rulestype)

## module specifier

A module specifier is a string that can be resolved to a path to the module file. For example, in the following code, `./modules/foo.js` is a module specifier.

```js
import { foo } from './modules/foo.js';
```

## module resolution

Module resolution is the process of calculating the file path indicated by a module specifier. For example, an import statement includes a module specifier, and Rspack will use the module resolution algorithm to find the corresponding file path.

- [Module resolution](/guide/features/module-resolution.md)

## module graph

> module graph is also called dependency graph.

The module graph is a graph data structure that represents relationships between modules. It is a directed graph, where each node in the graph represents a module, and each edge represents the dependency relationship between modules.

## NAPI-RS

[NAPI-RS](https://napi.rs/) is a framework for building pre-compiled Node.js addons in Rust. It simplifies the process of creating and publishing native Node.js addons by providing a high-level abstraction over the Node-API.

## plugin

A plugin is a program module that can be used to extend the functionality of Rspack by means of extensibility hooks. It can be used to customize the build process, or to integrate with other tools. Rspack provides lots of hooks which you can use to customize the build process.

- [Plugin](/guide/features/plugin.md)

## runtime

The runtime is all the code Rspack needs to connect your modularized application while it's running in the browser or other environments. It contains the loading and resolving logic needed to connect your modules as they interact.

- [optimization.runtimeChunk](/config/optimization.md#optimizationruntimechunk)

## scope hoisting

Scope hoisting is a technique that concat modules into a single scope when possible, rather than wrapping each module in a separate function. It can make minification more effective and improve runtime performance by reduce module lookup cost.

- [optimization.concatenateModules](/config/optimization.md#optimizationconcatenatemodules)

## tree shaking

Tree shaking is a technique that allows you to remove unused code from your bundle. It a form of compiler dead code elimination, with a focus on minimizing processing of dead code. Compilers like Rspack will accomplish this by analyzing the static structure of your code, and then removing the unused code.

- [Tree shaking](/guide/optimization/tree-shaking.md)



---
url: /misc/planning/future.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Future behavior

## Breaking changes

During the 0.y.z phase, Rspack may include breaking changes only when upgrading the minor (y) version, and ensures backward compatibility when upgrading the patch (z) version.

After reaching version 1.0.0, we will adhere to [semver](https://semver.org/) for version management.

## Deprecation


| Stage | Version | Description |
| --- | --- | --- |
| **Deprecated***default value ~unchanged~* | Current version | It's open for migration. The default behavior remains **unchanged**. |
| **Deprecated***default value ~applied~* | Next minor | The default behavior is **changed** to the latest one. Turning off this new behavior is still an option, but you should migrate to the new behavior as soon as possible. |
| **Removed** | Minor/Major after next minor | The migration should be completed. The old behavior and its corresponding option is **removed**. At the time, please refer to the migration guide or release note for the new behavior. |




---
url: /misc/planning/roadmap.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Roadmap

This document outlines the current direction of Rspack and will continue to evolve alongside future releases.

> Last updated: 2026-04

## Advanced output optimization

Rspack prioritizes stable output behavior in its default optimization pipeline. In areas such as side effects analysis, it intentionally takes a conservative approach. This trade-off works well for most projects, but there is still room to push optimization further in scenarios where bundle size matters most.

Rspack already supports fine-grained optimizations based on pure annotations. Going forward, we will continue improving tree shaking and provide optimization controls with clearer boundaries and more explicit trade-offs, so users can choose the level of optimization that best fits their needs.

We also plan to incorporate more static type information into optimization analysis, drawing on ideas from projects such as Prepack, Closure Compiler, and React Compiler. The goal is to bring more optimization-relevant signals from source code into the bundling pipeline.

For code splitting, we will continue exploring finer-grained strategies. Today, the smallest practical unit of splitting is still usually the module, which means partially reused modules can still introduce unnecessary loading. We plan to explore approaches inspired by tools such as esbuild and Turbopack, including module-level partitioning based on actual reuse patterns, while keeping cache stability, debugging experience, and runtime behavior predictable. We will also explore new loading strategies alongside emerging module capabilities such as `import defer`.

## Improving build performance

Rspack will continue improving its core algorithms, data structures, and incremental build paths. In real-world projects, however, bottlenecks are often not limited to the bundling pipeline itself. They also come from surrounding tools such as linters, type checkers, and Tailwind CSS.

For that reason, our performance work will not focus only on the Rspack core. We will continue improving related tools across the Rstack ecosystem as well. For example, in Rslint we are exploring linting and type checking based on tsgo as an alternative to the common `eslint-webpack-plugin` and `ts-checker-rspack-plugin` combination, with the goal of improving the performance of the overall build pipeline.

## Support for agents

More developers are already using coding agents for bundling-related tasks such as performance analysis, output optimization, and automated migration. We have started supporting these workflows through [Rstack Skills](https://github.com/rstackjs/agent-skills). At the same time, it has become increasingly clear that effective AI-assisted problem solving in bundling depends on three things: access to accurate context, reliable reproduction of issues, and fast, low-cost hypothesis validation.

Going forward, this work will focus on four areas:

- Improving debugging capabilities so coding agents can investigate issues with Rspack debug builds and connect compile-time information with runtime behavior.
- Improving diagnostic output by exposing more machine-readable compilation data, including bailout reasons in optimization stages such as tree shaking and scope hoisting, as well as module, chunk, and plugin pipeline information for automated analysis.
- Improving context collection and issue reproduction by exposing resolved configuration results, environment details, and key compilation paths, so AI-generated suggestions can be reproduced and verified more reliably.
- Shortening the feedback loop by exploring more efficient compilation modes for agent-driven workflows, reducing the cost of iterative validation.

## More modern output formats

Rspack has historically maintained compatibility with webpack’s output formats. This is important for migration correctness and ecosystem compatibility, but it also means carrying forward some historical design constraints. Supporting formats such as CJS, UMD, and ESM alongside runtime features such as HMR and Module Federation often forces traditional bundlers to trade off readability against how well generated code can be analyzed by downstream tools.

Looking ahead, while preserving key runtime capabilities, we will continue exploring more modern output forms, including cleaner ESM output and organizational patterns based on emerging standards such as import maps and module fragments.

## Keeping up with community standards and platform capabilities

The JavaScript ecosystem continues to evolve, and new syntax, module capabilities, and runtime APIs keep maturing. Rspack will continue to follow these changes closely, including support for features such as `import.meta` and `import defer`.

## Supporting higher-level frameworks

Modern bundlers are no longer only responsible for turning modules into bundles. For frameworks and higher-level tooling, they increasingly need to handle responsibilities such as multi-environment compilation, server/client boundary analysis, style and asset collection, and runtime coordination.

Rspack already provides experimental support for React Server Components. Going forward, we will continue turning more of these capabilities into stable foundational primitives, reducing the integration cost for higher-level frameworks and tools while lowering the amount of adapter code they need to maintain.

## Community collaboration

Rspack has already helped address many performance and efficiency problems in practice, and we hope it can continue to be useful to a broader range of projects. We look forward to deeper collaboration with framework and tooling teams across the ecosystem. If your framework or toolchain is interested in working with Rspack, feel free to reach out.



---
url: /misc/team/core-team.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Core team

The development of Rstack is led by ByteDance's web infra team and driven together with community contributors on several core projects, including [Rspack](https://github.com/web-infra-dev/rspack), [Rsbuild](https://github.com/web-infra-dev/rsbuild), [Rspress](https://github.com/web-infra-dev/rspress), [Rsdoctor](https://github.com/web-infra-dev/rsdoctor), [Rslib](https://github.com/web-infra-dev/rslib), [Rstest](https://github.com/web-infra-dev/rstest) and [Rslint](https://github.com/web-infra-dev/rslint).

Current members of the Rstack team are listed in random order below.

## Members


## Emeriti members

You can find the past team members and other people who significantly contributed to Rspack over the years on the [Emeriti members](/misc/team/emeriti.md) page.



---
url: /misc/team/emeriti.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Emeriti members

We'd like to recognize a few people who have made significant contributions to Rspack and its ecosystem in the past and have helped maintain them over the years.

## Members




---
url: /misc/team/join-us.md
---

> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Join us

## 🏄 Who we are

We are the Web Infra team at ByteDance, serving the entire company's Web ecosystem. Our vision is to **create a world-class Web technology system, providing ByteDance products with the ultimate user and developer experience**.

We firmly believe that Web technology is one of the greatest things. The Web Infra team is dedicated to providing better tools, making Web development easier, enabling developers to enjoy a better development experience, and users to enjoy a better user experience. At the same time, open source has always been something we explore in the long term.

We have created a series of Web tools to enhance development efficiency and experience, including but not limited to:

- **JavaScript toolchain** — [Rstack](/guide/start/ecosystem.md#rstack) is a unified JavaScript toolchain centered on Rspack, with high performance and consistent architecture.
- **Next-generation products from an AI-first perspective**, including [Midscene.js](https://midscenejs.com), exploring the application of AI in the Web field.
- **High-performance Web solutions**, which go beyond the traditional Web. Breaking through the conventional WebView and combining with the end, browser kernel, we continue to explore various end performance optimization methods, allowing developers to enjoy optimization capabilities at an extremely low cost.
- **Modern Web engineering system**, including a React-based progressive Web development framework, monorepo solutions, and micro-frontend/micro-module solutions.

Currently, these tools are widely used and well-received within ByteDance. At the same time, several projects have been open-sourced to GitHub, where they are being built and developed together with the community developers.

## 🌟 Team culture

The Web Infra team advocates for an **open-source, technology-driven, and value-oriented** work philosophy:

- Open Source:
  - Freely communicate with colleagues within and outside the team, and explore various directions within the team.
  - The team promotes sharing, turning one person's experience into the team's knowledge.
  - Actively embrace the community, expand and extend based on community technology, and give back to the community.
- Technology-Driven:
  - Professionalism is the guarantee for solving various problems. The team focuses on technology exploration, expanding the technological horizon, and injecting more possibilities into the development of the Web ecosystem.
- Value-Oriented:
  - Combine technological development with business growth, transform technological outcomes into business value, and provide input for the development and iteration of technology.

## 🙋 Who's on the team

Visit [Core Team](/misc/team/core-team.md) to learn more about our team members.

## ⛺️ Where we are

Currently, we have established R\&D centers in four locations: US - Seattle, China - Beijing / Shanghai / Hangzhou.

## 🍭 Position information

The Web Infra team is looking for experienced front-end engineers to join us in developing high-performance front-end tools and new products with an AI-first approach. This will enhance the development experience for both developers and users. As a member of the Web Infra team, you will:

- Design and develop web tools, including but not limited to: web development frameworks, Rust bundlers, etc.
- Build a universal and open-source modern web engineering system, engineering solutions, and best practices.
- Help web developers improve efficiency and quality by exploring, introducing, and ensuring the best practices and new technological solutions.
- Keep up with changes in the front-end community, practice the latest front-end technologies, and incorporate them into architectural design.
- Collaboratively explore the next generation of products from an AI-first perspective.

Currently recruiting positions include:

- [Senior Frontend Engineer/Expert - Web Application Framework](https://jobs.bytedance.com/experienced/position/7304543939385264410/detail)
- [Senior Frontend Engineer - AI Technology Products](https://jobs.bytedance.com/experienced/position/7304543509947091251/detail)
- [Frontend Technology Expert - Build Tools & Compiler](https://jobs.bytedance.com/experienced/position/7304543984570370341/detail)
- [Frontend Technology Expert - Lynx Frontend Framework](https://jobs.bytedance.com/experienced/position/7304543795609241907/detail)

## 📌 Position requirements

- Proficient in the technology stack based on the React ecosystem and Node.js ecosystem.
- Continuously focus on mainstream technologies, cutting-edge fields, and best practices in the global technology community.
- Experience in developing compilation tools and front-end foundational engineering.
- Active community involvement and experience with open-source projects.
- Bonus points for:
  - Experience in Rust / Go / C++ / Node.js Native Addon development.
  - Participation in open-source projects of the Web Infra team.
  - Familiarity with mainstream models and products in the AI field, and keeping up with the latest developments in the area.

## 🌈 Compensation & benefits

- Deep involvement in the construction of open-source projects to enhance professional influence.
- Collaborate with top open-source projects and developers within the community to advance the development of Web technologies.
- Competitive salary and stock options.
- Comprehensive medical insurance packages.

## 📩 Resume submission

Please send your resume to **`web-infra-careers@bytedance.com`**. We look forward to having you join us!

If you have any questions about the position or the team, feel free to communicate with us through the following channels:

- [Discord](https://discord.gg/sYK4QjyZ4V)
- [Feishu Group](https://applink.feishu.cn/client/chat/chatter/add_by_link?link_token=131he762-7608-4553-825d-02a0be3ffe75)