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

import compare from '../../../public/compare.png';
import rspackAudio from '../../../public/rspack.mp3';

<audio id="rspack-audio">
  <source src={rspackAudio} type="audio/mpeg"></source>
</audio>

# Introduction

<div>
  <span>Rspack (pronounced as `/'ɑrespæk/`, </span>
  <button
    style={{
      border: 'none',
      padding: '3px',
      verticalAlign: 'middle',
      display: 'inline',
    }}
    id="play-rspack-audio"
    onClick={() => {
      document.getElementById('rspack-audio').play();
    }}
  >
    <svg
      xmlns="http://www.w3.org/2000/svg"
      width="16"
      height="16"
      viewBox="0 0 32 32"
    >
      <path
        fill="currentColor"
        d="m27.16 8.08l-1.53 1.29a10 10 0 0 1-.29 13.23l1.47 1.4a12 12 0 0 0 .35-15.88Z"
      />
      <path
        fill="currentColor"
        d="M21.58 12a6 6 0 0 1-.18 7.94l1.47 1.36a8 8 0 0 0 .23-10.59zM18 30a1 1 0 0 1-.71-.3L9.67 22H3a1 1 0 0 1-1-1V11a1 1 0 0 1 1-1h6.67l7.62-7.7a1 1 0 0 1 1.41 0a1 1 0 0 1 .3.7v26a1 1 0 0 1-1 1zM4 20h6.08a1 1 0 0 1 .71.3L17 26.57V5.43l-6.21 6.27a1 1 0 0 1-.71.3H4z"
      />
    </svg>
  </button>
  <p style={{ display: 'inline', lineHeight: '1.75rem' }}>
    <span>) is a high performance JavaScript bundler</span>
    <span>&nbsp;written in Rust. It offers strong</span>
    <span>&nbsp;compatibility with the webpack ecosystem,</span>
    <span>&nbsp;allowing for seamless replacement of webpack,</span>
    <span>&nbsp;and provides lightning fast build speeds.</span>
  </p>
</div>

## 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), 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](/guide/compatibility/plugin), more than 85% can be used in Rspack or have an alternative.

:::tip Learn more

- See [Rspack blogs](/blog/index) for the latest updates on Rspack.
- See [Roadmap](/misc/planning/roadmap) 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

[Vite](https://vitejs.dev/) offers a great developer experience, but its reliance on [Rollup](https://rollupjs.org/) for production builds faces similar performance costs to other JavaScript-based approaches. The same tradeoffs of webpack versus Rollup also apply, such as missing flexibility from the [optimization.splitChunks](/config/optimization#optimizationsplitchunks) feature.

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

Rspack and Rollup are both bundling tools, but they focus on different areas. Rollup is more suitable for bundling libraries, while Rspack is more suitable for bundling applications. Therefore, Rspack has optimized many features for bundling applications, such as HMR and bundle splitting. Rollup produces ESM outputs that are more friendly to libraries than Rspack. There are also many tools in the community that encapsulate Rollup to some extent and provide more friendly support for bundling applications, such as Vite. Currently, Rspack has better production build performance than Rollup.

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

## Next steps

Please read [Quick start](/guide/start/quick-start) 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
---

import { PackageManagerTabs } from '@theme';

# 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) 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 has the following Node.js version requirements:

- `@rspack/cli >= v1.0.0` requires Node.js 18.12.0 or higher.
- `@rspack/core >= v1.5.0` requires Node.js 18.12.0 or higher.
- `@rspack/core < v1.5.0` requires Node.js 16.0.0 or higher.

:::

## 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:

<PackageManagerTabs command="create 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:

<PackageManagerTabs command="create 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
```

## Online examples

We provide an online example based on Rsbuild. The example gives an intuitive feel for the build performance of Rspack and the development experience of Rsbuild:

- [Rsbuild CodeSandbox example](https://codesandbox.io/p/github/rstackjs/rsbuild-codesandbox-example)

Here we also provide an online example based on Wasm and WebContainer on StackBlitz:

- [Rsbuild StackBlitz Example](https://stackblitz.com/~/github.com/rstackjs/rsbuild-stackblitz-example)

## 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:

<PackageManagerTabs command="add @rspack/core @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) 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)
- [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)

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

import { Tag } from '@components/Tag';

# Ecosystem

## Rstack

Rstack is a unified JavaScript toolchain centered on Rspack, with high performance and consistent architecture.

### Rsbuild

<Tag color="geekblue">Build tool</Tag>

[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

<Tag color="geekblue">Library development tool</Tag>

[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

<Tag color="geekblue">Static site generator</Tag>
<Tag color="purple">React</Tag>

[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

<Tag color="geekblue">Build analyzer</Tag>

[Rsdoctor](https://github.com/web-infra-dev/rsdoctor) 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

<Tag color="geekblue">Testing framework</Tag>

[Rstest](https://github.com/web-infra-dev/rstest) 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

<Tag color="geekblue">Linter</Tag>

[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

<Tag color="geekblue">Build tool</Tag>
<Tag color="purple">Angular</Tag>

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

### Docusaurus

<Tag color="geekblue">Static site generator</Tag>
<Tag color="purple">React</Tag>

[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

<Tag color="geekblue">Web framework</Tag>
<Tag color="purple">React</Tag>

[Modern.js](https://modernjs.dev/en/) 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.

### Next.js

<Tag color="geekblue">Web framework</Tag>
<Tag color="purple">React</Tag>

[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/tech/next) for details.

### Nuxt

<Tag color="geekblue">Web framework</Tag>
<Tag color="purple">Vue</Tag>

[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

<Tag color="geekblue">Build system</Tag>
<Tag color="purple">Monorepo</Tag>

[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

<Tag color="geekblue">Build tool</Tag>
<Tag color="purple">Lynx</Tag>

[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

<Tag color="geekblue">Build tool</Tag>
<Tag color="purple">React Native</Tag>

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

### Storybook

<Tag color="geekblue">UI development</Tag>

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

## More

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



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

import { PackageManagerTabs } from '@theme';

# 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:

<PackageManagerTabs
  command="skills add rstackjs/agent-skills --skill rspack-best-practices"
  dlx
/>

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

You are an expert in JavaScript, Rspack, and web application development. You write maintainable, performant, and accessible code.

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

import { Tabs, Tab } from '@theme';

# Plugins

If [loaders](/guide/features/loader) 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) 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:

<Tabs>
  <Tab label="ESM">

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

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

  </Tab>
  <Tab label="CJS">

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

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

  </Tab>
</Tabs>

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

You can also refer to [Plugin compat](/guide/compatibility/plugin) 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):

<Tabs>
  <Tab label="ESM">

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

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

  </Tab>
  <Tab label="CJS">

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

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

  </Tab>
</Tabs>

### SWC plugins

In the built-in [swc-loader](/guide/features/builtin-swc-loader) of Rspack, you can use SWC's Wasm plugins, see [jsc.experimental.plugins](/guide/features/builtin-swc-loader#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).

<Tabs>
  <Tab label="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!');
    });
  }
}
```

  </Tab>
  <Tab label="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;
```

  </Tab>
</Tabs>

### 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!');
    });
  }
}
```



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

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

### 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)
- [builtin:lightningcss-loader](/guide/features/builtin-lightningcss-loader)



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

# Dev server

Rspack CLI comes with a built-in `@rspack/dev-server` for development and debugging. Its capabilities are similar to `webpack-dev-server`, including features like hot module replacement (HMR), proxy server and more.

:::tip

`webpack-dev-server@5` is used in `@rspack/dev-server`, which has some differences from `webpack-dev-server@4`.

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

:::

### 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#outputcssfilename), otherwise CSS HMR may not work.
:::

### Proxy

Rspack has a built-in simple proxy server. You can enable the proxy server by configuring the `devServer.proxy` option in Rspack configuration. The devServer internally uses [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware) to implement the proxy function. 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.html).



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

# 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#moduleparserasset) to modify the global configuration, or use [`rules[].parser.dataUrlCondition`](/config/module-rules#rulesparserdataurlcondition) 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
---

# Asset base path

Rspack provides the [output.publicPath](/config/output#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 `__webpack_public_path__` in your JavaScript code.

The `__webpack_public_path__` 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"
__webpack_public_path__ =
  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#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
---

# Module resolution

Module resolution is the process of converting a module identifier to a module's file path. The Rust port of enhanced-resolve is used for module path resolution, which is an extension to the [node module resolution algorithm](https://nodejs.org/api/modules.html#modules_all_together) with the same interface as [enhanced-resolve](https://github.com/webpack/enhanced-resolve), refer to [resolve configuration](/config/resolve) 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.



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

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

You can use it through Rspack's [ModuleFederationPlugin](/plugins/webpack/module-federation-plugin) 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/webpack/module-federation-plugin-v1).

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



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

import WebpackLicense from '@components/WebpackLicense';
import { ApiMeta, Stability } from '@components/ApiMeta.tsx';
import { Tabs, Tab } from '@theme';

<WebpackLicense from="https://webpack.js.org/guides/web-workers/" />

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

### Additional syntax

In addition to `new Worker()`, Rspack also supports the following syntax 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 "node:worker_threads"`: commonly used in Node.js environments, see [Worker threads](https://nodejs.org/api/worker_threads.html)

```js
import { Worker } from 'node: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('./sw.js').then((registration) => {
  console.log('Service worker registration succeeded:', registration);
});
```

To support additional custom syntax, you can configure it through [`module.parser.javascript.worker`](/config/module#moduleparserjavascriptworker).

### Examples

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)

### Notes

1. Note that `new Worker` can also accept a string representation of a URL, but only passing in URLs is supported in Rspack.
2. Rspack does not support the use of variables 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);
   ```

   This is because Rspack cannot statically analyze the syntax. Please be sure to note this limitation when using the Worker syntax in Rspack.

3. Not support `/* webpackEntryOptions: { filename: "workers/[name].js" } */` magic comments for now.

## 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) to replace worker-loader with worker-rspack-loader:

<Tabs>
  <Tab label="ESM">
```js title="rspack.config.mjs"
import { createRequire } from 'module';

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

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

  </Tab>
  <Tab label="CJS">

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

  </Tab>
</Tabs>



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

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

## Filtering modules

In addition to two options `entries` and `imports`, you can also use a `test` option to filter out certain modules for lazy compilation.

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);
    },
  },
});
```

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

## Integrating with custom server

When using Rspack CLI, the `lazyCompilation` option is actually processed by `@rspack/cli`. It adds an [Express-style middleware](https://expressjs.com/en/guide/using-middleware.html) to dev server to handle lazy compilation requests from client.

If you are using a custom dev server, you will need to manually integrate `rspack.lazyCompilationMiddleware` into your dev 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) instance, use `lazyCompilation` config from it.

:::tip
Prior to Rspack 1.7, this middleware was only available via `rspack.experiments.lazyCompilationMiddleware`.
:::

## Customizing lazy compilation endpoint

By default, the lazy compilation middleware uses the `/lazy-compilation-using-` prefix for handling requests. If you need to customize this prefix, you can use the `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/features/builtin-swc-loader.md
---

import { ApiMeta, Stability } from '@components/ApiMeta';

# Builtin 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: /\.ts$/,
        exclude: [/node_modules/],
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            parser: {
              syntax: 'typescript',
            },
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
};
```

### JSX transpilation

To transpile React's `.jsx` files:

```js title="rspack.config.mjs"
export default {
  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,
                },
              },
            },
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
};
```

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

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

### jsc.experimental.plugins

<ApiMeta stability={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) 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'),
              },
            },
          },
        },
      },
    ],
  },
};
```

### rspackExperiments

Experimental features provided by rspack.

### rspackExperiments.import

<ApiMeta stability={Stability.Experimental} />

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: [
      {
        use: 'builtin:swc-loader',
        options: {
          rspackExperiments: {
            import: [
              {
                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: [
      {
        use: 'builtin:swc-loader',
        options: {
          rspackExperiments: {
            import: [
              {
                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: [
      {
        use: 'builtin:swc-loader',
        options: {
          rspackExperiments: {
            import: [
              {
                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: [
      {
        use: 'builtin:swc-loader',
        options: {
          rspackExperiments: {
            import: [
              {
                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';
```

### collectTypeScriptInfo

<ApiMeta addedVersion="1.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.

:::tip
Before Rspack 1.7, the [rspackExperiments.collectTypeScriptInfo](/config/deprecated-options#experimentscollecttypescriptinfo) option could be used.
:::

#### collectTypeScriptInfo.typeExports

<ApiMeta addedVersion="1.7.0" />

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

Whether to collect type exports information for [`typeReexportsPresence`](/config/module#moduleparserjavascripttypereexportspresence). 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

<ApiMeta addedVersion="1.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 {
  experiments: {
    inlineEnum: true, // This is currently an experimental feature and requires explicit enabling
  },
  module: {
    rules: [
      {
        test: /\.ts$/,
        use: [
          {
            loader: 'builtin:swc-loader',
            options: {
              jsc: {
                parser: {
                  syntax: 'typescript',
                },
              },
              collectTypeScriptInfo: {
                exportedEnum: isProduction,
              },
            },
          },
        ],
      },
    ],
  },
};
```

Since this feature relies on module export usage information ([optimization.usedExports](/config/optimization#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
---

import { ApiMeta, Stability } from '@components/ApiMeta';

# Builtin lightningcss-loader

<ApiMeta addedVersion="1.0.0" />

[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 LightningcssLoaderOptions = {
  minify?: boolean;
  errorRecovery?: boolean;
  targets?: string[] | string;
  include?: LightningcssFeatureOptions;
  exclude?: LightningcssFeatureOptions;
  /**
   * @deprecated Use `drafts` instead.
   * This will be removed in the next major version.
   */
  draft?: Drafts;
  drafts?: Drafts;
  nonStandard?: NonStandard;
  pseudoClasses?: PseudoClasses;
  unusedSymbols?: Set<String>;
};
```

### targets

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

Browserslist query string.

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%'],
  },
};
```

### 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#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/esm.md
---

import { Stability } from '@components/ApiMeta';

# 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#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',
  },
  experiments: {
    outputModule: true,
  },
};
```

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), you need to configure the following:

```js title="rspack.config.mjs"
export default {
  //...
  output: {
    module: true,
    chunkFormat: 'module',
    library: {
      type: 'modern-module',
    },
    chunkLoading: 'import',
    workerChunkLoading: 'import',
  },
  externalsType: 'module-import',
  optimization: {
    concatenateModules: true,
    avoidEntryIife: true,
    minimize: false,
  },
  experiments: {
    outputModule: true,
  },
};
```

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

Currently, Rspack's ESM support is still being improved. In certain use cases, you may encounter integration issues between ESM and other features. The main limitations include:

1. Lack of static analysis friendly code splitting support
2. Limited custom chunk splitting support in ESM format
3. Lack of module-level side effect information preservation, affecting tree-shaking accuracy
4. Re-exports of external modules (`export * from '...'`) cannot be properly preserved in ESM format

We are continuously improving Rspack's ESM support to provide a comprehensive solution that addresses existing issues and makes ESM usage more simple and intuitive, better embracing the modern JavaScript module system.

## 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#outputmodule): Set to `true` to generate ESM format output. When this option is enabled, it affects the following configurations:
   1. Affects [externalsType](/config/externals#externalstype) default value: When `output.module` is `true`, `externalsType` defaults to `'module-import'`
   2. Affects [output.filename](/config/output#outputfilename) default value: When `output.module` is `true`, the default filename is `'[name].mjs'` instead of `'[name].js'`
   3. Affects [output.chunkFilename](/config/output#outputchunkfilename) default value: When `output.module` is `true`, chunk filename defaults to `'[id].mjs'` instead of `'[id].js'`
   4. Affects [output.hotUpdateChunkFilename](/config/output#outputhotupdatechunkfilename) default value: When `output.module` is `true`, defaults to `'[id].[fullhash].hot-update.mjs'`
   5. Affects [output.hotUpdateMainFilename](/config/output#outputhotupdatemainfilename) default value: When `output.module` is `true`, defaults to `'[runtime].[fullhash].hot-update.json.mjs'`
   6. Affects [output.iife](/config/output#outputiife) default value: When `output.module` is `true`, `output.iife` defaults to `false`
   7. Affects [output.library.type](/config/output#outputlibrarytype) default value: When `output.module` is `true`, defaults to `'module'` instead of `'var'`
   8. Affects [output.scriptType](/config/output#outputscripttype) default value: When `output.module` is `true`, defaults to `'module'`
   9. Affects [output.environment.dynamicImport](/config/output#outputenvironmentdynamicimport) default value: Enabled when `output.module` is `true`
   10. Affects [output.environment.dynamicImportInWorker](/config/output#outputenvironmentdynamicimportinworker) default value: Enabled when `output.module` is `true`
   11. Affects [output.environment.module](/config/output#outputenvironmentmodule) 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#outputchunkformat): Set to `'module'` to use ESM format.
3. [output.library.type](/config/output#outputlibrarytype): Set to `'modern-module'` for additional optimization of library ESM output format.
4. [output.chunkLoading](/config/output#outputchunkloading): Set to `'import'` to use ESM `import` for loading chunks.
5. [output.workerChunkLoading](/config/output#outputworkerchunkloading): Set to `'import'` to use ESM `import` for loading workers.
6. [optimization.concatenateModules](/config/optimization#optimizationconcatenatemodules): modern-module depends on this option being enabled to ensure the output supports good tree-shaking and correct library exports.
7. [optimization.avoidEntryIife](/config/optimization#optimizationavoidentryiife): In some cases, Rspack wraps ESM output in an IIFE, which breaks ESM's modular characteristics.
8. [experiments.outputModule](/config/experiments#experimentsoutputmodule): Enable the experimental feature required for output.module.
9. [HtmlWebpackPlugin.scriptLoading](/guide/tech/html#htmlwebpackplugin): Set to `'module'` to use ESM `<script type="module">` for loading `.mjs` modules.



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

# Layer

Layer is a powerful feature provided by Rspack that allows you to categorize and manage modules. 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#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#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#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#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/tech/typescript.md
---

# TypeScript

## How to use

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

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.ts$/,
        exclude: [/node_modules/],
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            parser: {
              syntax: 'typescript',
            },
          },
        },
        type: 'javascript/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).

```js title="rspack.config.mjs"
export default {
  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,
                },
              },
            },
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
};
```

## Alias

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

## Client types

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

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"
   console.log(import.meta.webpackContext); // 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/tech/css.md
---

import { PackageManagerTabs } from '@theme';

# 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 provides the [experiment.css](/config/experiments#experimentscss) option, an experimental feature introduced in webpack 5 to enable built-in CSS support. Rspack has improved this feature and plans to enable it by default in Rspack 2.0.

> If you create a new project based on Rspack, it is recommended to use this method.

```js title="rspack.config.mjs"
export default {
  experiments: {
    css: true,
  },
};
```

After enabling `experiment.css`, Rspack will support the following three module types, which you can set on the `rule` using `type`:

- `css`: Used to handle normal CSS files.
- `css/module`: Used to handle [CSS Modules](#css-modules).
- `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` are treated as CSS Modules.

For files ending in `*.css`, Rspack will treat them as `type: 'css/auto'` by default. 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'],
      },
    ],
  },
};
```

### Using CssExtractRspackPlugin

Rspack supports using [css-loader](https://github.com/webpack/css-loader) and [CssExtractRspackPlugin](/plugins/rspack/css-extract-rspack-plugin) 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:

<PackageManagerTabs command="add 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#mini-css-extract-plugin--rspackcssextractrspackplugin) to learn how to migrate from webpack.

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

### 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:

<PackageManagerTabs command="add css-loader 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'`, or `type: 'css/module'` as these types are provided by `experiments.css`.
:::

## 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:

- [module.parser.css](/config/module#moduleparsercss): Configure the parsing of CSS Modules.
- [module.generator.css](/config/module#modulegeneratorcss): Configure the generation of CSS Modules.

:::

### 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:

<PackageManagerTabs command="add postcss 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:

<PackageManagerTabs command="add sass-embedded 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:

<PackageManagerTabs command="add less 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/tech/html.md
---

# HTML

Rspack supports generating HTML files using the following plugins, and automatically injecting the generated CSS and JavaScript files into the HTML.
This is particularly useful for Rspack bundles that contain filename hashes, as the hashes can change with each Rspack build.

## HtmlWebpackPlugin

Rspack fully supports [HtmlWebpackPlugin](https://github.com/jantimon/html-webpack-plugin).

```js title="rspack.config.mjs"
import HtmlWebpackPlugin from 'html-webpack-plugin';
import path from 'node:path';

export default {
  entry: 'index.js',
  output: {
    path: path.resolve(__dirname, './dist'),
    filename: 'index_bundle.js',
  },
  plugins: [new HtmlWebpackPlugin()],
};
```

For all configuration options, see the [plugin documentation](https://github.com/jantimon/html-webpack-plugin#options).

## Built-in HtmlRspackPlugin

[HtmlRspackPlugin](/plugins/rspack/html-rspack-plugin) is a high-performance HTML plugin implemented in Rust, offering significantly better build performance than the `HtmlWebpackPlugin`, especially when building a large number of HTML files.

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

export default {
  entry: 'index.js',
  output: {
    path: path.resolve(__dirname, './dist'),
    filename: 'index_bundle.js',
  },
  plugins: [new rspack.HtmlRspackPlugin()],
};
```

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



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

import { ApiMeta, Stability } from '@components/ApiMeta.tsx';

# 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

<ApiMeta addedVersion={'1.0.0-beta.1'} />

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/tech/react.md
---

import { PackageManagerTabs } from '@theme';
import { Stability } from '@components/ApiMeta.tsx';

# 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) loader to support `.jsx` and `.tsx` files:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.jsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'ecmascript',
                jsx: true,
              },
            },
          },
        },
        type: 'javascript/auto',
      },
      {
        test: /\.tsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'typescript',
                tsx: true,
              },
            },
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
};
```

Refer to [builtin:swc-loader](/guide/features/builtin-swc-loader) 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.

<PackageManagerTabs command="add @rspack/plugin-react-refresh 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 ReactRefreshPlugin 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,
                },
              },
            },
          },
        },
      },
    ],
  },
  plugins: [
    isDev && new ReactRefreshPlugin(),
    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.

:::tip
At present, React Compiler only supports Babel compilation, which may slow down the build time.
:::

### How to use

The steps to use React Compiler in Rspack:

1. 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.
2. React Compiler currently only provides a Babel plugin, you need to 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)

3. 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' },
        ],
      },
    ],
  },
};
```

4. 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/).



---
url: /guide/tech/preact.md
---

import { PackageManagerTabs } from '@theme';
import { Stability } from '@components/ApiMeta.tsx';

# 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: /\.jsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'ecmascript',
                jsx: true,
              },
            },
          },
        },
        type: 'javascript/auto',
      },
      {
        test: /\.tsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              parser: {
                syntax: 'typescript',
                tsx: true,
              },
            },
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
};
```

Refer to [Builtin swc-loader](/guide/features/builtin-swc-loader) 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:

<PackageManagerTabs command="add @rspack/plugin-preact-refresh @prefresh/core @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.

:::warning
In versions below 1.0.0, Rspack did not support preact refresh with `swc-loader`.

Please use `builtin:swc-loader` and enable preact specific transformation with `rspackExperiments.preact: {}`
:::

```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: /\.jsx$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            jsc: {
              experimental: {
                plugins: [
                  [
                    '@swc/plugin-prefresh', // enable prefresh specific transformation
                    {
                      library: ['preact-like-framework'], // the customizable preact name, default is `["preact", "preact/compat", "react"]`
                    },
                  ],
                ],
              },
              parser: {
                syntax: 'ecmascript',
                jsx: true,
              },
              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/blob/main/rspack/preact-refresh) for the full example.



---
url: /guide/tech/vue.md
---

import { PackageManagerTabs } from '@theme';

# 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',
      },
    ],
  },
  experiments: {
    css: false, // At this point, you need to turn off `experiments.css` to adapt to the internal processing logic of `vue-loader`
  },
};
```

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 turn off `experiments.css` when configuring Vue 2 projects or 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: /\.ts$/, // add this rule when you use TypeScript in Vue SFC
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            parser: {
              syntax: 'typescript',
            },
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
  experiments: {
    css: false,
  },
};
```

TypeScript is supported using Rspack's native `builtin:swc-loader`, see [this](/guide/features/builtin-swc-loader) 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):

<PackageManagerTabs command="add babel-loader @babel/core @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/vue3-jsx) of Vue JSX for reference.



---
url: /guide/tech/next.md
---

import { Tabs, Tab, PackageManagerTabs } from '@theme';

# 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) blog post to learn more details.
:::

## Installation

Install the `next-rspack` package:

<PackageManagerTabs command="add 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.js` or `next.config.ts`:

<Tabs>
  <Tab label="next.config.ts">

```ts
import withRspack from 'next-rspack';
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  /* config options here */
};

export default withRspack(nextConfig);
```

  </Tab>
  <Tab label="next.config.js">

```ts
const withRspack = require('next-rspack');

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* config options here */
};

module.exports = withRspack(nextConfig);
```

  </Tab>
</Tabs>

> 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.js`, modify Rspack's configuration by adding the following callback function:

```js title="next.config.js"
module.exports = {
  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.js"
const withPlugins = require('next-compose-plugins');
const withRspack = require('next-rspack');

module.exports = withPlugins([
  [withRspack],
  // your other plugins here
]);
```



---
url: /guide/tech/nestjs.md
---

# NestJS

Rspack not only supports building frontend projects but also supports building Node.js App like NestJS.
Rspack provides NestJS [example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/nestjs) for reference.

## 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, special handling is usually required. node-loader can be used to handle addon packaging very well.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.node$/,
        use: [
          {
            loader: 'node-loader',
            options: {
              name: '[path][name].[ext]',
            },
          },
        ],
      },
    ],
  },
};
```



---
url: /guide/tech/solid.md
---

# 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/tech/svelte.md
---

# 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/optimization/analysis.md
---

# Bundle analysis

## Rsdoctor's bundle analysis

[Rsdoctor](/guide/optimization/use-rsdoctor) 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**.

<img
  src="https://assets.rspack.rs/others/assets/rsdoctor/bundle-size.jpg"
  width="700px"
  style={{ margin: 'auto' }}
/>

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

## webpack-bundle-analyzer

Rspack's Command Line Interface (CLI) supports bundle analysis out-of-box via the `--analyze` option. It uses [webpack-bundle-analyzer](https://www.npmjs.com/package/webpack-bundle-analyzer) behind the scenes.

```sh
$ rspack build --analyze
```

## 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://statoscope.tech/):

```sh
$ rspack build --json stats.json
```



---
url: /guide/optimization/code-splitting.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/guides/code-splitting/" />

# 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#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/#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/webpack/split-chunks-plugin#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`.

### Force the splitting of certain modules

We can use [`optimization.splitChunks.cacheGroups.{cacheGroup}.name`](/plugins/webpack/split-chunks-plugin#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.

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.



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

# Lazy barrel

Lazy barrel is a stable optimization feature in Rspack that 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#side-effects-analysis) for more details.

2. Module-level declaration: Modules explicitly marked as side-effect-free through [`rules[].sideEffects`](/config/module-rules#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#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.

## Configuration

Lazy barrel is enabled by default since Rspack 1.6.0. No configuration is needed.

If you're using an older version and have `experiments.lazyBarrel` in your configuration, you can safely remove it:

```diff title="rspack.config.mjs"
export default {
-  experiments: {
-    lazyBarrel: true,
-  },
};
```

:::warning Deprecated configuration
The `experiments.lazyBarrel` configuration option has been deprecated and will be removed in Rspack v2.0.
:::

## 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)
- [Side effects analysis](/guide/optimization/tree-shaking#side-effects-analysis)



---
url: /guide/optimization/production.md
---

# 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) 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) 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/rspack/swc-js-minimizer-rspack-plugin) and [LightningCssMinimizerRspackPlugin](/plugins/rspack/lightning-css-minimizer-rspack-plugin) 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#optimizationminimizer) to set custom minimizers.



---
url: /guide/optimization/profile.md
---

# Build performance profile

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/optimization/use-rsdoctor) 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, and it will contain the `trace.json` file, which is generated by Rspack based on [tracing](https://github.com/tokio-rs/tracing) and can be viewed using [ui.perfetto.dev](https://ui.perfetto.dev/).

> See [Tracing](/contribute/development/tracing) 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), 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#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).

### 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/rspack/swc-js-minimizer-rspack-plugin).

### 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/rspack/lightning-css-minimizer-rspack-plugin).

### 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/rspack/html-rspack-plugin) implemented in Rust by Rspack can provide better performance.

## 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/optimization/tree-shaking.md
---

# 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#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) 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) is set to `production`, Rspack enables several tree shaking optimizations:

- [usedExports](/config/optimization#optimizationusedexports): Detects which module exports are used, enabling removal of unused exports.
- [sideEffects](/config/optimization#optimizationsideeffects): Analyzes modules for side effects. Modules without side effects can be further optimized through re-exports.
- [providedExports](/config/optimization#optimizationprovidedExports): Analyzes all exports and tracks their re-export sources.
- [innerGraph](/config/optimization#optimizationsinnergraph): 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#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#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#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#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#optimizationinnergraph) is set to true.

:::



---
url: /guide/optimization/use-rsdoctor.md
---

# 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:

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @rsdoctor/rspack-plugin -D" />

2. Register the `RsdoctorRspackPlugin` plugin in the [plugins](/config/plugins) 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/webpack.md
---

import { PackageManagerTabs } from '@theme';

# 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).
- For projects using Vue CLI, you can refer to [Rsbuild - Migrating from Vue CLI](https://rsbuild.rs/guide/migration/vue-cli).

## Installing Rspack

In your project directory, install Rspack as a `devDependencies`:

<PackageManagerTabs command="add @rspack/core @rspack/cli -D" />

Now you can remove the webpack-related dependencies from your project:

<PackageManagerTabs command="remove webpack webpack-cli webpack-dev-server" />

:::tip
In some cases, you will still need to keep `webpack` as a dev dependency, such as when using [vue-loader](https://github.com/vuejs/vue-loader) (you can use [rspack-vue-loader](https://github.com/rstackjs/rspack-vue-loader) instead).

This is because these packages directly `import` subpaths of webpack and couple with webpack. If you encounter this issue, you can provide feedback to the maintainers of these plugins, asking them if they can make `webpack` an optional dependency.
:::

## Updating package.json

Update your build scripts to use Rspack instead of webpack:

```diff title="package.json"
{
  "scripts": {
-   "serve": "webpack serve",
-   "build": "webpack build",
+   "serve": "rspack serve",
+   "build": "rspack build",
  }
}
```

## 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 is actively working on implementing webpack's upcoming features, so some configuration defaults differ from webpack 5, as shown below:

| Configuration     | webpack Default | Rspack Default |
| ----------------- | --------------- | -------------- |
| node.global       | true            | 'warn'         |
| node.\_\_filename | 'mock'          | 'warn-mock'    |
| node.\_\_dirname  | 'mock'          | 'warn-mock'    |

You can refer to [Configure Rspack](/config/index) to see the configurations supported by Rspack.

## 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/webpack/define-plugin):

```diff title="rspack.config.js"
- const webpack = require('webpack');
+ const { rspack } = require('@rspack/core');

module.exports = {
  //...
  plugins: [
-   new webpack.DefinePlugin({
+   new rspack.DefinePlugin({
      // ...
    }),
  ],
}
```

See [Webpack-aligned built-in plugins](/plugins/webpack/index) for more information about supported webpack plugins in Rspack.

## Community plugins

Rspack supports most of the webpack community plugins and also offers alternative solutions for some currently unsupported plugins.

Check [Plugin compat](/guide/compatibility/plugin) for more information on Rspack's compatibility with popular webpack community plugins.

### `copy-webpack-plugin`

Use [rspack.CopyRspackPlugin](/plugins/rspack/copy-rspack-plugin) instead of [copy-webpack-plugin](https://github.com/webpack/copy-webpack-plugin):

```diff title="rspack.config.js"
- const CopyWebpackPlugin = require('copy-webpack-plugin');
+ const { rspack } = require('@rspack/core');

module.exports = {
  plugins: [
-   new CopyWebpackPlugin({
+   new rspack.CopyRspackPlugin({
      // ...
    }),
  ]
}
```

### `mini-css-extract-plugin`

Use [rspack.CssExtractRspackPlugin](/plugins/rspack/css-extract-rspack-plugin) 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"
        ],
+       type: 'javascript/auto'
      }
    ]
  }
}
```

### `tsconfig-paths-webpack-plugin`

Use [resolve.tsConfig](/config/resolve#resolvetsconfig) instead of [tsconfig-paths-webpack-plugin](https://github.com/dividab/tsconfig-paths-webpack-plugin):

```diff title="rspack.config.js"
- const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');

module.exports = {
  resolve: {
-   plugins: [new TsconfigPathsPlugin({})]
+   tsConfig: {}
  }
}
```

### `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):

```diff title="rspack.config.js"
- const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');
+ const { TsCheckerRspackPlugin } = require('ts-checker-rspack-plugin');

module.exports = {
  plugins: [
-   new ForkTsCheckerWebpackPlugin()
+   new TsCheckerRspackPlugin()
  ]
}
```

## Loaders

Rspack's loader runner is fully compatible with webpack's loader functionality, supporting the vast majority of webpack loaders.
You can use your existing loaders without any changes. However, to achieve the best performance, consider migrating the following loaders:

### [babel-loader](https://github.com/babel/babel-loader) / [swc-loader](https://swc.rs/docs/usage/swc-loader) → builtin:swc-loader

Using `builtin:swc-loader` offers better performance compared to the `babel-loader` and the external `swc-loader`, as it avoids frequent communication between JavaScript and Rust.

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.

```diff title="rspack.config.js"
module.exports = {
   module: {
     rules: [
-      {
-        test: /\.tsx?$/i,
-        use: [
-          {
-            loader: 'babel-loader',
-            options: {
-              presets: ['@babel/preset-typescript'],
-            },
-          },
-        ],
-        test: /\.jsx?$/i,
-        use: [
-          {
-            loader: 'babel-loader',
-            options: {
-              presets: ['@babel/preset-react'],
-            },
-          },
-        ],
-      },
+      {
+        test: /\.(j|t)s$/,
+        exclude: [/[\\/]node_modules[\\/]/],
+        loader: 'builtin:swc-loader',
+        options: {
+          jsc: {
+            parser: {
+              syntax: 'typescript',
+            },
+            externalHelpers: true,
+            transform: {
+              react: {
+                runtime: 'automatic',
+                development: !prod,
+                refresh: !prod,
+              },
+            },
+          },
+          env: {
+            targets: 'Chrome >= 48',
+          },
+        },
+      },
+      {
+        test: /\.(j|t)sx$/,
+        loader: 'builtin:swc-loader',
+        exclude: [/[\\/]node_modules[\\/]/],
+        options: {
+          jsc: {
+            parser: {
+              syntax: 'typescript',
+              tsx: true,
+            },
+            transform: {
+              react: {
+                runtime: 'automatic',
+                development: !prod,
+                refresh: !prod,
+              },
+            },
+            externalHelpers: true,
+          },
+          env: {
+            targets: 'Chrome >= 48', // browser compatibility
+          },
+        },
+      },
     ],
   },
 };
```

### [file-loader](https://github.com/webpack-contrib/raw-loader) / [url-loader](https://github.com/webpack-contrib/url-loader) / [raw-loader](https://github.com/webpack-contrib/raw-loader) → [Asset Modules](/guide/features/asset-module)

Rspack implements webpack 5's [Asset Modules](https://webpack.js.org/guides/asset-modules), using asset modules to replace `file-loader`, `url-loader`, and `raw-loader` for better performance.

#### file-loader → 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 → 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 → asset/source

```diff title="rspack.config.js"
 module.exports = {
   module: {
     rules: [
-      {
-        test: /^BUILD_ID$/,
-        use: ["raw-loader",],
-      },
+      {
+        test: /^BUILD_ID$/,
+        type: "asset/source",
+      },
     ],
   },
 };
```



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

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

import { PackageManagerTabs } from '@theme';

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

<PackageManagerTabs command="install storybook-react-rsbuild @rsbuild/core @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.

## Limitations

Rspack is gradually improving full support for Storybook. Currently, there are some capabilities that are not supported, see [storybook-rsbuild - Roadmap](https://github.com/rstackjs/storybook-rsbuild#roadmap) for details.



---
url: /guide/migration/rspack_0.x.md
---

# Migrating from Rspack 0.x

The document lists all breaking changes from Rspack v0.7 to v1.0. You can refer to this document for migration.

> See [Breaking changes in Rspack v1.0.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

The default value of [experiments.css](/config/experiments#experimentscss) has been changed from `true` to `false`.

In Rspack 0.x, `experiments.css` was enabled by default, which means files ending with`*.css`were automatically treated as`type: 'css/auto'` without needing to manually include other loaders to process CSS files.

If you rely on the built-in feature to handle CSS files without using any loaders, or if you have used the following configuration to handle CSS files:

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

Please note that you now need to manually enable `experiments.css`.

### [Important] optimization.concatenateModules

The default value of [optimization.concatenateModules](/config/optimization#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) 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#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/webpack/split-chunks-plugin#splitchunkscachegroupscachegroupreuseexistingchunk) has been changed from `true` to `false`.

### optimization.moduleIds

The default value of [optimization.moduleIds](/config/optimization#optimizationmoduleids) has been changed to `'natural'` when `mode` is `none`.

### optimization.chunkIds

The default value of [optimization.chunkIds](/config/optimization#optimizationchunkids) has been changed to `'natural'` when `mode` is `none`.

## Removed configurations

### [Important] Removed resolve.tsConfigPath

Please use [resolve.tsConfig](/config/resolve#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#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/rspack/lightning-css-minimizer-rspack-plugin) 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)'s [resolve](/api/plugin-api/normal-module-factory-hooks#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/compatibility/plugin.md
---

import { CommunityPluginCompatibleTable } from '@components/CommunityCompatibleTable.tsx';

# Plugin compatibility

This page lists the compatibility status of common community plugins in Rspack.

For details on Rspack's support for webpack built-in plugins, see [Webpack-aligned built-in plugins](/plugins/webpack/index).

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.

<CommunityPluginCompatibleTable lang="en" />

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: /misc/branding/guideline.md
---

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

<img
  src="https://assets.rspack.rs/rspack/rspack-logo.svg"
  alt="Rspack Logo"
  style={{ width: '300px' }}
/>

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

import { PackageManagerTabs } from '@theme';
import { Tabs, Tab } from '@theme';

# 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:

<Tabs>
  <Tab label="ESM">

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

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```

  </Tab>
  <Tab label="CJS">

```js title="rspack.config.cjs"
const { defineConfig } = require('@rspack/cli');

module.exports = defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```

  </Tab>
  <Tab label="TypeScript">

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

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```

  </Tab>
</Tabs>

## Configuration file formats

Rspack supports these configuration file formats:

- `rspack.config.js`: defaults to `CommonJS` format, or `ES modules` format if the type of the package.json is "module".
- `rspack.config.ts`: `TypeScript` format, see [TypeScript configuration file](#typescript-configuration-file) for more details.
- `rspack.config.cjs`: Forced to `CommonJS` format.
- `rspack.config.mjs`: Forced to `ES modules` format.

Note that Rspack will first search JS configuration file and then TS configuration file.

> 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](./extends.mdx) 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, using SWC by default to transform TypeScript code into CommonJS format JavaScript code.

If you're using a Rspack CLI earlier than v1.5.0, it's recommended to upgrade to the latest version. You no longer need to load configuration files through `ts-node` or `esbuild-register`, and these dependencies can be removed.

### Native support

If your JavaScript runtime already natively supports TypeScript, you can use the built-in TS transformation 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.

### Using esbuild

For lower Node.js versions, you can use `esbuild-register` to load the configuration file.

Install [esbuild](https://npmjs.com/package/esbuild) and [esbuild-register](https://npmjs.com/package/esbuild-register), no additional configuration is needed.

<PackageManagerTabs command="add esbuild esbuild-register -D" />

### Using ts-node

You can also use [ts-node](https://npmjs.com/package/ts-node) to load the configuration file.

1. Install `ts-node`:

<PackageManagerTabs command="add ts-node -D" />

2. Then configure `ts-node` to use `CommonJS` modules in `tsconfig.json`:

```json title="tsconfig.json"
{
  "ts-node": {
    "compilerOptions": {
      "module": "CommonJS"
    }
  }
}
```

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

<Tabs>
  <Tab label="TypeScript">

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

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```

  </Tab>
  <Tab label="JavaScript">

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

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});
```

  </Tab>
</Tabs>

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) option or [webpack-merge](https://npmjs.com/package/webpack-merge) package to merge multiple Rspack configurations.

### extends option

When using [@rspack/cli](/api/cli), 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) for more usage.

### webpack-merge

`webpack-merge` is a community library for merging multiple webpack configurations, and it can also be used to merge Rspack configurations.

First install `webpack-merge`:

<PackageManagerTabs command="add webpack-merge -D" />

Then you can use its `merge` function to merge configurations:

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

const isDev = process.env.NODE_ENV === 'development';
const base = {};
const dev = {
  plugins: [new SomeDevPlugin()],
};

export default isDev ? merge(base, dev) : base;
```

> See [webpack-merge documentation](https://npmjs.com/package/webpack-merge) for more details.



---
url: /config/filename-placeholders.md
---

# 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#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#outputfilename)                                   | Compilation, Chunk             | Entry chunk filenames         |
| [output.chunkFilename](/config/output#outputchunkfilename)                         | Chunk                          | Non-entry chunk filenames     |
| [output.cssFilename](/config/output#outputcssfilename)                             | Compilation, Chunk             | Entry CSS chunk filenames     |
| [output.cssChunkFilename](/config/output#outputcsschunkfilename)                   | Chunk                          | Non-entry CSS chunk filenames |
| [output.assetModuleFilename](/config/output#outputassetmodulefilename)             | File, Module                   | Static asset module filenames |
| [output.webassemblyModuleFilename](/config/output#outputwebassemblymodulefilename) | File, Module                   | WebAssembly module filenames  |
| [output.hotUpdateMainFilename](/config/output#outputhotupdatemainfilename)         | Only `[fullhash]`, `[runtime]` | HMR manifest filename         |
| [output.hotUpdateChunkFilename](/config/output#outputhotupdatechunkfilename)       | Only `[fullhash]`, `[id]`      | HMR chunk filenames           |
| [output.sourceMapFilename](/config/output#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#outputhashdigestlength).

:::tip

During local development, avoid using hash-based filenames.

Entry chunks and chunks produced by [optimization.splitChunks](/plugins/webpack/split-chunks-plugin) 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;
  chunk?: Chunk | ChunkPathData;
  contentHashType?: string;
};

type ChunkPathData = {
  id?: string;
  name?: string;
  hash?: string;
  contentHash?: Record<string, string>;
};
```



---
url: /config/extends.md
---

import WebpackLicense from '@components/WebpackLicense';
import PropertyType from '../../../components/PropertyType.tsx';
import { Tabs, Tab } from '@theme';

<WebpackLicense from="https://webpack.js.org/configuration/configuration-types/#exporting-multiple-configurations" />

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

If you are using the JavaScript API or other Rspack-based tools, `extends` will not take effect, use [webpack-merge](/config/#webpack-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:

<Tabs>
  <Tab label="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',
  },
};
```

  </Tab>
  <Tab label="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',
  },
};
```

  </Tab>
</Tabs>

:::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

When merging configurations:

- 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
};
```



---
url: /config/entry.md
---

import WebpackLicense from '@components/WebpackLicense';
import { ApiMeta, Stability } from '../../../components/ApiMeta';
import PropertyType from '@components/PropertyType';

<WebpackLicense from="https://webpack.js.org/configuration/entry-context/#entry" />

# Entry

<PropertyType
  type="string | string[] | Record<string, string | string[] | EntryDescription> | Function"
  defaultValueList={[{ defaultValue: "'./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.html) 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'],
  },
};
```

Multiple modules will be executed sequentially according to the order defined by the array, so the code in `pre.js` will be executed before the code in `post.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

<PropertyType
  type="string[] | string"
  defaultValueList={[{ defaultValue: "'./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

<PropertyType
  type="false | string"
  defaultValueList={[{ defaultValue: '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

<PropertyType
  type="false | string | 'jsonp' | 'import-scripts' | 'require' | 'async-node' | 'import'"
  defaultValueList={[{ defaultValue: '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

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to create a load-on-demand asynchronous chunk for this entry.

#### EntryDescription.publicPath

<PropertyType
  type="'auto' | string | (pathData: PathData, assetInfo?: AssetInfo) => string"
  defaultValueList={[{ defaultValue: 'undefined' }]}
/>

The publicPath of the resource referenced by this entry.

#### EntryDescription.baseUri

<PropertyType
  type="string"
  defaultValueList={[{ defaultValue: 'undefined' }]}
/>

The baseURI of the resource referenced by this entry.

#### EntryDescription.filename

<PropertyType
  type="string"
  defaultValueList={[{ defaultValue: 'undefined' }]}
/>

The filename of the entry chunk.

#### EntryDescription.library

<PropertyType
  type="string | string[] | object"
  defaultValueList={[{ defaultValue: 'undefined' }]}
/>

The format of the chunk generated by this entry as a library, for detailed configuration, see [output.library](/config/output#outputlibrary).

#### EntryDescription.dependOn

<PropertyType
  type="string[] | string"
  defaultValueList={[{ defaultValue: '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

<PropertyType
  type="'fetch' | 'async-node'"
  defaultValueList={[{ defaultValue: 'undefined' }]}
/>

Option to set the method of loading WebAssembly Modules. Methods included by default are `'fetch'` (web/WebWorker), `'async-node'` (Node.js), but others might be added by plugins.

The default value can be affected by different [target](/config/target):

- 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

<ApiMeta addedVersion={'1.0.0-beta.1'} />

<PropertyType
  type="string | null | undefined"
  defaultValueList={[{ defaultValue: '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#rulesissuerlayer), stats, and externals.

For more information about layers, see the [Layer guide](/guide/features/layer).

:::warning
For version before v1.6.0, this configuration will only take effect when [experiments.layers](/config/deprecated-options#experimentslayers) is `true`.
:::

```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#make) event.

> Note that the `make` event triggers when webpack starts and for every invalidation when [watching for file changes](/config/watch).

```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#outputlibrary) option: If an array is passed only the last item is exported.



---
url: /config/context.md
---

import WebpackLicense from '@components/WebpackLicense';
import PropertyType from '@components/PropertyType';
import { Tabs, Tab } from '@theme';

<WebpackLicense from="https://webpack.js.org/configuration/entry-context/#context" />

# Context

<PropertyType
  type="string"
  defaultValueList={[{ defaultValue: '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) and [output](/config/output).

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:

<Tabs>
  <Tab label="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',
  },
};
```

  </Tab>
  <Tab label="CJS">

```js title="rspack.config.cjs"
module.exports = {
  context: __dirname,
  entry: {
    main: './src/index.js',
  },
};
```

  </Tab>
</Tabs>

In the above example, the `main` entry will be resolved based on the `path.join(__dirname, './src/index.js')` path.



---
url: /config/mode.md
---

import WebpackLicense from '@components/WebpackLicense';
import PropertyType from '@components/PropertyType';

<WebpackLicense from="https://webpack.js.org/configuration/mode/" />

# Mode

<PropertyType
  type="'production' | 'development' | 'none'"
  defaultValueList={[{ defaultValue: "'production'" }]}
/>

The `mode` configuration is used to set the build mode of Rspack to enable the default optimization strategy.

## 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:

- Replace `process.env.NODE_ENV` in code with `'production'`.
- Set the default value of `optimization.minimize` to `true` to enable SWC minification.

### development

In development mode, Rspack automatically enables the following optimization strategies:

- Replace `process.env.NODE_ENV` in code with `'development'`.
- Set proper naming format for modules and chunks.

### none

When `mode` is set to `'none'`, Rspack will not enable any default optimization strategies.



---
url: /config/output.md
---

import WebpackLicense from '@components/WebpackLicense';
import { ApiMeta, Stability } from '../../../components/ApiMeta';
import { Tabs, Tab } from '@theme';

<WebpackLicense from="https://webpack.js.org/configuration/output/" />

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

`[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#rulesgenerator).

:::info Asset module output as a separate file

- Module type is `'asset'` and asset is set to satisfy [rules[].parser.dataUrlCondition](/config/module-rules#rulesparserdataurlcondition)
- 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.charset

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

Add [deprecated](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#Charset) `charset="utf-8"` attribute to the HTML `<script>` tag.

## output.chunkFilename

- **Type:** `string | (pathData: PathData, assetInfo?: AssetInfo) => string`
- **Default:** Determined by [`output.filename`](/config/output#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#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.

By default `[id].js` is used or a value inferred from [`output.filename`](/config/output#outputfilename)(`[name]` is replaced with `[id]` or `[id].` is prepended).

```js title="rspack.config.mjs"
export default {
  output: {
    chunkFilename: '[id].js',
  },
};
```

:::tip
See [Filename placeholders](/config/filename-placeholders) 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) 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) 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.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.chunkLoadingGlobal

- **Type:** `string`
- **Default:** Determined by [`output.uniqueName`](/config/output#outputuniquename)

The global variable is used by Rspack for loading chunks.

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

## 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), `'importScripts'` (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`](#target) and [`chunkFormat`](#outputchunkformat).

:::tip

The default value of this option depends on the [`target`](/config/target) and [`chunkFormat`](#chunkFormat) 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.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

<ApiMeta addedVersion={'1.1.0'} />

- **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#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#outputfilename) option for details on the possible values.

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:** Determined by [`output.filename`](/config/output#outputfilename)

This option determines the name of CSS output files on disk. See [`output.filename`](/config/output#outputfilename) option for details on the possible values.

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#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.html) 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 (inline source maps are not supported)    |
| [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)

List of library types enabled for use by entry points.

```js title="rspack.config.mjs"
export default {
  //...
  output: {
    enabledLibraryTypes: ['module'],
  },
};
```

## output.enabledWasmLoadingTypes

- **Type:** `('fetch-streaming' | 'fetch' | 'async-node' | string | false)[]`
- **Default:** Determined by [`output.wasmLoading`](#outputwasmloading) and [`output.workerWasmLoading`](#workerWasmLoading)

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 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 Webpack runtime code.
   * */
  nodePrefixForCoreModules?: boolean;
  /** The environment supports optional chaining ('obj?.a' or 'obj?.()'). */
  optionalChaining?: 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) 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.html) 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.

{
// TODO: add the Glossary link
}

:::

Use [Entry](/config/entry.html) 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) 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: 'myLib',
    libraryTarget: '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#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',
  },
};
```

:::tip
Rspack uses the faster `xxhash64` algorithm by default since v1.1.
:::

## output.hashSalt

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

An optional salt to update the hash.

## output.hotUpdateChunkFilename

- **Type:** `string`
- **Default:** `"[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]`, the default being:

```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:** `"webpackHotUpdate" + output.uniqueName`

Only used when [`target`](/config/target) 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:** `"[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:** `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), 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'`, `'system'`, `'assign'`, `'assign-properties'`, `'this'`, `'window'`, `'self'`, `'global'`, `'commonjs'`, `'commonjs2'`, `'commonjs-module'`, `'commonjs-static'`, `'amd'`, `'amd-require'`, `'umd'`, `'umd2'`, 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) 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 {
  // …
  experiments: {
    outputModule: true,
  },
  output: {
    library: {
      // do not specify a `name` here
      type: 'module',
    },
  },
};
```

Output ES modules.

However this feature is still experimental and not fully supported yet, so make sure to enable [`experiments.outputModule`](/config/experiments#experimentsoutputmodule) beforehand. In addition, you can track the development progress in [this thread](https://github.com/webpack/webpack/issues/2933#issuecomment-774253975).

##### type: 'modern-module'

```js title="rspack.config.mjs"
export default {
  // …
  experiments: {
    outputModule: true,
  },
  output: {
    library: {
      // do not specify a `name` here
      type: 'modern-module',
    },
  },
};
```

This configuration generates tree-shakable output for ES Modules.

However this feature is still experimental and not fully supported yet, so make sure to enable [`experiments.outputModule`](/config/experiments#experimentsoutputmodule) beforehand.

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

##### 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: {
    libraryTarget: '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) 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.module

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

Output JavaScript files as module type. Disabled by default as it's an experimental feature. To use it, you must set [`experiments.outputModule`](/config/experiments#experimentsoutputmodule) to `true`.

When enabled, Rspack will set [`output.iife`](#outputiife) to `false`, [`output.scriptType`](#outputscripttype) to `'module'` and `terserOptions.module` to `true` internally.

If you're using Rspack to compile a library to be consumed by others, make sure to set [`output.libraryTarget`](#librarytarget-module) to `'module'` when `output.module` is `true`.

```js title="rspack.config.mjs"
export default {
  //...
  experiments: {
    outputModule: true,
  },
  output: {
    module: true,
  },
};
```

## output.path

- **Type:** `string`
- **Default:** `path.resolve(process.cwd(), 'dist')`

The output directory as an **absolute** path.

<Tabs>
  <Tab label="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'),
  },
};
```

  </Tab>
  <Tab label="CJS">

```js title="rspack.config.cjs"
const path = require('node:path');

module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist/assets'),
  },
};
```

  </Tab>
</Tabs>

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.
- `output.path` must be an absolute path.

:::

## 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) 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) for more details.

## output.scriptType

- **Type:** `'module' | 'text/javascript' | boolean`
- **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) 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).

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

- When set to `true`, Rspack will use [`output.uniqueName`](#outputuniquename) as the Trusted Types policy name.
- When set to a non-empty string, its value will be used as a policy name.
- When set to an object, the policy name is taken from the object's `policyName` property.

```js title="rspack.config.mjs"
export default {
  //...
  output: {
    trustedTypes: {
      policyName: 'my-application#webpack',
    },
  },
};
```

### output.trustedTypes.onPolicyCreationFailure

<ApiMeta addedVersion={'1.1.6'} />

- **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#webpack',
      onPolicyCreationFailure: 'continue',
    },
  },
};
```

## output.uniqueName

- **Type:** `string`
- **Default:** It defaults to [`output.library`](#outputlibrary) name or the package name from `package.json` in the context, if both aren't found, it is set to an `''`.

A unique name of the Rspack build to avoid multiple Rspack runtimes to conflict when using globals.

`output.uniqueName` will be used to generate unique globals for:

- [`output.chunkLoadingGlobal`](#outputchunkloadingglobal)

```js title="rspack.config.mjs"
export default {
  output: {
    uniqueName: 'my-package-xyz',
  },
};
```

## output.wasmLoading

- **Type:** `false | 'fetch', 'async-node'`
- **Default:** `'fetch'`

Option to set the method of loading WebAssembly Modules. Methods included by default are `'fetch'` (web/webworker), `'async-node'` (Node.js), but others might be added by plugins.

The default value can be affected by different [`target`](/config/target):

- Defaults to `'fetch'` if [`target`](/config/target) is set to `'web'`, `'webworker'`, `'electron-renderer'` or `'node-webkit'`.
- Defaults to `'async-node'` if [`target`](/config/target) is set to `'node'`, `'async-node'`, `'electron-main'` or `'electron-preload'`.

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

## 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) for more information.
:::

## output.workerChunkLoading

- **Type:** `false | 'jsonp' | 'import-scripts' | 'require' | 'async-node' | 'import'`
- **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) 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-streaming' | 'fetch' | 'async-node' | string`
- **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',
  },
};
```

## output.auxiliaryComment

:::warning
Prefer to use [`output.library.auxiliaryComment`](#outputlibraryauxiliarycomment) instead.
:::

## output.libraryExport \{#outputlibraryexport-1}

:::warning
We might drop support for this, so prefer to use [output.library.export](#outputlibraryexport) which works the same as `libraryExport`.
:::

## output.libraryTarget

:::warning
Please use [`output.library.type`](#outputlibrarytype) instead as we might drop support for `output.libraryTarget` in the future.
:::

## output.umdNamedDefine

:::warning
Prefer to use [`output.library.umdNamedDefine`](#outputlibraryumdnameddefine) instead.
:::

## output.cssHeadDataCompression

<ApiMeta addedVersion={'1.0.0'} />

- **Type:** `boolean`
- **Default:** `false` for development mode, `true` for production mode

Rspack adds some metadata in CSS to parse CSS modules, and this configuration determines whether to compress these metadata.

For example

```css
.local-a {
  color: blue;
}

head {
  --webpack-main: a: local-a/&\.\/ src\/index\.module\.css;
}
```

After compress 👇

```css
.local-a {
  color: blue;
}

head {
  --webpack-main: &\.\/ srcăindexāmoduleācss;
}
```



---
url: /config/module.md
---

import { ApiMeta, Stability } from '../../../components/ApiMeta';
import PropertyType from '@components/PropertyType';
import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.docschina.org/configuration/module/" />

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

- **Type:** `string | string[] | RegExp | 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.unsafeCache

- **Type:** `boolean | RegExp`

This is a performance optimization option that reduces the overhead of recording module resolution-related files in Rspack by **assuming that the resolution results of matched modules will not change**.

During module resolution, Rspack needs to record relevant files that may affect the resolution results. For example:

```js
import 'the-module';
```

When resolving `the-module`, Rspack not only obtains the actual module path but also records the associated `package.json`:

```json
{
  "exports": {
    ".": "./lib/index.js"
  }
}
```

Because the `exports` field in `package.json` may affect the module's resolution path. When these files change, Rspack needs to re-perform module resolution.

After enabling `unsafeCache`, matched modules are considered to have stable resolution results that will not change, so Rspack will no longer record files associated with the resolution of these modules.

`unsafeCache` has the following default behavior:

- If [cache](/config/cache) is disabled, the value is `false`
- If [cache](/config/cache) is enabled:
  - For modules from the `node_modules` directory, the value is `true`
  - In other cases, the value is `false`

```js title="rspack.config.mjs"
export default {
  //...
  module: {
    unsafeCache: false,
  },
};
```

:::tip Differences from Webpack
Even when `module.unsafeCache: false` is set, Rspack still caches the association between `Dependency` and `Module` because Rspack uses an incremental algorithm when building the module graph. In contrast, Webpack completely disables module graph caching.

To ensure resolution accuracy, Rspack completely records all related files during the module resolution process when `unsafeCache` is disabled.
:::

:::tip Relationship with `watchOptions.ignored`
File recording: Occurs during the make phase, storing associated paths and building indexes with Dependencies.

File watching: After compilation ends, recorded file paths are passed to the watcher, which can ignore specific paths through the `ignored` configuration.

Incremental building: When the watcher detects file changes, Rspack finds the affected Dependencies through the paths and re-executes module resolution.

Both are architecturally layered, each responsible for different functional phases.
:::

## module.parser

- **Type:** `Object`
- **Default:** `{}`

Configure all parsers' options in one place with `module.parser`.

```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,
      },
    },
  },
};
```

### module.parser.asset

Parser options for `asset` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      asset: {
        // options
      },
    },
  },
};
```

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

```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,
        },
      },
    },
  },
};
```

### module.parser.javascript

Parser options for `javascript` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        // options
      },
    },
  },
};
```

### module.parser.javascript.commonjsMagicComments

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'false' }]} />
<ApiMeta addedVersion="1.5.6" />

Enable [Magic comments](/api/runtime-api/module-methods#magic-comments) support for CommonJS.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        commonjsMagicComments: true,
      },
    },
  },
};
```

Note that only `webpackIgnore` comment is supported at the moment:

```js
const x = require(/* webpackIgnore: true */ 'x');
```

### module.parser.javascript.dynamicImportMode

<PropertyType
  type="'lazy' | 'eager' | 'weak' | 'lazy-once'"
  defaultValueList={[{ defaultValue: "'lazy'" }]}
/>

Specifies global mode for dynamic import, see [`webpackMode`](/api/runtime-api/module-methods#webpackmode) for more details.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        dynamicImportMode: 'eager',
      },
    },
  },
};
```

### module.parser.javascript.dynamicImportPrefetch

<PropertyType
  type="boolean | number"
  defaultValueList={[{ defaultValue: 'false' }]}
/>

Specifies global prefetch for dynamic import, see [`webpackPrefetch`](/api/runtime-api/module-methods#webpackprefetch) for more details.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        dynamicImportPrefetch: true,
      },
    },
  },
};
```

### module.parser.javascript.dynamicImportPreload

<PropertyType
  type="boolean | number"
  defaultValueList={[{ defaultValue: 'false' }]}
/>

Specifies global preload for dynamic import, see [`webpackPreload`](/api/runtime-api/module-methods#webpackpreload) for more details.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        dynamicImportPreload: true,
      },
    },
  },
};
```

### module.parser.javascript.dynamicImportFetchPriority

<ApiMeta addedVersion="1.0.0" />

<PropertyType
  type="'low' | 'high' | 'auto'"
  defaultValueList={[{ defaultValue: "'auto'" }]}
/>

Specifies global `fetchPriority` for dynamic import, see [`webpackFetchPriority`](/api/runtime-api/module-methods#webpackfetchpriority) for more details.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        dynamicImportFetchPriority: 'high',
      },
    },
  },
};
```

### module.parser.javascript.url

<PropertyType
  type="true | false | 'relative' | 'new-url-relative'"
  defaultValueList={[{ defaultValue: '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" />
```

### module.parser.javascript.exprContextCritical

<PropertyType
  type="boolean | undefined"
  defaultValueList={[{ defaultValue: 'true' }]}
/>

Enable warnings for full dynamic dependencies (`import(variable)`).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        exprContextCritical: false,
      },
    },
  },
};
```

### module.parser.javascript.wrappedContextCritical

<PropertyType
  type="boolean | undefined"
  defaultValueList={[{ defaultValue: 'false' }]}
/>

Enable warnings for partial dynamic dependencies (`import("./path/to/" + variable)`).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        wrappedContextCritical: false,
      },
    },
  },
};
```

### module.parser.javascript.unknownContextCritical

<PropertyType
  type="boolean | undefined"
  defaultValueList={[{ defaultValue: '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,
      },
    },
  },
};
```

### module.parser.javascript.wrappedContextRegExp

<PropertyType
  type="RegExp | undefined"
  defaultValueList={[{ defaultValue: '/.*/' }]}
/>

Set a regular expression to match wrapped dynamic dependencies.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        wrappedContextRegExp: /\.js$/,
      },
    },
  },
};
```

### module.parser.javascript.importMeta

<ApiMeta addedVersion="1.0.0-alpha.6" />

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Enable or disable evaluating `import.meta`.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        importMeta: false,
      },
    },
  },
};
```

### module.parser.javascript.exportsPresence

<PropertyType
  type="'error' | 'warn' | 'auto' | false"
  defaultValueList={[{ defaultValue: "'auto'" }]}
/>

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: 'error',
      },
    },
  },
};
```

### module.parser.javascript.importExportsPresence

<PropertyType type="'error' | 'warn' | 'auto' | false" />

Warn or error for using non-existent exports, defaulting to the configuration of [module.parser.javascript.exportsPresence](#moduleparserjavascriptexportspresence).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        importExportsPresence: 'error',
      },
    },
  },
};
```

### module.parser.javascript.reexportExportsPresence

<PropertyType type="'error' | 'warn' | 'auto' | false" />

Warn or error for conflicting re-exports, defaulting to the configuration of [module.parser.javascript.exportsPresence](#moduleparserjavascriptexportspresence).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        reexportExportsPresence: 'error',
      },
    },
  },
};
```

### module.parser.javascript.strictExportPresence

- **Type:** `boolean`

Emit errors instead of warnings when imported names don't exist in imported module.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      javascript: {
        strictExportPresence: true,
      },
    },
  },
};
```

### module.parser.javascript.typeReexportsPresence

<ApiMeta stability={Stability.Experimental} addedVersion="1.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/tech/typescript#%E5%BC%80%E5%90%AF-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#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: /\.ts$/,
        use: [
          {
            loader: 'builtin:swc-loader',
            options: {
              jsc: {
                parser: {
                  syntax: 'typescript',
                },
              },
              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.

### module.parser.javascript.worker

<ApiMeta addedVersion="1.0.0-alpha.0" />

<PropertyType type="string[] | boolean" />

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"]
          '...',
        ],
      },
    },
  },
};
```

> See [Web Workers](/guide/features/web-workers) for more details.

### module.parser.javascript.overrideStrict

<ApiMeta addedVersion="1.0.0-alpha.4" />

<PropertyType 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',
      },
    },
  },
};
```

### module.parser.javascript.commonjs

<PropertyType
  type="boolean | { exports?: boolean | 'skipInEsm' }"
  defaultValueList={[{ defaultValue: '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',
        },
      },
    },
  },
};
```

### module.parser.javascript.jsx

<ApiMeta stability={Stability.Experimental} addedVersion="1.5.7" />

<PropertyType type="boolean" defaultValueList={[{ defaultValue: '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.
:::

### module.parser["javascript/auto"]

Parser options for `javascript/auto` modules, same as the [`javascript` parser options](#moduleparserjavascript).

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

### module.parser["javascript/dynamic"]

Parser options for `javascript/dynamic` modules, same as the [`javascript` parser options](#moduleparserjavascript).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'javascript/dynamic': {
        // options
      },
    },
  },
};
```

### module.parser["javascript/esm"]

Parser options for `javascript/esm` modules, same as the [`javascript` parser options](#moduleparserjavascript).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'javascript/esm': {
        // options
      },
    },
  },
};
```

### module.parser.json

<ApiMeta addedVersion="1.2.0" />

Parser options for `json` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      json: {
        // options
      },
    },
  },
};
```

### module.parser.json.exportsDepth

<ApiMeta addedVersion="1.2.0" />

- **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,
      },
    },
  },
};
```

### module.parser["css/auto"]

Parser options for `css/auto` modules.

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

:::warning
This configuration will only work if [experiments.css](/config/experiments#experimentscss) is enabled.
:::

### module.parser["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';
```

### module.parser["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,
      },
    },
  },
};
```

### module.parser.css

Parser options for `css` modules.

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

:::warning
This configuration will only work if [experiments.css](/config/experiments#experimentscss) is enabled.
:::

### module.parser.css.namedExports

Same as [`module.parser["css/auto"].namedExports`](#moduleparsercssautonamedexports).

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

### module.parser.css.url

Same as [`module.parser["css/auto"].url`](#moduleparsercssautourl).

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      css: {
        url: true,
      },
    },
  },
};
```

### module.parser["css/module"]

Parser options for `css/module` modules.

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

:::warning
This configuration will only work if [experiments.css](/config/experiments#experimentscss) is enabled.
:::

### module.parser["css/module"].namedExports

Same as [`module.parser["css/auto"].namedExports`](#moduleparsercssautonamedexports).

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

### module.parser["css/module"].url

Same as [`module.parser["css/auto"].url`](#moduleparsercssautourl).

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

## module.generator

- **Type:** `Object`
- **Default:** `{}`

Configure all generators' options in one place with `module.generator`.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      // Generator options for asset modules
      asset: {
        dataUrl: {
          encoding: false,
          mimetype: 'base64',
        },
        filename: '[name]-[contenthash][ext]',
        publicPath: 'https://cdn.example.com/',
      },
      // Generator options for asset/inline modules
      'asset/inline': {
        dataUrl: {
          encoding: false,
          mimetype: 'base64',
        },
      },
      // Generator options for asset/resource modules
      'asset/resource': {
        filename: '[name]-[contenthash][ext]',
        publicPath: 'https://cdn.example.com/',
      },
      // Generator options for css/auto modules
      'css/auto': {
        exportsConvention: 'as-is',
        exportsOnly: false,
        localIdentName: '[uniqueName]-[id]-[local]',
        esModule: true,
      },
      // Generator options for `css` modules
      css: {
        exportsOnly: false,
        esModule: true,
      },
      // Generator options for css/module modules
      'css/module': {
        exportsConvention: 'as-is',
        exportsOnly: false,
        localIdentName: '[uniqueName]-[id]-[local]',
        esModule: true,
      },
      // Generator options for `json` modules
      json: {
        JSONParse: true,
      },
    },
  },
};
```

### module.generator.asset

Generator options for `asset` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      asset: {
        // options
      },
    },
  },
};
```

### module.generator.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,
      },
    },
  },
};
```

### module.generator.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: 'mimetype/png',
        },
      },
    },
  },
};
```

When used a a function, it executes for every module and must return a data URI string.

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

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

export default {
  //...
  module: {
    generator: {
      asset: {
        dataUrl: ({ content }) => {
          const svgToMiniDataURI = require('mini-svg-data-uri');
          return svgToMiniDataURI(content);
        },
      },
    },
  },
};
```

### module.generator.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,
        },
      },
    },
  },
};
```

### module.generator.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',
        },
      },
    },
  },
};
```

### module.generator.asset.importMode

- **Type:** `'url' | 'preserve'`
- **Default:** `'url'`

If `"url"`, a URL pointing to the asset will be generated based on [publicPath](#modulegeneratorassetpublicpath).
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',
      },
    },
  },
};
```

### module.generator.asset.filename

- **Type:** `string | ((pathData: PathData, assetInfo?: AssetInfo) => string)`
- **Default:** `undefined`
- **Supported Template string:** checkout [`output.assetModuleFilename`](/config/output#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]',
      },
    },
  },
};
```

### module.generator.asset.outputPath

- **Type:** `string | ((pathData: PathData, assetInfo?: AssetInfo) => string)`
- **Default:** `undefined`

Emit the asset in the specified folder relative to [`output.path`](/config/output#outputpath).

Only for modules with module type `'asset'` or `'asset/resource'`.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      asset: {
        outputPath: 'foo/',
      },
    },
  },
};
```

### module.generator.asset.publicPath

- **Type:** `string | ((pathData: PathData, assetInfo?: AssetInfo) => string)`
- **Default:** `undefined`

Override [`output.publicPath`](/config/output#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/',
      },
    },
  },
};
```

### module.generator.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,
      },
    },
  },
};
```

### module.generator["asset/inline"]

Generator options for `asset/inline` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/inline': {
        // options
      },
    },
  },
};
```

### module.generator["asset/inline"].binary

Same as [`module.generator["asset"].binary`](#modulegeneratorassetbinary).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/inline': {
        binary: false,
      },
    },
  },
};
```

### module.generator["asset/inline"].dataUrl

Same as [`module.generator["asset"].dataUrl`](#modulegeneratorassetdataurl).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/inline': {
        dataUrl: {
          // options
        },
      },
    },
  },
};
```

### module.generator["asset/inline"].dataUrl.encoding

Same as [`module.generator["asset"].dataUrl.encoding`](#modulegeneratorassetdataurlencoding).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/inline': {
        dataUrl: {
          encoding: false,
        },
      },
    },
  },
};
```

### module.generator["asset/inline"].dataUrl.mimetype

Same as [`module.generator["asset"].dataUrl.mimetype`](#modulegeneratorassetdataurlmimetype).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/inline': {
        dataUrl: {
          mimetype: 'image/png',
        },
      },
    },
  },
};
```

### module.generator["asset/resource"]

Generator options for `asset/resource` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        // options
      },
    },
  },
};
```

### module.generator["asset/resource"].binary

Same as [`module.generator["asset"].binary`](#modulegeneratorassetbinary).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        binary: false,
      },
    },
  },
};
```

### module.generator["asset/resource"].importMode

Same as [`module.generator["asset"].importMode`](#modulegeneratorassetimportmode).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        importMode: 'preserve',
      },
    },
  },
};
```

### module.generator["asset/resource"].filename

Same as [`module.generator["asset"].filename`](#modulegeneratorassetfilename).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        filename: 'static/[hash][ext]',
      },
    },
  },
};
```

### module.generator["asset/resource"].outputPath

Same as [`module.generator["asset"].outputPath`](#modulegeneratorassetoutputpath).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        outputPath: 'foo/',
      },
    },
  },
};
```

### module.generator["asset/resource"].publicPath

Same as [`module.generator["asset"].publicPath`](#modulegeneratorassetpublicpath).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'asset/resource': {
        publicPath: 'https://cdn.example.com/',
      },
    },
  },
};
```

### module.generator["css/auto"]

Generator options for `css/auto` modules.

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

:::warning
This configuration will only work if [experiments.css](/config/experiments#experimentscss) is enabled.
:::

### module.generator["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',
      },
    },
  },
};
```

### module.generator["css/auto"].exportsOnly

- **Type:** `boolean`
- **Default:** `true` for node environments, `false` for web environments.

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,
      },
    },
  },
};
```

### module.generator["css/auto"].localIdentName

- **Type:** `string`
- **Default:** `[uniqueName]-[id]-[local]`

Customize the format of the local class names generated for CSS modules, besides the substitutions at [File-level](/config/output#file-context) and [Module-level](/config/output#module-context), also include `[uniqueName]` and `[local]`.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/auto': {
        localIdentName: '[local]-[hash:base64:6]',
      },
    },
  },
};
```

### module.generator["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#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.
  });
}
```

### module.generator.css

Generator options for `css` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      css: {
        // options
      },
    },
  },
};
```

:::warning
This configuration will only work if [experiments.css](/config/experiments#experimentscss) is enabled.
:::

### module.generator.css.exportsOnly

Same as [`module.generator["css/auto"].exportsOnly`](#modulegeneratorcssautoexportsonly).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      css: {
        exportsOnly: false,
      },
    },
  },
};
```

### module.generator.css.esModule

Same as [`module.generator["css/auto"].esModule`](#modulegeneratorcssautoesmodule).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      css: {
        esModule: true,
      },
    },
  },
};
```

### module.generator["css/module"]

Generator options for `css/module` modules.

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/module': {
        // options
      },
    },
  },
};
```

:::warning
This configuration will only work if [experiments.css](/config/experiments#experimentscss) is enabled.
:::

### module.generator["css/module"].exportsConvention

Same as [`module.generator["css/auto"].exportsConvention`](#modulegeneratorcssautoexportsconvention).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/module': {
        exportsConvention: 'camel-case',
      },
    },
  },
};
```

### module.generator["css/module"].exportsOnly

Same as [`module.generator["css/auto"].exportsOnly`](#modulegeneratorcssautoexportsonly).

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

### module.generator["css/module"].localIdentName

Same as [`module.generator["css/auto"].localIdentName`](#modulegeneratorcssautolocalidentname).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/module': {
        localIdentName: '[local]-[hash:base64:6]',
      },
    },
  },
};
```

### module.generator["css/module"].esModule

Same as [`module.generator["css/auto"].esModule`](#modulegeneratorcssautoesmodule).

```js title="rspack.config.mjs"
export default {
  module: {
    generator: {
      'css/module': {
        esModule: true,
      },
    },
  },
};
```

### module.generator.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,
      },
    },
  },
};
```

## module.rules

See [Module Rules](/config/module-rules) for details.



---
url: /config/module-rules.md
---

import { ApiMeta, Stability } from '../../../components/ApiMeta';
import PropertyType from '@components/PropertyType';
import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.docschina.org/configuration/module/" />

# 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) 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) to handle files ending with `.ts`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.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

<ApiMeta addedVersion="1.0.0-beta.1" />

- **Type:** `string`
- **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 [Layer guide](/guide/features/layer).

:::warning
For version before v1.6.0, this configuration will only work if [experiments.layers = true](/config/deprecated-options#experimentslayers).
:::

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#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[].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#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` option allows you to match values of properties in the description file, typically `package.json`, to determine which modules a rule should apply to. This is a useful way to apply rules to specific modules based on metadata found in their `package.json`.

The object keys in `descriptionData` correspond to keys in the module's `package.json`, such as `name`, `version`, etc. Each key should be associated with a [`Condition`](#condition) for matching the `package.json` data.

For example, below we are applying the rule only to JavaScript resources with `'rspack'` string included in their `package.json` `name`.

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        include: /node_modules/,
        descriptionData: {
          name: (packageJsonName) => packageJsonName.includes('rspack'),
        },
        // additional rule options...
      },
    ],
  },
};
```

## rules[].with

<ApiMeta addedVersion="1.0.0-beta.1" />

- **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#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), 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: /\.ts$/,
        exclude: [/node_modules/],
        loader: 'builtin:swc-loader',
        options: {
          jsc: {
            experimental: {
+             keepImportAttributes: true,
            },
            parser: {
              syntax: 'typescript',
            },
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
};
```

## rules[].loader

`rules[].loader` is a shortcut to `rules[].use: [ { loader } ]`. See [rules[].use](/config/module-rules#rulesuse) for details.

## rules[].options

`rules[].options` is a shortcut to `rules[].use: [ { options } ]`. See [rules[].use](/config/module-rules#rulesuse) for details.

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

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

## rules[].sideEffects

- **Type:** `boolean`

Flag the module for side effects, this will affect the result of [Tree Shaking](/guide/optimization/tree-shaking).

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

## rules[].enforce

<PropertyType 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#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:**

```ts
type RuleType =
  | 'asset'
  | 'css'
  | 'css/auto'
  | '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/tech/json).
- `'css' | 'css/module' | 'css/auto'`: CSS module, see [Built-in CSS support](/guide/tech/css#built-in-css-support).
- `'asset' | 'asset/source' | 'asset/resource' | 'asset/inline' | 'asset/bytes'`: Asset module, see [Asset Module](/guide/features/asset-module).

## rules[].layer

<ApiMeta addedVersion="1.0.0-beta.1" />

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

For more information about layers, see the [Layer guide](/guide/features/layer).

:::warning
For version before v1.6.0, this configuration will only work if [experiments.layers = true](/config/deprecated-options#experimentslayers).
:::

```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 = { loader: string; options: Record<string, any> } | string;
interface RawFuncUseCtx {
  resource?: string;
  realResource?: string;
  resourceQuery?: string;
  issuer?: string;
}
```

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

<ApiMeta addedVersion="1.3.1" />

- **Type**: `boolean`
- **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
            },
          },
        ],
      },
    ],
  },
  experiments: {
    parallelLoader: true,
  },
};
```

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

- This feature is experimental. It only takes effect when [experiments.parallelLoader](/config/experiments#experimentsparallelloader) is enabled.
- 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[].resolve

Set specific module [resolve](/config/resolve) 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](#rules)[]</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](#rules) | 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

<ApiMeta addedVersion="1.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,
      },
    ],
  },
};
```



---
url: /config/resolve.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/configuration/resolve/" />

# Resolve

Used to configure the Rspack module resolution logic.

- **Type:** `Object`

## resolve.alias

- **Type:** `Record<string, false | string | (string | false)[]>`
- **Default:** `{}`

Path alias, e.g.

```
{
  "@": path.resolve(__dirname, './src'),
  "abc$": path.resolve(__dirname, './node_modules/abc/index.js'),
}
```

At this point:

- `require("@/a")` will attempt to resolve `<root>/src/a`.
- `require("abc")` will attempt to resolve `<root>/src/abc`.
- `require("abc/file.js")` will not match, and it will attempt to resolve `node_modules/abc/file.js`.

### Impact on package resolution

When you use `resolve.alias` to redirect a package import (for example, `import 'lib'`) to a specific directory inside a monorepo or within `node_modules`, the module resolution behavior changes:

- **Default behavior**: If the import is a package name, Rspack performs the full package resolution process: it reads the package's `package.json` and determines the entry file and subpath mappings according to the [`exports`](https://nodejs.org/api/packages.html#exports) field.
- **When aliased**: When an alias resolves to a file system path — for example, `./node_modules/lib` — Rspack no longer treats it as a package name and resolves it as a regular path. This bypasses the standard package resolution logic, causing fields such as `exports` in `package.json` to no longer take effect. This is the intended and standard behavior of Node.js.

### Monorepo usage

If you want packages within a monorepo to retain the same resolution behavior as regular npm packages, avoid using `alias` to point a package name directly to its source directory.
The recommended approach is to use your package manager's workspace feature to symlink sub-packages into `node_modules`, so they can be resolved just like normal dependencies.

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

:::tip
The options defined in `resolve.byDependency` are merged with the top-level `resolve` configuration, with `resolve.byDependency` taking precedence.
:::

## 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), [target](/config/target) and module type.

```js
// For ES modules
['import', 'module', 'webpack', mode, target];

// For CommonJS
['require', 'module', 'webpack', mode, target];

// For CSS module
['webpack', mode, 'style'];
```

In the above example:

- `mode` is determined by [mode](/config/mode) config, which is `development` in development mode and `production` in other modes.
- `target` is determined by [target](/config/target) 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.extensions

- **Type:** `string[]`
- **Default:** `[".js", ".json", ".wasm"]`

Automatically resolve file extensions when importing modules. This means you can import files without explicitly writing their extensions.

For example, if importing `./index`, Rspack will try to resolve using the following order:

- `./index.js`
- `./index.json`
- `./index.wasm`

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

### Extend default value

Note that configuring `resolve.extensions` will completely override the default array, which means Rspack will no longer attempt to resolve modules using the default extensions.

To include the default extensions alongside your custom ones, you can use the spread syntax `'...'`:

```js title="rspack.config.mjs"
export default {
  resolve: {
    // equivalent to ['.ts', '.js', '.json', '.wasm']
    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.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.fallback

- **Type:** `Record<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.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`.

## resolve.mainFields

- **Type:** `string[]`
- **Default:** Based on the [target](/config/target) 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"]`

The name of the directory to use when resolving dependencies.

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

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

Opt for absolute paths when resolving, in relation to `resolve.roots`.

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

```js title="rspack.config.mjs"
export default {
  resolve: {
    // string
    tsConfig: path.resolve(__dirname, './tsconfig.json'),
    // or object
    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`.

## 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.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. It defaults to the `context` configuration option. On systems other than Windows, these requests are initially resolved as an absolute path.

## 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.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,
  },
};
```



---
url: /config/resolve-loader.md
---

import { Tabs, Tab } from '@theme';

# ResolveLoader

This configuration item is consistent in type with [`resolve`](/config/resolve), but this setting only affects the resolution of [loaders](/guide/features/loader).

- **Type:** Consistent with [`resolve`](/config/resolve)
- **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:

<Tabs>
  <Tab label="ESM">

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

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

export default {
  resolveLoader: {
    alias: {
      'amazing-loader': require.resolve('path-to-your-amazing-loader'),
    },
  },
};
```

  </Tab>
  <Tab label="CJS">

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

  </Tab>
</Tabs>

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



---
url: /config/node.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/configuration/node/" />

# Node

The following Node.js options configure whether to polyfill or mock certain [Node.js globals](https://nodejs.org/docs/latest/api/globals.html).

## 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'`
- **Default:**
  - If `target` does not include `node`, defaults to `'warn-mock'`.
  - If `target` includes `node`, uses `'node-module'` if [output.module](/config/output#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 source file path, relative to the [`context`](/config/context) option
- `false`: Do nothing and keep the native behavior
- `'mock'`: Replace with `/index.js`
- `'mock'`: Replace with `'/index.js'`
- `'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#outputmodule) is enabled. Replace `__filename` in CommonJS with an equivalent implementation based on `import.meta.url`, suitable for ESM output

### Examples

For example, to leave `__filename` and `import.meta.filename` as it is:

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

To replace `__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'`
- **Default:**
  - If `target` does not include `node`, defaults to `'warn-mock'`.
  - If `target` includes `node`, uses `'node-module'` if [output.module](/config/output#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) 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#outputmodule) is enabled. Replace `__dirname` in CommonJS with an equivalent implementation based on `import.meta.url`, suitable for ESM output

### Examples

For example, to leave `__dirname` and `import.meta.dirname` as it is:

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

To replace `__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',
  },
};
```



---
url: /config/optimization.md
---

import { ApiMeta } from '@components/ApiMeta';
import PropertyType from '../../../components/PropertyType.tsx';

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/configuration/optimization/" />

# Optimization

Rspack will select appropriate optimization configuration based on the [`mode`](/config/mode). You can also customize the configuration via [`optimization`](/config/optimization).

## optimization.moduleIds

<PropertyType
  type="'natural' | 'named' | 'deterministic'"
  defaultValueList={[
    { defaultValue: "'deterministic'", mode: 'production' },
    { defaultValue: "'named'", mode: 'development' },
  ]}
/>

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

```js title="rspack.config.mjs"
export default {
  optimization: {
    moduleIds: 'deterministic',
  },
};
```

The `deterministic` option is useful for long term caching, and results in smaller bundles compared to hashed. Length of the numeric value is chosen to fill a maximum of 80% of the id space. By default a minimum length of 3 digits is used when `optimization.moduleIds` is set to `deterministic`.

## optimization.chunkIds

<PropertyType
  type="'natural' | 'named' | 'deterministic' | 'size' | 'total-size'"
  defaultValueList={[
    { defaultValue: "'named'", mode: 'development' },
    { defaultValue: "'deterministic'", mode: 'production' },
  ]}
/>

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. |
| `'size'`          | Use numeric ids to make the initial download package smaller.                                                                                  |
| `'total-size'`    | Use numeric ids to make the overall download package smaller.                                                                                  |

```js title="rspack.config.mjs"
export default {
  optimization: {
    chunkIds: 'deterministic',
  },
};
```

## optimization.mergeDuplicateChunks

<PropertyType type="boolean" defaultValueList={[{ defaultValue: '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

<PropertyType
  type="boolean"
  defaultValueList={[
    { defaultValue: 'true', mode: 'production' },
    { defaultValue: 'false', mode: 'development' },
  ]}
/>

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

<PropertyType
  type="Array<Plugin>"
  defaultValueList={[
    {
      defaultValue:
        '[new SwcJsMinimizerRspackPlugin(), new LightningCssMinimizerRspackPlugin()]',
    },
  ]}
/>

Customize the minimizer. By default, [`rspack.SwcJsMinimizerRspackPlugin`](/plugins/rspack/swc-js-minimizer-rspack-plugin) and [`rspack.LightningCssMinimizerRspackPlugin`](/plugins/rspack/lightning-css-minimizer-rspack-plugin) 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.removeAvailableModules

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to detect and remove modules from chunks when these modules are already included in parent chunks. This optimization helps to reduce duplicated modules in the bundle.

This optimization is enabled by default and setting `optimization.removeAvailableModules` to `false` will disable this optimization:

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

:::danger
Disabling this optimization is dangerous, as it may significantly increase the bundle size and greatly slow down the build process.
:::

## optimization.removeEmptyChunks

<PropertyType type="boolean" defaultValueList={[{ defaultValue: '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

<PropertyType
  type="boolean | string | { name: string } | { name: (entrypoint: { name: string }) => string }"
  defaultValueList={[{ defaultValue: 'false' }]}
/>

Used to control how the Rspack's [runtime](/misc/glossary#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. This setting is an alias for:

```js title="rspack.config.mjs"
export default {
  optimization: {
    runtimeChunk: 'runtime',
  },
};
```

By setting `optimization.runtimeChunk` to an object it can provide the `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.realContentHash

<PropertyType
  type="boolean"
  defaultValueList={[
    { defaultValue: 'true', mode: 'production' },
    { defaultValue: 'false', mode: 'development' },
  ]}
/>

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

<PropertyType 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/webpack/split-chunks-plugin) page.

## optimization.sideEffects

<PropertyType
  type="boolean | 'flag'"
  defaultValueList={[
    { defaultValue: 'true', mode: 'production' },
    { defaultValue: "'flag'", mode: 'development' },
  ]}
/>

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

<PropertyType type="boolean" defaultValueList={[{ defaultValue: '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#reexports-optimization).

```js title="rspack.config.mjs"
export default {
  //...
  optimization: {
    providedExports: false,
  },
};
```

## optimization.usedExports

<PropertyType
  type="boolean | 'global'"
  defaultValueList={[
    { defaultValue: 'true', mode: 'production' },
    { defaultValue: 'false', mode: 'development' },
  ]}
/>

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',
  },
};
```

## optimization.mangleExports

<PropertyType
  type="boolean | 'deterministic' | 'size' "
  defaultValueList={[
    { defaultValue: 'deterministic', mode: 'production' },
    { defaultValue: 'false', mode: 'development' },
  ]}
/>

`optimization.mangleExports` allows to control export mangling.

The following values are supported:

| option          | description                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 'named'         | Use meaningful, easy-to-debug content as id. This option is enabled by default in development mode                                 |
| 'deterministic' | Use the hashed module identifier as the id to benefit from long-term caching. This option is enabled by default in production mode |
| true            | Same as 'deterministic'                                                                                                            |
| false           | Keep original name. Good for readability and debugging.                                                                            |

## optimization.inlineExports

<ApiMeta addedVersion="1.7.0" />

<PropertyType
  type="boolean"
  defaultValueList={[
    { defaultValue: 'true', mode: 'production' },
    { defaultValue: 'false', mode: 'development' },
  ]}
/>

Performs cross-module inline optimization for:

1. Exported constant value in leaf modules of the module graph:
   - `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#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.
:::

For more details, refer to the [inline const example](https://github.com/rstackjs/rstack-examples/tree/main/rspack/inline-const).

## optimization.innerGraph

<PropertyType
  type="boolean"
  defaultValueList={[
    { defaultValue: 'true', mode: 'production' },
    { defaultValue: 'false', mode: 'development' },
  ]}
/>

`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.concatenateModules

<PropertyType
  type="boolean"
  defaultValueList={[
    { defaultValue: 'true', mode: 'production' },
    { defaultValue: 'false', mode: 'development' },
  ]}
/>

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

<PropertyType
  type="boolean | string"
  defaultValueList={[{ defaultValue: 'false' }]}
/>

Tells Rspack to set `process.env.NODE_ENV` to a given string value. `optimization.nodeEnv` uses [DefinePlugin](/plugins/webpack/define-plugin) unless set to false.
`optimization.nodeEnv` **defaults** to [mode](/config/mode) if set, else falls back to `'production'`.

Possible values:

- any string: the value to set `process.env.NODE_ENV` to.
- false: do not modify/set the value of `process.env.NODE_ENV`.

```js title="rspack.config.mjs"
export default {
  //...
  optimization: {
    nodeEnv: 'production',
  },
};
```

:::tip
When [mode](/config/mode) is set to `'none'`, `optimization.nodeEnv` defaults to `false`.
:::

## optimization.emitOnErrors

<PropertyType
  type="boolean"
  defaultValueList={[
    { defaultValue: 'false', mode: 'production' },
    { defaultValue: 'true', mode: 'development' },
  ]}
/>

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

<ApiMeta addedVersion="1.2.0" />

<PropertyType type="boolean" defaultValueList={[{ defaultValue: '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 do not enable this option.
:::



---
url: /config/plugins.md
---

# 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) 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/webpack/define-plugin) 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 the [Plugin Compatibility List](/guide/compatibility/plugin) 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/webpack/hot-module-replacement-plugin) 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/dev-server.md
---

import WebpackLicense from '@components/WebpackLicense';
import { Tabs, Tab } from '@theme';

<WebpackLicense from="https://webpack.js.org/configuration/dev-server/" />

# DevServer

This page describes the options that affect the behavior of [`@rspack/dev-server`](https://github.com/web-infra-dev/rspack-dev-server) (short: dev-server), based on `webpack-dev-server@5`, which facilitates rapid application development.

- **Type:** `object`

:::tip
If the current application does not depend on `@rspack/dev-server`, then the devServer config will have no effect.

For example, Rspack CLI depends on `@rspack/dev-server` by default, so the devServer config can be used in Rspack CLI projects. Rsbuild has implemented its own dev server and provides a separate "server" config, so the devServer config cannot be used in Rsbuild projects.
:::

## 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.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' | 'sockjs'`
- **Default:** `ws`

This option allows us either to choose the current `devServer` transport mode for clients individually or to provide custom client implementation. This allows specifying how the browser or other client communicates with the `devServer`.

:::tip
Providing `'ws'` or `'sockjs'` to [`webSocketServer`](#devserverwebsocketserver) is a shortcut to setting both `devServer.client.webSocketTransport` and `devServer.webSocketServer` to the given value.
:::

```js title="rspack.config.mjs"
export default {
  //...
  devServer: {
    client: {
      webSocketTransport: 'ws',
    },
    webSocketServer: 'ws',
  },
};
```

:::tip
When providing a custom client and server implementation make sure that they are compatible with one another to communicate successfully.
:::

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'),
  },
};
```

### 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 [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware) which handles Rspack assets.

```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.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) 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,
  },
};
```

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:** `[object, function]`

:::tip

`@rspack/dev-server` in Rspack uses the `webpack-dev-server` v5, and `devServer.proxy` is an array type. If the configuration you use is the object type of the v4 version, you need to first migrate it according to the [webpack-dev-server/migration-v5.md](https://github.com/webpack/webpack-dev-server/blob/master/migration-v5.md) migration.

:::

Proxying some URLs can be useful when you have a separate API backend development server and you want to send API requests on the same domain.

The dev-server makes use of the powerful [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware) package. Check out its [documentation](https://github.com/chimurai/http-proxy-middleware#options) for more advanced usages. Note that some of `http-proxy-middleware`'s features do not require a `target` key, e.g. its `router` feature, but you will still need to include a `target` key in your configuration here, otherwise `@rspack/dev-server` won't pass it along to `http-proxy-middleware`.

With a backend on `localhost:3000`, you can use this to enable proxying:

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

A request to `/api/users` will now proxy the request to `http://localhost:3000/api/users`.

If you don't want `/api` to be passed along, we need to rewrite the path:

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

A backend server running on HTTPS with an invalid certificate will not be accepted by default. If you want to, modify your configuration like this:

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

Sometimes you don't want to proxy everything. It is possible to bypass the proxy based on the return value of a function.

In the function, you get access to the request, response, and proxy options.

- Return `null` or `undefined` to continue processing the request with proxy.
- Return `false` to produce a 404 error for the request.
- Return a path to serve from, instead of continuing to proxy the request.

E.g. for a browser request, you want to serve an HTML page, but for an API request, you want to proxy it. You could do something like this:

```js title="rspack.config.mjs"
export default {
  //...
  devServer: {
    proxy: [
      {
        context: ['/api'],
        target: 'http://localhost:3000',
        bypass: function (req, res, proxyOptions) {
          if (req.headers.accept.indexOf('html') !== -1) {
            console.log('Skipping proxy for browser request.');
            return '/index.html';
          }
        },
      },
    ],
  },
};
```

If you want to proxy multiple, specific paths to the same target, you can use an array of one or more objects with a `context` property:

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

Note that requests to root won't be proxied by default. To enable root proxying, the [`devMiddleware.index`](#devserverdevmiddleware) option should be specified as a falsy value:

```js title="rspack.config.mjs"
export default {
  //...
  devServer: {
    devMiddleware: {
      index: false, // specify to enable root proxying
    },
    proxy: [
      {
        context: () => true,
        target: 'http://localhost:1234',
      },
    ],
  },
};
```

The origin of the host header is kept when proxying by default, you can set `changeOrigin` to `true` to override this behaviour. It is useful in some cases like using [name-based virtual hosted sites](https://en.wikipedia.org/wiki/Virtual_hosting#Name-based).

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

## devServer.server

- **Type:** `'http' | 'https' | 'spdy' | 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` using [spdy](https://www.npmjs.com/package/spdy) with a self-signed certificate:

```js title="rspack.config.mjs"
export default {
  //...
  devServer: {
    server: 'spdy',
  },
};
```

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:

<Tabs>
  <Tab label="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,
      },
    },
  },
};
```

  </Tab>
  <Tab label="CJS">

```js title="rspack.config.cjs"
const fs = require('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,
      },
    },
  },
};
```

  </Tab>
</Tabs>

## 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');
      }

      devServer.app.get('/setup-middleware/some/path', (_, response) => {
        response.send('setup-middlewares option GET');
      });

      // 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.send('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.send('Foo Bar!');
        },
      });

      middlewares.push((req, res) => {
        res.send('Hello World!');
      });

      return middlewares;
    },
  },
};
```

## devServer.static

- **Type:** `boolean | string | object | [string, object]`

This option allows configuring options for serving static files from the directory (by default 'public' directory). To disable set it to `false`:

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

To watch a single directory:

```js title="rspack.config.mjs"
export default {
  devServer: {
    static: ['assets'],
  },
};
```

To watch multiple static directories:

```js title="rspack.config.mjs"
export default {
  devServer: {
    static: ['assets', 'css'],
  },
};
```

## devServer.watchFiles

- **Type:** `string | object | [string, object]`

This option allows you to configure a list of globs/directories/files to watch for file changes. For example:

```js title="rspack.config.mjs"
export default {
  //...
  devServer: {
    watchFiles: ['src/**/*.php', 'public/**/*'],
  },
};
```

It is possible to configure advanced options for watching files. See the [`chokidar`](https://github.com/paulmillr/chokidar) documentation for the possible options.

```js title="rspack.config.mjs"
export default {
  //...
  devServer: {
    watchFiles: {
      paths: ['src/**/*.php', 'public/**/*'],
      options: {
        usePolling: false,
      },
    },
  },
};
```

## devServer.webSocketServer

- **Type:** `false | 'sockjs' | 'ws'`

This option allows us either to choose the current web-socket server or to provide custom web-socket 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.

```js title="rspack.config.mjs"
export default {
  //...
  devServer: {
    webSocketServer: 'ws',
  },
};
```



---
url: /config/cache.md
---

import PropertyType from '@components/PropertyType';

# Cache

Rspack caches snapshots and intermediate build artifacts, then reuses them in subsequent builds to improve build speed.

:::info Cache Type
Rspack supports both memory cache and experimental persistent cache. See [Persistent Cache](/config/experiments#persistent-cache) for more details.
:::

This configuration only controls whether caching is enabled.

<PropertyType
  type="boolean"
  defaultValueList={[
    { defaultValue: 'false', mode: 'production' },
    { defaultValue: 'true', mode: 'development' },
  ]}
/>

## Usage

You can disable the `cache` in your Rspack config:

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



---
url: /config/devtool.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/configuration/devtool/" />

# Devtool

Choose a style of source mapping to enhance the debugging process. These values can affect build and rebuild speed dramatically.

Use the [SourceMapDevToolPlugin](/plugins/webpack/source-map-dev-tool-plugin) or [EvalSourceMapDevToolPlugin](/plugins/webpack/eval-source-map-dev-tool-plugin) for a more fine grained configuration.

- **Type:**

```ts
type Devtool = 'string' | false;
```

- **Default:** `cheap-module-source-map` in development mode and `source-map` in production mode

## Configuration guide

### Step 1: determine debugging needs

- **Not required** → Set `devtool: false`
  - Disables all debugging information
  - Zero build overhead with maximum build speed
- **Required** → Proceed to [Step 2](#step-2-define-debugging-requirements)

### Step 2: define debugging requirements

- **Module-level positioning only** → Set `devtool: 'eval'`
  - Each module executed via `eval()` with `//# sourceURL` comment
  - Extremely fast build speed
- **Full source code mapping needed** → Proceed to [Step 3](#step-3-configure-sourcemap)

### Step 3: configure source map

Set `devtool: 'source-map'`, A full source map is emitted as a separate file. It adds a `//# sourceMapURL` comment to the bundle so development tools know where to find it.

It also supports combination with the following modifiers to improve performance and control source map generation.

Performance optimization modifiers, to speed up the build, usually used in development environments:

| Modifier | Effect                                                                                                                                         | Performance improvement |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| eval     | Each module is executed with `eval()` and a source map is added as a DataUrl to the `eval()`, avoiding chunk-level multiple source map concate | ⚡⚡⚡                  |
| cheap    | Maps line numbers only (no columns), ignores source maps from loaders                                                                          | ⚡⚡                    |
| module   | Processes source maps from loaders to map to original code (line-only mapping)                                                                 | ⚡                      |

Functional modifiers, to control source map generation, usually used in production environments:

| Modifier  | Effect                                                                                                                                       |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| hidden    | source map is emitted as a separate file, but no `//# sourceMappingURL=[url]` comment is added to the bundle, protecting source code privacy |
| inline    | source map is added as a DataUrl to the bundle                                                                                               |
| nosources | source map is created without the `sourcesContent` in it                                                                                     |
| debugids  | source map is created with the `debugId` in it                                                                                               |

We expect a certain pattern when validate devtool name, pay attention and don't mix up the sequence of devtool string. The pattern is: `[inline-|hidden-|eval-][nosources-][cheap-[module-]]source-map[-debugids]`.

## Recommended configurations

### Development

The following options are ideal for development:

`eval` - Each module is executed with `eval()` and `//# sourceURL`. This is pretty fast. The main disadvantage is that it doesn't display line numbers correctly since it gets mapped to transpiled code instead of the original code (No source maps from Loaders).

`eval-source-map` - Each module is executed with `eval()` and a source map is added as a DataUrl to the `eval()`. Initially it is slow, but it provides fast rebuild speed and yields real files. Line numbers are correctly mapped since it gets mapped to the original code. It yields the best quality source maps for development.

`eval-cheap-source-map` - Similar to `eval-source-map`, each module is executed with `eval()`. It is "cheap" because it doesn't have column mappings, it only maps line numbers. It ignores source maps from Loaders and only display transpiled code similar to the eval devtool.

`eval-cheap-module-source-map` - Similar to `eval-cheap-source-map`, however, in this case source maps from Loaders are processed for better results. However Loader source maps are simplified to a single mapping per line.

### Production

These options are typically used in production:

'false' - No source map is emitted. This is a good option to start with.

`source-map` - A full source map is emitted as a separate file. It adds a reference comment to the bundle so development tools know where to find it.

`hidden-source-map` - Same as `source-map`, but doesn't add a reference comment to the bundle. Useful if you only want source maps to map error stack traces from error reports, but don't want to expose your source map for the browser development tools.

`nosources-source-map` - A source map is created without the `sourcesContent` (the original source code) in it. It still exposes the original filenames and structure and can be used to map stack traces on the client without exposing the source code. This kind of source map can be deployed to the web server if you can accept the file name being exposed.

:::warning
When using `source-map` or `hidden-source-map`, do not deploy the source maps (`.map` file) to the public web server or CDN. Public source maps will expose your source code and may bring security risks.
:::



---
url: /config/target.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/configuration/target/" />

# Target

Used to configure the target environment of Rspack output and the ECMAScript version of Rspack runtime code.

- **Type:** `string | string[]`
- **Default:** `browserslist` if the current project has a browserslist config, otherwise `web`.

## string

The following options are now supported:

| options                      | description                                                                                                                                                                                                                                   |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `'web'`                      | Compile as available in the browser environment (default)                                                                                                                                                                                     |
| `'webworker'`                | Compile as Web Worker                                                                                                                                                                                                                         |
| `'browserslist'`             | Infer the ES-features version based on the configured browserslist (default if browserslist config is available)                                                                                                                              |
| `'node[[X].Y]'`              | Compile as available for Node.js environments                                                                                                                                                                                                 |
| `'async-node[[X].Y]'`        | Compile for usage in a Node.js-like environment (uses fs and vm to load chunks asynchronously)                                                                                                                                                |
| `'esX'`                      | Compile Rspack runtime to the corresponding ECMAScript version. Currently supports `es3`, `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020`, `es2021`, `es2022`, `es2023`, `es2024`, `es2025` (es5 is used by default)        |
| `'electron[[X].Y]-main'`     | Compile for Electron for main process.                                                                                                                                                                                                        |
| `'electron[[X].Y]-renderer'` | Compile for Electron for renderer process, providing a target using `array-push` as chunkFormat and `jsonp` as chunkLoading for browser environments and `NodeTargetPlugin` and `ExternalsPlugin` for CommonJS and Electron built-in modules. |
| `'electron[[X].Y]-preload'`  | Compile for Electron for preload script of renderer process                                                                                                                                                                                   |
| `'nwjs[[X].Y]'`              | Compile as available for NW.js environments                                                                                                                                                                                                   |
| `'node-webkit[[X].Y]'`       | Compile as available for node-webkit environments                                                                                                                                                                                             |

:::warning Scope of esX

The `esX` in the `target` configuration can only specify the ECMAScript version of the Rspack runtime code. If you want to specify the ECMAScript version of the user code, you can use [builtin:swc-loader](/guide/features/builtin-swc-loader.html) or [babel-loader](https://www.npmjs.com/package/babel-loader) to degrade the user code.

:::

## Example

Specify that the Compiler needs to compile to the Node.js environment:

```js title="rspack.config.mjs"
export default {
  target: 'node',
};
```

When multiple targets are passed, then common subset of features will be used:

```js title="rspack.config.mjs"
export default {
  // Rspack will generate a runtime code for web platform and will use only ES5 features
  target: ['web', 'es5'],
};
```

Note that not all targets may be mixed for now. When specifying that the Compiler needs to be compiled for multiple platforms, an error is reported:

```js title="rspack.config.mjs"
export default {
  target: ['web', 'node'],
};
```

For this case, you can define multiple Rspack configurations for bundling based on [MultiCompiler](/api/javascript-api/index#multicompiler).

## browserslist

If the current project has a browserslist config, then Rspack will use it for:

- Determinate ES-features that may be used to generate the **Rspack runtime code** (this will not affect the transpilation result of user code).
- Infer a target environment (e.g: `last 2 node versions` the same as `target: "node"` with some [`output.environment`](/config/output#outputenvironment) settings).

:::tip What is Browserslist
[Browserslist](https://browsersl.ist/) can specify which browsers your web application can run in, it provides a configuration for specifying browsers range. Browserslist has become a standard in the industry, it is used by libraries such as Autoprefixer, Babel, ESLint, PostCSS, SWC and webpack.
:::

Supported browserslist values:

- `browserslist` - use automatically resolved browserslist config and environment (from the nearest `.browserslistrc` file, `package.json`'s `browserslist` field, or `BROWSERSLIST` environment variable, see [browserslist documentation](https://github.com/browserslist/browserslist#queries) for details)
- `browserslist:modern` - use `modern` environment from automatically resolved browserslist config
- `browserslist:last 2 versions` - use an explicit browserslist query (config will be ignored)
- `browserslist:/path/to/config` - explicitly specify browserslist config
- `browserslist:/path/to/config:modern` - explicitly specify browserslist config and an environment

### Limitations

Rspack uses [browserslist-rs](https://github.com/browserslist/browserslist-rs), a Rust implementation of Browserslist, and does not yet fully support all Browserslist features.

Currently unsupported features:

- Baseline queries, such as `baseline widely available`
- Custom usage queries, such as `> 0.5% in my stats`
- Coverage-based usage queries, such as `cover 99.5% in my stats`

## Node.js version

A version of node or electron may be optionally specified. This is denoted by the [[X].Y] in the table above.

```js title="rspack.config.mjs"
export default {
  target: 'node18.12',
};
```

When Rspack generates runtime code, this helps determine which ES features can be used (all chunks and modules are wrapped by runtime code).

## target: false

If none of the predefined targets in the above list meet your needs, you can set `target` to `false`, which will instruct Rspack not to use any plugins.

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



---
url: /config/watch.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/configuration/watch" />

# 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[]`
- **Default:** `/[\\/](?:\.git|node_modules)[\\/]/`

The path that matches is excluded while watching. Watching many files can result in a lot of CPU or memory usage.

Since Rspack v1.2.0, `node_modules` and `.git` directories are excluded by default. This means that changes to files in these directories will not trigger a rebuild.

If you want to watch the `node_modules` directory, you can set it to only exclude the `.git` directory:

```js title="rspack.config.mjs"
export default {
  //...
  watchOptions: {
    ignored: /\.git/,
  },
};
```

`ignored` can use glob matching:

```js title="rspack.config.mjs"
export default {
  //...
  watchOptions: {
    ignored: '**/.git',
  },
};
```

It is also possible to use multiple glob patterns:

```js title="rspack.config.mjs"
export default {
  //...
  watchOptions: {
    ignored: ['**/files/**/*.js', '**/.git', '**/node_modules'],
  },
};
```

In addition, you can specify one or more absolute paths:

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

export default {
  //...
  watchOptions: {
    ignored: [path.posix.resolve(__dirname, './ignored-dir')],
  },
};
```

When using glob patterns, Rspack convert them to regular expressions with [glob-to-regexp](https://github.com/fitzgen/glob-to-regexp), so make sure to get yourself familiar with it before you use glob patterns for watchOptions.ignored.

### watchOptions.poll

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

Whether to watch by polling.

When set to `true`, the default polling interval is 5007 milliseconds.

```js title="rspack.config.mjs"
export default {
  //...
  watchOptions: {
    poll: true,
  },
};
```

It can also set a custom polling interval:

```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#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,
  },
};
```



---
url: /config/externals.md
---

import WebpackLicense from '@components/WebpackLicense';
import { Stability } from '../../../components/ApiMeta';

<WebpackLicense from="https://webpack.js.org/configuration/externals/" />

# Externals

The `externals` configuration option provides a way of excluding dependencies from the output bundles. Instead, the created bundle relies on that dependency to be present in the consumer's (any end-user application) environment. This feature is typically most useful to **library developers**, however there are a variety of applications for it.

## externals

- **Type:** `string | object | function | RegExp | Array<string | object | function | RegExp>`

**Prevent bundling** of certain `import`ed packages and instead retrieve these _external dependencies_ at runtime.

For example, to include [jQuery](https://jquery.com/) from a CDN instead of bundling it:

```html title="index.html"
<script
  src="https://code.jquery.com/jquery-3.1.0.js"
  integrity="sha256-slogkvB1K3VOkzAI8QITxV3VzpOnkeNVsKvtkYLMjfk="
  crossorigin="anonymous"
></script>
```

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

This leaves any dependent modules unchanged, i.e. the code shown below will still work:

```js
import $ from 'jquery';

$('.my-element').animate(/* ... */);
```

The property name `jquery` specified under `externals` in the above Rspack configuration indicates that the module `jquery` in `import $ from 'jquery'` should be excluded from bundling. In order to replace this module, the value `jQuery` will be used to retrieve a global `jQuery` variable, as the default external library type is `var`, see [externalsType](#externalstype).

While we showed an example consuming external global variable above, the external can actually be available in any of these forms: global variable, CommonJS, AMD, ES2015 Module, see more in [externalsType](#externalstype).

### string

Depending on the [externalsType](#externalstype), this could be the name of the global variable (see [`'global'`](#externalstypeglobal), [`'this'`](#externalstypethis), [`'var'`](#externalstypevar), [`'window'`](#externalstypewindow)) or the name of the module (see `amd`, [`commonjs`](#externalstypecommonjs), [`module`](#externalstypemodule), `umd`).

You can also use the shortcut syntax if you're defining only 1 external:

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

equals to

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

You can specify the [external library type](#externalstype) to the external with the `${externalsType} ${libraryName}` syntax. It will override the default external library type specified in the [externalsType](#externalstype) option.

For example, if the external library is a [CommonJS module](#externalstypecommonjs), you can specify

```js title="rspack.config.mjs"
export default {
  //...
  externals: {
    jquery: 'commonjs jquery',
  },
};
```

### 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 [`libraryTarget: 'umd'`](/config/output#outputlibrarytarget) and [`externalsType: 'umd'`](#externalstype). It's not allowed for other library targets.
:::

```js title="rspack.config.mjs"
export default {
  externals: {
    // When `libraryTarget: '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`): Describes the external module with the other external formats ([`string`](#string), [`string[]`](#string-array), or [`object`](#object))
- `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

Every dependency that matches the given regular expression will be excluded from the output bundles.

```js title="rspack.config.mjs"
export default {
  //...
  externals: /^(jquery|\$)$/i,
};
```

In this case, any dependency named `jQuery`, capitalized or not, or `$` would be externalized.

### 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`
- **Default:** `'var'`

Specify the default type of externals. `amd`, `umd`, `system` and `jsonp` externals **depend on the [`output.libraryTarget`](/config/output#outputlibrarytarget)** being set to the same value e.g. you can only consume `amd` externals within an `amd` library.

Supported types:

- `'amd'`
- `'amd-require'`
- `'assign'` - same as `'var'`
- [`'commonjs'`](#externalstypecommonjs)
- `'commonjs-module'`
- [`'global'`](#externalstypeglobal)
- [`'module'`](#externalstypemodule)
- [`'import'`](#externalstypeimport) - uses `import()` to load a native ECMAScript module (async module)
- [`'module-import'`](#externalstypemodule-import)
- [`'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#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 [`experiments.outputModule`](/config/experiments#experimentsoutputmodule) first, otherwise Rspack will throw errors.

**Example**

```js
import jq from 'jquery';
jq('.my-element').animate(/* ... */);
```

```js title="rspack.config.mjs"
export default {
  experiments: {
    outputModule: 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');
  },
};

// webpack 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.

Make sure to enable [`experiments.outputModule`](/config/#experimentsoutputmodule) first if static imports exist, otherwise Rspack will throw errors.

**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');
  },
};

// webpack 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['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 {
  experiments: {
    outputModule: true,
  },
  externalsType: 'node-commonjs',
  externals: {
    jquery: 'jquery',
  },
};
```

Will generate into something like

```js
import { createRequire } from '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#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,
  },
};
```



---
url: /config/performance.md
---

import PropertyType from '../../../components/PropertyType.tsx';
import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/configuration/performance/" />

# Performance

These options allows you to control how Rspack notifies you of assets and entry points that exceed a specific file limit.

## performance

<PropertyType type="false | object" />

Configure how performance hints are shown. For example if you have an asset that is over 250kb, Rspack will emit a warning notifying you of this.

### performance.assetFilter

<PropertyType type="(assetFilename: string) => boolean" />

This property allows Rspack to control what files are used to calculate performance hints.

### performance.hints

<PropertyType
  type="false | 'error' | 'warning'"
  defaultValueList={[
    { defaultValue: 'warning', mode: 'production' },
    { defaultValue: 'false', mode: 'development' },
  ]}
/>

Turns hints on/off. In addition, tells Rspack to throw either an error or a warning when hints are found.

### performance.maxAssetSize

<PropertyType type="number" defaultValueList={[{ defaultValue: '250000' }]} />

An asset is any emitted file from Rspack. This option controls when Rspack emits a performance hint based on individual asset size in bytes.

### performance.maxEntrypointSize

<PropertyType type="number" defaultValueList={[{ defaultValue: '250000' }]} />

An entry point represents all assets that would be utilized during initial load time for a specific entry. This option controls when Rspack should emit performance hints based on the maximum entry point size in bytes.



---
url: /config/lazy-compilation.md
---

import WebpackLicense from '@components/WebpackLicense';
import { ApiMeta } from '@components/ApiMeta';

<WebpackLicense from="https://webpack.js.org/configuration/experiments/#experimentslazycompilation" />

# LazyCompilation

<ApiMeta addedVersion="1.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).

## **lazyCompilation**

- **Type:** `boolean | LazyCompilationOptions`
- **Default:** `{ entries: false, imports: true }` when [`Target`](/config/target) is for `'web'` applications only, `false` for others.

```ts
type LazyCompilationOptions =
  | boolean
  | {
      /**
       * Enable lazy compilation for entries.
       * @default true
       */
      entries?: boolean;
      /**
       * Enable lazy compilation for dynamic imports.
       * @default true
       */
      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 "/lazy-compilation-using-"
       */
      prefix?: string;
    };
```

:::tip
Check out the [guide](/guide/features/lazy-compilation) for a quick start.
:::

If you have twenty entry points, only the accessed entry points will be built when you enable lazyCompilation. Or if there are many `import()` statements in the project, each module pointed to by `import()` will only be built when it is actually accessed.

If set to `true`, lazy compilation will be applied by default to both entry modules and modules pointed to by `import()`. You can decide whether it applies only to entries or only to `import()` through a configuration object. The `entries` option determines whether it applies to entries, while the `import()` option determines whether it applies to `import()`.

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

export default {
  lazyCompilation: {
    client: path.resolve('custom-client.js'),
  },
};
```

In addition, you can also configure a `test` parameter for more fine-grained control over which modules are lazily compiled. The `test` parameter can be a regular expression that matches only those modules that should be lazily compiled. It can also be a function where the input is of type 'Module' and returns a boolean value indicating whether it meets the criteria for lazy compilation logic.

### lazyCompilation.client

- **Type:** `string`

The path to a custom runtime code that overrides the default lazy compilation client. If you want to customize the logic of the client runtime, you can specify it through this option.

- [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 'path';

export default {
  lazyCompilation: {
    client: path.resolve('custom-client.js'),
  },
};
```

### lazyCompilation.serverUrl

- **Type:** `string`

Tells the client the server path that needs to be requested. By default it is empty, in a browser environment it will find the server path where the page is located, but in a node environment you need to explicitly specify a specific path.

```js title="rspack.config.mjs"
export default {
  lazyCompilation: {
    serverUrl: 'http://localhost:3000',
  },
};
```

### lazyCompilation.prefix

- **Type:** `string`
- **Default:** `'/lazy-compilation-using-'`

Customize the prefix used for lazy compilation endpoint. By default, the lazy compilation middleware uses the `/lazy-compilation-using-` prefix for handling requests.

```js title="rspack.config.mjs"
export default {
  lazyCompilation: {
    prefix: '/custom-lazy-endpoint-',
  },
};
```

### 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);
```



---
url: /config/stats.md
---

import PropertyType from '../../../components/PropertyType.tsx';
import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/configuration/stats/" />

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

:::

<PropertyType
  type="boolean | string | Object"
  defaultValueList={[
    {
      defaultValue: `{"preset":"errors-warnings","timings":true}`,
    },
  ]}
/>

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

<PropertyType
  type="boolean"
  defaultValueList={[{ defaultValue: '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

<PropertyType
  type="boolean | string"
  defaultValueList={[{ defaultValue: 'undefined' }]}
/>

Sets the [preset](/config/stats#stats-presets) for the type of information that gets displayed. It is useful for [extending stats behaviours](/config/stats#extending-stats-behaviours).

## Asset options

### stats.assets

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display the asset information. See [Asset Object](/api/javascript-api/stats-json#asset-object) for more details.

### stats.assetsSort

<PropertyType type="string" defaultValueList={[{ defaultValue: '"id"' }]} />

Sort the assets by a given field. All of the [sorting fields](/config/stats#sorting-fields) are allowed to be used. Use `!` prefix in the value to reverse the sort order by a given field.

### stats.assetsSpace

<PropertyType type="number" defaultValueList={[{ defaultValue: '15' }]} />

How many items of assets should be displayed (groups will be collapsed to fit this space).

### stats.relatedAssets

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'false' }]} />

Whether to display information about assets that are related to other assets (like SourceMaps for assets).

### stats.excludeAssets

<PropertyType
  type="Array<string | RegExp | (name: string) => boolean> | string | RegExp | (name: string) => boolean | false"
  defaultValueList={[{ defaultValue: 'false' }]}
/>

Exclude the matching assets information. This can be done with a string, a RegExp, a function that is getting the assets name as an argument and returns a boolean. `stats.excludeAssets` can be an array of any of the above.

### stats.cachedAssets

<PropertyType type="boolean" defaultValueList={[{ defaultValue: '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

<PropertyType type="boolean" />

Whether to group assets by how their are related to chunks.

### stats.groupAssetsByEmitStatus

<PropertyType type="boolean" />

Whether to group assets by their status (emitted, compared for emit or cached).

### stats.groupAssetsByExtension

<PropertyType type="boolean" />

Whether to group assets by their extension.

### stats.groupAssetsByInfo

<PropertyType type="boolean" />

Whether to group assets by their asset info (immutable, development, hotModuleReplacement, etc).

### stats.groupAssetsByPath

<PropertyType type="boolean" />

Whether to group assets by their asset path.

## Chunk options

### stats.chunks

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display information about the chunk, see [chunk object](/api/javascript-api/stats-json#chunk-object) for more details.

### stats.chunkModules

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display information about the built modules to information about the chunk.

### stats.chunkModulesSpace

<PropertyType type="number" defaultValueList={[{ defaultValue: '10' }]} />

How many items of chunk modules should be displayed (groups will be collapsed to fit this space).

### stats.dependentModules

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'false' }]} />

Whether to display chunk modules that are dependencies of other modules of the chunk.

### stats.chunkOrigins

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display information about the origins of chunks and chunk merging.

### stats.chunkRelations

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'false' }]} />

Whether to display chunk parents, children and siblings.

### stats.chunksSort

<PropertyType type="string" defaultValueList={[{ defaultValue: '"id"' }]} />

Sort the chunks by a given field. All of the [sorting fields](/config/stats#sorting-fields) are allowed to be used. Use `!` prefix in the value to reverse the sort order by a given field.

### stats.ids

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'false' }]} />

Whether to display IDs of modules and chunks.

## ChunkGroup options

### stats.chunkGroups

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display information about the `namedChunkGroups`, see [chunk group object](/api/javascript-api/stats-json#entrychunkgroup-object) for more details.

### stats.chunkGroupAuxiliary

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display auxiliary assets in chunk groups.

### stats.chunkGroupChildren

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display children of the chunk groups (e.g. prefetched, preloaded chunks and assets).

### stats.chunkGroupMaxAssets

<PropertyType type="number" defaultValueList={[{ defaultValue: '5' }]} />

How many assets should be displayed in chunk groups.

### stats.entrypoints

<PropertyType
  type="boolean | 'auto'"
  defaultValueList={[{ defaultValue: 'false' }]}
/>

Whether to display the entry points with the corresponding bundles, , see [entrypoint object](/api/javascript-api/stats-json#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

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display information about the built modules, see [module object](/api/javascript-api/stats-json#module-object) for more details.

### stats.moduleTrace

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display dependencies and the origin of warnings/errors.

### stats.moduleAssets

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to add information about assets inside modules.

### stats.modulesSpace

<PropertyType type="number" defaultValueList={[{ defaultValue: '15' }]} />

How many items of modules should be displayed (groups will be collapsed to fit this space).

### stats.modulesSort

<PropertyType type="string" defaultValueList={[{ defaultValue: '"id"' }]} />

Sort the modules by a given field. All of the [sorting fields](/config/stats#sorting-fields) are allowed to be used. Use `!` prefix in the value to reverse the sort order by a given field.

### stats.reasons

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display information about the reasons of why modules are included.

### stats.reasonsSpace

<PropertyType type="number" defaultValueList={[{ defaultValue: '1000' }]} />

How many characters should the reasons be displayed (groups will be collapsed to fit this space).

### stats.source

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'false' }]} />

Whether to display the source code of modules.

### stats.depth

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'false' }]} />

Whether to display the distance from the entry point for each module.

### stats.orphanModules

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'false' }]} />

Whether to display the orphan modules.

> A module is an orphan if it is not included in any chunk.

### stats.runtimeModules

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display information about runtime modules.

> The runtime modules are built-in modules of Rspack, used to provide various runtime capabilities.

### stats.cachedModules

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display information about cached (not built) modules.

### stats.excludeModules

<PropertyType
  type="Array<string | RegExp | (name: string) => boolean> | string | RegExp | (name: string) => boolean | false"
  defaultValueList={[{ defaultValue: 'false' }]}
/>

Exclude the matching modules information. This can be done with a string, a RegExp, a function that is getting the modules name as an argument and returns a boolean. `stats.excludeAssets` can be an array of any of the above.

### stats.nestedModules

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display information about modules nested in other modules (like with module concatenation).

### stats.nestedModulesSpace

<PropertyType type="number" defaultValueList={[{ defaultValue: '10' }]} />

How many items of nested modules should be displayed (groups will be collapsed to fit this space).

## Module grouping options

### stats.groupModulesByAttributes

<PropertyType type="boolean" />

Whether to group modules by their attributes (errors, warnings, assets, optional, orphan, or dependent).

### stats.groupModulesByCacheStatus

<PropertyType type="boolean" />

Whether to group modules by their cache status (cached or built and cacheable).

### stats.groupModulesByExtension

<PropertyType type="boolean" />

Whether to group modules by their extension.

### stats.groupModulesByPath

<PropertyType type="boolean" />

Whether to group modules by their path.

### stats.groupModulesByType

<PropertyType type="boolean" />

Whether to group modules by their type.

### stats.groupModulesByLayer

<PropertyType type="boolean" />

Whether to group modules by their layer.

### stats.groupReasonsByOrigin

<PropertyType type="boolean" />

Group reasons by their origin module to avoid large set of reasons.

## Optimization options

### stats.providedExports

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'false' }]} />

Whether to display the exports of the modules.

### stats.usedExports

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'false' }]} />

Whether to display which exports of a module are used.

### stats.optimizationBailout

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'false' }]} />

Whether to display the reasons why optimization bailed out for modules.

## Error/Warning options

### stats.errors

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display the errors.

### stats.errorsCount

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display the errors count.

### stats.errorDetails

<PropertyType type="boolean" defaultValueList={[{ defaultValue: '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

<PropertyType type="number" defaultValueList={[{ defaultValue: '5' }]} />

How many lines should an error be displayed.

### stats.errorStack

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display stack trace of errors.

### stats.warnings

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display the warnings.

### stats.warningsCount

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display the warnings count.

### stats.warningsSpace

<PropertyType type="number" defaultValueList={[{ defaultValue: '5' }]} />

How many lines should a warning be displayed.

## Logging options

### stats.logging

<PropertyType 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

<PropertyType type="Array<string | RegExp | function (name) => boolean>" />

Whether to display the debug information of the specified [loggers](/api/javascript-api/logger) 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

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display stack traces in the logging output for errors, warnings and traces.

### stats.colors

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'false' }]} />

Whether to output in the different colors.

Defaults to `true` when executing `rspack build` in an environment that supports color output.

## Compilation options

### stats.hash

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display information about the hash of the compilation.

### stats.env

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'false' }]} />

Whether to display the `--env` information.

### stats.builtAt

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display the build date and the build time information.

### stats.version

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to add information about the Rspack version used.

### stats.context

<PropertyType type="string" />

Whether to display the [base directory](/config/context) as an absolute path for shortening the module specifier.

### stats.publicPath

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display the [`publicPath`](/config/output#outputpublicpath).

### stats.outputPath

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display the [`output.path`](/config/output#outputpath).

### stats.children

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display the [`output.path`](/config/output#outputpath).

### stats.performance

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to display performance hint when the file size exceeds [`performance.maxAssetSize`](/config/performance#performancemaxassetsize).

### stats.timings

<PropertyType type="boolean" defaultValueList={[{ defaultValue: '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.
- `'profile'`: items's processing cost.
- `'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,
  },
};
```



---
url: /config/experiments.md
---

import { ApiMeta, Stability } from '../../../components/ApiMeta';
import WebpackLicense from '@components/WebpackLicense';
import PropertyType from '@components/PropertyType';

<WebpackLicense from="https://webpack.js.org/configuration/experiments/" />

# 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:** `false`

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,
  },
};
```

This is enabled by default when [experiments.futureDefaults](#experimentsfuturedefaults) is set to `true`.

## experiments.outputModule

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

When enabled, Rspack outputs ECMAScript module syntax whenever possible. For example, `import()` to load chunks, ESM exports to expose chunk data, and more.

```js title="rspack.config.mjs"
export default {
  experiments: {
    outputModule: true,
  },
};
```

## experiments.css

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

When enabled, Rspack enables native CSS support and CSS-related parser and generator options.

- [`module.parser["css/auto"]`](/config/module#moduleparsercssauto)
- [`module.parser.css`](/config/module#moduleparsercss)
- [`module.parser["css/module"]`](/config/module#moduleparsercssmodule)
- [`module.generator["css/auto"]`](/config/module#modulegeneratorcssauto)
- [`module.generator.css`](/config/module#modulegeneratorcss)
- [`module.generator["css/module"]`](/config/module#modulegeneratorcssmodule)

Basic example:

```js title="rspack.config.mjs"
export default {
  experiments: {
    css: true,
  },
};
```

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

<ApiMeta addedVersion="1.1.0-beta.0" />

- **Type:** `boolean | 'none' | 'safe' | 'advance' | 'advance-silent' | Incremental`
- **Default:** `'advance-silent'`

Whether to enable incremental build, which significantly speeds up rebuilds and HMR by only rebuilding the changed parts. Two configuration ways are provided:

1. Presets: including `boolean | 'none' | 'safe' | 'advance' | 'advance-silent'`
   - `false | 'none'`: Disable incremental, and it will not be enabled for any stage.
   - `'safe'`: Enable incremental for `make` and `emitAssets` stages, This is also the current default behavior of Rspack.
   - `true | 'advance-silent'`: Enable incremental for all stages to maximize performance for rebuilds and HMR. After these stages become stable in the future, we will make this option the default behavior for Rspack.
   - `'advance'`: The same as above, but it will detect cases that are unfriendly to incremental and throw warnings to users (e.g., incorrect configurations). This option can help you to identify potential issues affecting incremental build performance.
2. **Detailed object configuration**: `Incremental`, which allows fine-grained control over whether the incremental is enabled for each stage.

   {/* prettier-ignore */}
   <details>
      <summary style={{ display: 'list-item' }}>Detailed type of `Incremental`</summary>
      <blockquote>
        <p>
        ```ts
        type Incremental = {
          // Whether to throw a warning when encountering situations that are not friendly for incremental.
          silent?: boolean;
          // The following configuration is used to control whether the incremental of each stage is enabled.
          make?: boolean;
          inferAsyncModules?: boolean;
          providedExports?: boolean;
          dependenciesDiagnostics?: boolean;
          sideEffects?: boolean;
          buildChunkGraph?: boolean;
          moduleIds?: boolean;
          chunkIds?: boolean;
          modulesHashes?: boolean;
          modulesCodegen?: boolean;
          modulesRuntimeRequirements?: boolean;
          chunksRuntimeRequirements?: boolean;
          chunksHashes?: boolean;
          chunksRender?: boolean;
          emitAssets?: boolean;
        };
        ```
        </p>
      </blockquote>
    </details>

Usually, we recommend configuring in the preset way, and the detailed object configuration is only provided to facilitate bug troubleshooting.

Incremental only improves the rebuild performance and have no impact on the initial build. However, when persistent cache is available, initial builds are also treated as rebuilds too, and can benefit from incremental for performance.

The table below shows the results of incremental in different scenarios:

| how to build | incremental speed up |
| :----------: | :------------------: |
|  hot build   |          ✅          |
|  cold build  |          ❌          |
|  hot start   |          ✅          |
|  cold start  |          ❌          |
| rebuild/HMR  |          ✅          |

Starting from v1.4.0, Rspack enables incremental builds for all phases by default using `'advance-silent'` mode. In previous versions, it only activated incremental builds for the `make` and `emitAssets` phases by default with `'safe'` mode.

## experiments.parallelLoader

<ApiMeta addedVersion="1.3.1" />

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

Enable parallel loader execution. You need to manually enable parallel mode for each loader using [`rules[].use.parallel`](/config/module-rules#rulesuseparallel). When enabled, the corresponding loaders will be executed in worker threads.

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

## experiments.rspackFuture

- **Type:** `object`

- **Default:** See options down below for details

Used to control whether to enable Rspack future default options, check out the details [here](https://github.com/web-infra-dev/rspack/pull/4107).

### rspackFuture.bundlerInfo

<ApiMeta addedVersion="1.0.0" />

- **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 `true` to force injection. An array can be used to select the items to be forced injected.

#### Disable default injection

The default injection can be disabled by setting `force` to `false`. Then injection will only occur when `__rspack_version__` and `__rspack_unique_id__` are detected in the code:

- [`__rspack_version__`](/api/runtime-api/module-variables#__rspack_version__): Inject version information.
- [`__rspack_unique_id__`](/api/runtime-api/module-variables#__rspack_unique_id__): Inject the unique ID of the bundler.

```js title="rspack.config.mjs"
export default {
  experiments: {
    rspackFuture: { bundlerInfo: { force: false } },
  },
};
```

## experiments.cache

<ApiMeta addedVersion="1.2.0-alpha.0" />

- **Type:** `ExperimentCacheOptions`

- **Default:** production mode is `false`, development mode is `true`

```ts
type ExperimentCacheOptions =
  | boolean
  | {
      type: 'memory';
    }
  | {
      type: 'persistent';
      buildDependencies?: string[];
      version?: string;
      snapshot?: {
        immutablePaths?: Array<string | RegExp>;
        unmanagedPaths?: Array<string | RegExp>;
        managedPaths?: Array<string | RegExp>;
      };
      storage?: {
        type: 'filesystem';
        directory?: string;
      };
    };
```

Control experimental caching behavior. This will only work if [config.cache](/config/cache) is set to `true`.

:::info Note
In production mode, the default value of `config.cache` is `false`, which will cause this configuration item invalid. It is recommended to directly configure `config.cache` to `true`.
:::

### Disable cache

Configuring `experiment.cache` to `false` to disable cache, which is no different from configuring the [config.cache](/config/cache) to `false`.

```js title="rspack.config.mjs"
export default {
  cache: true,
  experiments: {
    cache: false,
  },
};
```

### Memory cache

Configuring `experiment.cache` to `true` or `{ "type": "memory" }` to enable memory cache.

```js title="rspack.config.mjs"
export default {
  cache: true,
  experiments: {
    cache: true,
  },
};
```

### Persistent cache

Configuring `experiment.cache` to `{ "type": "persistent" }` to enable persistent cache.

```js title="rspack.config.mjs"
export default {
  cache: true,
  experiments: {
    cache: {
      type: 'persistent',
    },
  },
};
```

#### cache.buildDependencies

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

- **Default:** `[]`

`cache.buildDependencies` is an array of files containing build dependencies, Rspack will use the hash of each of these files to invalidate the persistent cache.

:::tip
It's recommended to set `cache.buildDependencies`: [__filename] in your rspack configuration to get the latest configuration.
:::

```js title="rspack.config.mjs"
export default {
  cache: true,
  experiments: {
    cache: {
      type: 'persistent',
      buildDependencies: [__filename, path.join(__dirname, './tsconfig.json')],
    },
  },
};
```

#### cache.version

- **Type:** `string`

- **Default:** `""`

Cache versions, different versions of caches are isolated from each other.

:::tip Persistent cache invalidation

In addition to [buildDependencies](#cachebuilddependencies) and [version](#cacheversion) configurations that affect persistent cache invalidation, Rspack also invalidates persistent cache when the following fields change.

- [config.name](/config/other-options#name)
- [config.mode](/config/mode#mode)

:::

#### cache.snapshot

Configure snapshot strategy. Snapshot is used to determine which files have been modified during shutdown. The following configurations are supported:

##### snapshot.immutablePaths

- **Type:** `(RegExp | string)[]`

- **Default:** `[]`

An array of paths to immutable files, changes to these paths will be ignored during hot restart.

##### snapshot.managedPaths

- **Type:** `(RegExp | string)[]`

- **Default:** `[/[\\/]node_modules[\\/][^.]/]`

An array of paths managed by the package manager. During hot start, it will determine whether to modify the path based on the version in package.json.

##### snapshot.unmanagedPaths

- **Type:** `(RegExp | string)[]`

- **Default:** `[]`

Specifies an array of paths in `snapshot.managedPaths` that are not managed by the package manager

#### cache.storage

- **Type:** `{ type: 'filesystem', directory: string }`

- **Default:** `{ type: 'filesystem', directory: 'node_modules/.cache/rspack' }`

Configure cache storage. Currently only file system storage is supported. The cache directory can be set through `directory`. The default is `node_modules/.cache/rspack`.

```js title="rspack.config.mjs"
export default {
  cache: true,
  experiments: {
    cache: {
      type: 'persistent',
      storage: {
        type: 'filesystem',
        directory: 'node_modules/.cache/rspack',
      },
    },
  },
};
```

:::tip
Rspack will generate a cache folder in the `storage.directory` based on [config.name](/config/other-options#name), [config.mode](/config/mode#mode), the file contents in [buildDependencies](#cachebuilddependencies) and [version](#cacheversion).

Rspack will automatically clean up cache folders that have not been accessed for a long time (7 days) at startup.
:::

### Migrating from webpack config

The Rspack cache configuration is different from the webpack cache configuration. You can refer to the following steps to migrate the webpack cache configuration.

1. According to the cache type, set the Rspack cache type. Continue with the next step for persistent cache, and stop here for other types of cache.

```diff title="rspack.config.mjs"
export default {
- cache: {
-   type: 'filesystem',
- },
+ cache: true,
+ experiments: {
+   cache: {
+     type: 'persistent',
+   },
+ },
};
```

2. Migrate `cache.buildDependencies`

```diff title="rspack.config.mjs"
export default {
- cache: {
-   buildDependencies: {
-     config: [__filename, path.join(__dirname, "package.json")],
-     ts: [path.join(__dirname, "tsconfig.json")]
-   }
- },
  experiments: {
    cache: {
      type: "persistent",
+     buildDependencies: [
+       __filename,
+       path.join(__dirname, "package.json"),
+       path.join(__dirname, "tsconfig.json")
+     ]
    },
  },
};
```

3. Migrate `cache.version` and `cache.name`

```diff title="rspack.config.mjs"
export default {
- cache: {
-   name: `${config.name}-${config.mode}-${otherFlags}`,
-   version: appVersion
- },
  experiments: {
    cache: {
      type: "persistent",
+     version: `${config.name}-${config.mode}-${otherFlags}-${appVersion}`
    },
  },
};
```

4. Migrate `snapshot`

```diff title="rspack.config.mjs"
export default {
- snapshot: {
-   immutablePaths: [path.join(__dirname, "constant")],
-   managedPaths: [path.join(__dirname, "node_modules")],
-   unmanagedPaths: []
- },
  experiments: {
    cache: {
      type: "persistent",
+     snapshot: {
+       immutablePaths: [path.join(__dirname, "constant")],
+       managedPaths: [path.join(__dirname, "node_modules")],
+       unmanagedPaths: []
+     }
    },
  },
};
```

5. Migrate `cache.cacheDirectory`

```diff title="rspack.config.mjs"
export default {
- cache: {
-   cacheDirectory: path.join(__dirname, "node_modules/.cache/test")
- },
  experiments: {
    cache: {
      type: "persistent",
+     storage: {
+       type: "filesystem",
+       directory: path.join(__dirname, "node_modules/.cache/test")
+     }
    },
  },
};
```

Sample migration code:

```js
function transform(webpackConfig, rspackConfig) {
  rspackConfig.experiments = rspackConfig.experiments || {};
  if (webpackConfig.cache === undefined) {
    webpackConfig.cache = webpackConfig.mode === 'development';
  }
  // 1. if using disable cache, just set `experiments.cache` = false
  if (!webpackConfig.cache) {
    rspackConfig.experiments.cache = false;
    return;
  }
  // 2. if using memory cache, just set `experiments.cache` = true
  if (webpackConfig.cache === true || webpackConfig.cache.type === 'memory') {
    rspackConfig.experiments.cache = true;
    return;
  }
  // 3. using persistent cache, set `experiments.cache` = { type: "persistent" }
  rspackConfig.experiments.cache = { type: 'persistent' };
  // 4. building `experiments.cache` from webpack config
  rspackConfig.experiments.cache.buildDependencies = Object.values(
    webpackConfig.cache.buildDependencies || {},
  ).flat();
  rspackConfig.experiments.cache.version = [
    webpackConfig.cache.name,
    webpackConfig.cache.version,
  ].join();
  rspackConfig.experiments.cache.snapshot = {
    immutablePaths: webpackConfig.snapshot?.immutablePaths,
    managedPaths: webpackConfig.snapshot?.managedPaths,
    unmanagedPaths: webpackConfig.snapshot?.unmanagedPaths,
  };
  rspackConfig.experiments.cache.storage = {
    type: 'filesystem',
    directory: webpackConfig.cache?.cacheDirectory,
  };
}
```

## experiments.buildHttp

<ApiMeta addedVersion="1.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) 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.useInputFileSystem

<ApiMeta addedVersion="1.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#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/webpack.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';

var virtualModules = new VirtualModulesPlugin({
  'virtual_entry.js': `
    require("./src/another_virtual.js");
    require("./src/disk_file.js")
    `,
  'src/another_virtual.js': 'module.exports = 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.

## experiments.nativeWatcher

<ApiMeta addedVersion="1.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 #233](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.deferImport

<ApiMeta addedVersion="1.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. Currently, only `import defer * as ns from "./module"` is supported, while `import.defer()` will be supported in future versions.

```js title="rspack.config.mjs"
export default {
  experiments: {
    deferImport: true,
  },
};
```



---
url: /config/infrastructure-logging.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/configuration/infrastructureLogging/" />

# 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#statsloggingdebug) option but for infrastructure. Defaults to `false`.

```js title="rspack.config.mjs"
export default {
  //...
  infrastructureLogging: {
    level: 'info',
    debug: ['MyPlugin', /MyPlugin/, (name) => name.contains('MyPlugin')],
  },
};
```

## infrastructureLogging.level

- **Type:** `'none' | 'error' | 'warn' | 'info' | 'log' | 'verbose'`
- **Default:** `'info'`

Enable infrastructure logging output. Similar to [stats.logging](/config/stats#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,
  },
};
```



---
url: /config/other-options.md
---

import WebpackLicense from '@components/WebpackLicense';
import PropertyType from '@components/PropertyType';
import { ApiMeta } from '@components/ApiMeta';

<WebpackLicense from="https://webpack.js.org/configuration/other-options/" />

# Other options

These are the remaining configuration options supported by rspack.

## amd

<ApiMeta addedVersion="1.3.0" />

<PropertyType
  type="false | object"
  defaultValueList={[{ defaultValue: '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

<PropertyType type="boolean" defaultValueList={[{ defaultValue: '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

<PropertyType
  type="string[]"
  defaultValueList={[{ defaultValue: '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

<PropertyType
  type="string"
  defaultValueList={[{ defaultValue: 'undefined' }]}
/>

Name of the configuration. Used when loading multiple configurations.

```js title="rspack.config.mjs"
export default {
  //...
  name: 'admin-app',
};
```

## loader

<PropertyType
  type="Record<string, any>"
  defaultValueList={[{ defaultValue: 'undefined' }]}
/>

Expose custom values into the [loader context](/api/loader-api/context).

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.js
module.exports = function (source) {
  // ...
  console.log(this.answer); // will log `42` here
  return source;
};
```

:::tip
You can override properties in the loader context as webpack copies all properties that are defined in the loader to the loader context.
:::

## profile

<PropertyType
  type="boolean"
  defaultValueList={[{ defaultValue: 'undefined' }]}
/>

Capture a "profile" of the application, including statistics and hints, which can then be dissected using the Analyze tool. It will also log out a summary of module timings.



---
url: /config/deprecated-options.md
---

import { ApiMeta } from '../../../components/ApiMeta';

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

## builtin:swc-loader options

### rspackExperiments.collectTypeScriptInfo

<ApiMeta deprecatedVersion="1.7.0" />

Used to collect information from TypeScript's AST for consumption by subsequent Rspack processes.

:::warning
This configuration has been deprecated. Use top-level [`collectTypeScriptInfo`](/guide/features/builtin-swc-loader#collecttypescriptinfo) instead.

```diff
{
  loader: 'builtin:swc-loader',
  options: {
-   rspackExperiments: {
-     collectTypeScriptInfo: {
-       exportedEnum: true,
-     },
-   },
+   collectTypeScriptInfo: {
+     exportedEnum: true,
+   },
  },
}
```

:::

## experiments.topLevelAwait

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

Enables support for [Top-level await](https://github.com/tc39/proposal-top-level-await). Top-level await can only be used in modules with [ModuleType](/config/module-rules#rulestype) set to `javascript/esm`.

Enabled by default. Can be disabled with this configuration:

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

:::warning
This option has been deprecated and will be removed in Rspack v2.0.

Top-level await will always be enabled in the future. Remove this option from your Rspack configuration.
:::

## experiments.lazyCompilation

<ApiMeta deprecatedVersion="1.5.0" />

Used to enable lazy compilation.

:::warning
This configuration has been deprecated. Use [lazyCompilation](/config/lazy-compilation) instead.
:::

## experiments.layers

<ApiMeta deprecatedVersion="1.6.0" />

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

Controls whether to enable the layer feature. Layers add an identifier prefix to all modules in a subgraph starting from a module in the module graph, to distinguish them from modules in different layers. For example:

The `layer` of the `index.js` module is `null` by default, and its `identifier` is `./index.js`. If we set `layer = 'client'` for it, its `identifier` becomes `(client)/./index.js`. At this point, the `index.js` modules in these two different layers are treated as distinct modules, because their unique `identifier`s differ. The final output includes the artifacts of both modules.

By default, a module's layer is `null`, and it inherits its parent module's layer. You can add a layer to an entry module using `entryOptions.layer`, and add a layer to matched modules using [`module.rule[].layer`](/config/module-rules#ruleslayer). Additionally, you can match based on the parent module's layer using [`module.rule[].issuerLayer`](/config/module-rules#rulesissuerlayer).

```js title="rspack.config.mjs"
export default {
  experiments: {
    layers: true,
  },
};
```

:::warning
This option is deprecated. Layers are now always enabled. Remove this option from your Rspack configuration.
:::

## experiments.parallelCodeSplitting

<ApiMeta deprecatedVersion="1.6.2" />

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

Enabling this configuration will activate a new multi-threaded code splitting algorithm. If your project includes many dynamic imports and doesn't have cyclic chunks, this can greatly reduce the time spent on the code splitting process.

```js title="rspack.config.mjs"
export default {
  experiments: {
    parallelCodeSplitting: true,
  },
  optimization: {
    removeAvailableModules: true,
  },
};
```

:::warning
This option is deprecated, it has a huge performance regression in some edge cases where the chunk graph has lots of cycles. We'll improve the performance of build_chunk_graph in the future instead.
:::

:::warning
When `parallelCodeSplitting` is enabled, ensure that 'optimization.removeAvailableModules' is also enabled (this has been enabled by default since version 1.3.0).

This maintains consistency with the previous code splitting algorithm, which enforced `removeAvailableModules` internally and ignored the `optimization.removeAvailableModules` configuration.
:::

## 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#rulesuse) instead.
:::

## experiments.inlineConst

<ApiMeta deprecatedVersion="1.7.0" />

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

Used to enable the experimental feature for cross-module inline optimization for constant exports.

:::warning
This configuration has been deprecated and is no longer required. The inline exports optimization is now controlled by [`optimization.inlineExports`](/config/optimization#optimizationinlineexports) instead.
:::

## experiments.inlineEnum

<ApiMeta deprecatedVersion="1.7.0" />

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

Used to enable inline optimization for TypeScript enums.

:::warning
This configuration has been deprecated and is no longer required. Inline enum optimization is now controlled by [`optimization.inlineExports`](/config/optimization#optimizationinlineexports) and [`builtin:swc-loader collectTypeScriptInfo.exportedEnum`](/guide/features/builtin-swc-loader#collecttypescriptinfoexportedenum).

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

## experiments.lazyBarrel

<ApiMeta deprecatedVersion="1.7.0" />

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

Used to enable lazy barrel optimization for skipping the building of unused re-export modules in side-effect-free barrel files.

:::warning
This configuration has been deprecated and will be removed in Rspack v2.0. Lazy barrel optimization is already stable and enabled by default. Remove this option from your Rspack configuration.
:::

:::tip
Lazy barrel is now a stable feature that is always enabled. It helps optimize build performance by skipping the building of unused re-export modules in side-effect-free barrel files.

For more details, see the [Lazy barrel guide](/guide/optimization/lazy-barrel).
:::

## experiments.typeReexportsPresence

<ApiMeta deprecatedVersion="1.7.0" />

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

Used to enable error tolerance for type re-exports.

:::warning
This configuration has been deprecated and is no longer required. Type re-exports presence checking is now controlled by [`module.parser.javascript.typeReexportsPresence`](/config/module#moduleparserjavascripttypereexportspresence) and [`builtin:swc-loader collectTypeScriptInfo.typeExports`](/guide/features/builtin-swc-loader#collecttypescriptinfotypeexports).

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

## module.parser.javascript.inlineConst

<ApiMeta deprecatedVersion="1.7.0" />

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

Used to control whether to perform cross-module inline optimization for constant exports in the parser.

:::warning
This configuration has been deprecated. Use [`optimization.inlineExports`](/config/optimization#optimizationinlineexports) instead.
:::



---
url: /plugins/index.md
---

# Rspack plugins

Rspack enhances its compilation capabilities through a rich ecosystem of plugins. These plugins fall into the following categories:

## Built-in plugins

Rspack provides several high-performance built-in plugins. They can serve as drop-in replacements for popular plugins in the webpack ecosystem and deliver more efficient performance.

Including:

- [CircularDependencyRspackPlugin](/plugins/rspack/circular-dependency-rspack-plugin): Flags circular imports
- [CopyRspackPlugin](/plugins/rspack/copy-rspack-plugin): Copies files or directories to the build output
- [CssChunkingPlugin](/plugins/rspack/css-chunking-plugin): Splits CSS while preserving import order to avoid style issues
- [CssExtractRspackPlugin](/plugins/rspack/css-extract-rspack-plugin): Extracts styles into standalone CSS files
- [HtmlRspackPlugin](/plugins/rspack/html-rspack-plugin): Generates HTML and injects assets
- [LightningCssMinimizerRspackPlugin](/plugins/rspack/lightning-css-minimizer-rspack-plugin): Minifies CSS with Lightning CSS
- [SubresourceIntegrityPlugin](/plugins/rspack/subresource-integrity-plugin): Enables subresource integrity (SRI)
- [SwcJsMinimizerRspackPlugin](/plugins/rspack/swc-js-minimizer-rspack-plugin): Minifies JavaScript via SWC
- [VirtualModulesPlugin](/plugins/rspack/virtual-modules-plugin): Creates and modifies virtual modules in memory

## Built-in plugins (webpack-aligned)

To align with webpack's functionality, Rspack has replicated most of webpack's built-in plugins. They maintain the same naming and configuration parameters as closely as possible and provide the same features.

See [Built-in plugins (webpack-aligned) - Overview](/plugins/webpack/index) for more details.

## 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 the [Plugin compatibility list](/guide/compatibility/plugin) 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.



---
url: /plugins/rspack/circular-dependency-rspack-plugin.md
---

import { ApiMeta } from '@components/ApiMeta.tsx';

# CircularDependencyRspackPlugin

<ApiMeta specific={['Rspack']} addedVersion="1.3.0" />

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.

```js
new rspack.CircularDependencyRspackPlugin(options);
```

## 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: /plugins/rspack/copy-rspack-plugin.md
---

import { Table } from '@builtIns';
import WebpackLicense from '@components/WebpackLicense';
import { ApiMeta } from '@components/ApiMeta.tsx';

<WebpackLicense from="https://webpack.js.org/plugins/copy-webpack-plugin/#root" />

# CopyRspackPlugin

<ApiMeta specific={['Rspack']} />

Copies individual files or entire directories, which already exist, to the build directory.

```js
new rspack.CopyRspackPlugin(options);
```

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

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

`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#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 },
        },
      ],
    }),
  ],
};
```



---
url: /plugins/rspack/css-chunking-plugin.md
---

import { Table } from '@builtIns';
import WebpackLicense from '@components/WebpackLicense';
import { ApiMeta } from '@components/ApiMeta.tsx';

# CssChunkingPlugin

<ApiMeta specific={['Rspack']} addedVersion="1.4.0" />

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

```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/rspack/css-extract-rspack-plugin.md
---

import { Table } from '@builtIns';
import { ApiMeta } from '@components/ApiMeta.tsx';

# CssExtractRspackPlugin

<ApiMeta specific={['Rspack']} />

Rspack is currently incompatible with [mini-css-extract-plugin](https://github.com/webpack/mini-css-extract-plugin), but you can use the CssExtractRspackPlugin as a replacement. It can be used with css-loader to extract CSS into separate files.

> If your project does not depend on on css-loader and mini-css-extract-plugin, it is recommended to use Rspack's built-in CSS solution [experiments.css](/config/experiments#experimentscss), which offers better performance.

## Example

When using CssExtractRspackPlugin, you need to register the plugin in the `plugins` section and register `CssExtractRspackPlugin.loader` in [module.rules](/config/module#modulerules).

```ts 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'],
        type: 'javascript/auto',
      },
    ],
  },
};
```

## Plugin options

Options for `CssExtractRspackPlugin`.

- **Types:**

```ts
interface PluginOptions {
  filename?: string | ((pathData: PathData, assetInfo?: AssetInfo) => string);
  chunkFilename?:
    | string
    | ((pathData: PathData, assetInfo?: AssetInfo) => string);
  ignoreOrder?: boolean;
  insert?: string | ((linkTag: HTMLLinkElement) => void);
  attributes?: Record<string, string>;
  linkType?: string | 'text/css' | false;
  runtime?: boolean;
  pathinfo?: boolean;
  enforceRelative?: boolean;
}
```

<Table
  header={[
    {
      name: 'Name',
      key: 'name',
    },
    {
      name: 'Type',
      key: 'type',
    },
    {
      name: 'Default Value',
      key: 'default',
    },
    {
      name: 'Description',
      key: 'description',
    },
  ]}
  body={[
    {
      name: '`filename`',
      type: '`string`',
      default: '"[name].css"',
      description:
        'The name of each CSS output file, please refer to `output.filename`',
    },
    {
      name: '`chunkFilename`',
      type: '`string`',
      default: '"[name].css"',
      description:
        'The name of the asynchronously loaded CSS files. If not set, it will use `filename`; please refer to `output.chunkFilename`',
    },
    {
      name: '`ignoreOrder`',
      type: '`boolean`',
      default: 'false',
      description:
        'Whether to issue a warning if there are conflicts in the order of some CSS in different chunks. For example, entryA introduces a.css and b.css, entryB introduces b.css and a.css, and the order of a.css and b.css cannot be determined',
    },
    {
      name: '`insert`',
      type: '`string | ((linkTag: HTMLLinkElement) => void)`',
      default: 'undefined',
      description:
        'Decide how the link tag is inserted into the page. If passed as a string type, it will be regarded as DOM selector, and the link tag will be inserted after element corresponding to that selector. If passed as function type, the function will be converted into a string at runtime for invocation, with link tag as parameter',
    },
    {
      name: '`attributes`',
      type: '`Record<string, string>`',
      default: 'undefined',
      description:
        'Adds custom attributes to the `link` tag for async CSS chunks',
    },
    {
      name: '`linkType`',
      type: "`string | 'text/css' | false`",
      default: '"text/css"',
      description:
        'Set the `type` attribute value for link tags to load async CSS chunks',
    },
    {
      name: '`runtime`',
      type: '`boolean`',
      default: 'true',
      description: `Whether to inject runtime code for CSS loading. If disabled, CSS will be still extracted and can be used for a custom loading methods`,
    },
    {
      name: '`pathinfo`',
      type: '`boolean`',
      default: 'false',
      description:
        'Whether to include comments in CSS bundles with more detailed path information',
    },
    {
      name: '`enforceRelative`',
      type: '`boolean`',
      default: 'false',
      description:
        'Whether to preserve "\.\/" when generated CSS `url()` is relative',
    },
  ]}
/>

## Loader options

Options for `CssExtractRspackPlugin.loader`.

- **Types:**

```ts
interface LoaderOptions {
  publicPath?: string | ((resourcePath: string, context: string) => string);
  emit?: boolean;
  esModule?: boolean;
}
```

<Table
  header={[
    {
      name: 'Name',
      key: 'name',
    },
    {
      name: 'Type',
      key: 'type',
    },
    {
      name: 'Default Value',
      key: 'default',
    },
    {
      name: 'Description',
      key: 'description',
    },
  ]}
  body={[
    {
      name: '`publicPath`',
      type: '`string | ((resourcePath: string, context: string) => string)`',
      default: 'output.publicPath',
      description:
        'Specifies a custom public path for the external resources like images, files, etc inside CSS',
    },
    {
      name: '`emit`',
      type: '`boolean`',
      default: 'true',
      description:
        'If true, emits CSS files. If false, the plugin will extract the CSS but will not emit files',
    },
    {
      name: '`esModule`',
      type: '`boolean`',
      default: 'true',
      description:
        'whether to use ES modules syntax for CSS Modules class name exports in the generated JavaScript module',
    },
  ]}
/>

## Note

Please note when enabling the built-in CSS support (`experiments.css`), Files ending with `.css` will be automatically treated as `css/auto` modules. If you want to use this plugin, make sure that the rule types with `CssExtractRspackPlugin.loader` set are all overridden by `javascript/auto` instead of the default `css/auto`.

For example:

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

export default {
  plugins: [new rspack.CssExtractRspackPlugin({})],
  module: {
    rules: [
      {
        test: /src\/legacy-project\/.*\.css$/,
        type: 'javascript/auto', // Cover the default CSS module type and treat it as a regular JS file.
        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
      },
      {
        test: /src\/new-project\/.*\.css$/,
        type: 'css/auto', // Handle with built-in CSS
      },
    ],
  },
  experiments: {
    css: true,
  },
};
```



---
url: /plugins/rspack/esm-library-plugin.md
---

import { ApiMeta } from '@components/ApiMeta.tsx';

# EsmLibraryPlugin

<ApiMeta specific={['Rspack']} addedVersion="1.5.6" />

Rspack provides experimental `EsmLibraryPlugin` plugin, provides statically analyzable, cleaner output for ESM library, and also supports code splitting.

:::tip
🚧 This plugin is still work-in-progress, config may change at anytime.
:::

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

export default {
  plugins: [new rspack.experiments.EsmLibraryPlugin()],
  optimization: {
    runtimeChunk: true, // recommended to enable runtime chunk, otherwise consumers need to import runtime code from entry
  },
};
```

## Known limits

- Execution order of modules is not 100% guaranteed, so avoid relying on side effects of execution orders.
- Currently does not support context module and ModuleFederation, but this will be improved in the future.



---
url: /plugins/rspack/html-rspack-plugin.md
---

import { Table } from '@builtIns';
import { ApiMeta } from '@components/ApiMeta.tsx';

# HtmlRspackPlugin

<ApiMeta specific={['Rspack']} />

`rspack.HtmlRspackPlugin` is a high-performance HTML plugin implemented in Rust. You can use it to generate HTML files for Rspack projects.

```js
new rspack.HtmlRspackPlugin(options);
```

## Comparison

Before using `rspack.HtmlRspackPlugin`, please note that there are some differences between `rspack.HtmlRspackPlugin` and the community [`html-webpack-plugin`](https://www.npmjs.com/package/html-webpack-plugin).

### Performance

Because `rspack.HtmlRspackPlugin` is implemented in Rust, its build performance is significantly better than `html-webpack-plugin`, especially in scenarios where many HTML files are being built.

### Features

The features of `rspack.HtmlRspackPlugin` are a subset of `html-webpack-plugin`. To ensure the performance of the plugin, we have not implemented all the features provided by `html-webpack-plugin`.

If its options do not meet your needs, you can also directly use the community [`html-webpack-plugin`](https://www.npmjs.com/package/html-webpack-plugin).

:::warning
`rspack.HtmlRspackPlugin` does not support the full [EJS syntax](https://github.com/mde/ejs/blob/main/docs/syntax.md), it only supports a subset of the EJS syntax. If you need the full EJS syntax support, you can use `html-webpack-plugin` directly.
In order to align with the default template syntax of `html-webpack-plugin`, Rspack changed the default EJS escape and unescape to be the same as `html-webpack-plugin`'s default syntax.
:::

### Supported EJS syntax

Only the following basic interpolation expressions and some control statements are supported. Here, the interpolation expressions only support the most basic string types and do not support arbitrary JavaScript expressions. Other EJS syntaxes are currently not supported.

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

Use the `for in` statement to implement list traversal and the `if` statement to implement conditional judgment:

```txt title="ejs"
<% for tag in htmlRspackPlugin.tags.headTags { %>
  <% if tag.tagName=="script" { %>
    <%= toHtml(tag) %>
  <% } %>
<% } %>
```

## Usage

The plugin will generate an HTML file for you that includes all your JS outputs in the head using `<script>` tags.

Just add the plugin to your Rspack config like this:

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

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

This will generate a file "_dist/index.html_" containing the following:

```html
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>rspack</title>
    <script src="main.js" defer></script>
  </head>
  <body></body>
</html>
```

If you have multiple entry points in your Rspack config, they will all be included with `<script>` tags in the generated HTML.

If you have some CSS assets in the build outputs, they will be included with `<link>` tags in the HTML head.

## Options

You can pass some configuration options to `rspack.HtmlRspackPlugin`. Allowed options are as follows:

- **Type:**

```ts
type HtmlRspackPluginOptions = {
  title?: string;
  filename?: string | ((entry: string) => string);
  template?: string;
  templateContent?:
    | string
    | ((params: Record<string, any>) => string | Promise<string>);
  templateParameters?:
    | Record<string, string>
    | boolean
    | ((
        params: Record<string, any>,
      ) => Record<string, any> | Promise<Record<string, any>>);
  inject?: boolean | 'head' | 'body';
  publicPath?: string;
  base?:
    | string
    | {
        href?: string;
        target?: '_self' | '_blank' | '_parent' | '_top';
      };
  scriptLoading?: 'blocking' | 'defer' | 'module' | 'systemjs-module';
  chunks?: string[];
  excludeChunks?: string[];
  chunksSortMode?: 'auto' | 'manual';
  sri?: 'sha256' | 'sha384' | 'sha512';
  minify?: boolean;
  favicon?: string;
  meta?: Record<string, string | Record<string, string>>;
  hash?: boolean;
};
```

- **Default:** `{}`

<Table
  header={[
    {
      name: 'Name',
      key: 'name',
    },
    {
      name: 'Type',
      key: 'type',
    },
    {
      name: 'Default',
      key: 'default',
    },
    {
      name: 'Description',
      key: 'description',
    },
  ]}
  body={[
    {
      name: '`title`',
      type: '`string | undefined`',
      default: '`undefined`',
      description: 'The title to use for the generated HTML document.',
    },
    {
      name: '`filename`',
      type: '`string | undefined | ((entry: string) => string)`',
      default: '`"index.html"`',
      description:
        'The file to write the HTML to. You can specify a subdirectory here too (e.g.: `"pages/index.html"`).',
    },
    {
      name: '`template`',
      type: '`string | undefined`',
      default: '`undefined`',
      description: 'The template file path.',
    },
    {
      name: '`templateContent`',
      type: '`string | undefined | ((params: Record<string, any>) => string | Promise<string>)`',
      default: '`undefined`',
      description:
        'The template file content, priority is greater than `template` option. When using a function, pass in the template parameters and use the returned string as the template content.',
    },
    {
      name: '`templateParameters`',
      type: '`Record<string, string> | undefined | boolean | ((params: Record<string, any>) => Record<string, any> | Promise<Record<string, any>>)`',
      default: '`undefined`',
      description:
        'Allows to overwrite the parameters used in the template. When using a function, pass in the original template parameters and use the returned object as the final template parameters.',
    },
    {
      name: '`inject`',
      type: '`boolean | undefined | "head" | "body"`',
      default: '`true`',
      description:
        'The script and link tag inject position in template. Use `false` to not inject. If not specified, it will be automatically determined based on `scriptLoading` value.',
    },
    {
      name: '`publicPath`',
      type: '`string | undefined`',
      default: '`undefined`',
      description: 'The public path used for script and link tags.',
    },
    {
      name: '`base`',
      type: '`string | undefined | { href?: string; target?: "_self" | "_blank" | "_parent" | "_top" }`',
      default: '`undefined`',
      description:
        'Inject a [`base`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base) tag.',
    },
    {
      name: '`scriptLoading`',
      type: '`"blocking" | "defer" | "module" | "systemjs-module" | undefined`',
      default: '`"defer"`',
      description:
        'Modern browsers support non-blocking JavaScript loading ([`defer` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer)) to improve the page startup performance. Setting this option to `"module"` adds attribute `type="module"` to the `script`. This also implies `defer` attribute on the `script`, since modules are automatically deferred.',
    },
    {
      name: '`chunks`',
      type: '`string[] | undefined`',
      default: '`undefined`',
      description: 'Allows you to add only some chunks.',
    },
    {
      name: '`excludeChunks`',
      type: '`string[] | undefined`',
      default: '`undefined`',
      description: 'Allows you to skip some chunks.',
    },
    {
      name: '`chunksSortMode`',
      type: '`"auto" | "manual"`',
      default: '`"auto"`',
      description:
        'Allows to control how chunks should be sorted before they are included to the HTML.',
    },
    {
      name: '`sri`',
      type: '`"sha256"" | "sha384"" | "sha512"" | undefined`',
      default: '`undefined`',
      description:
        '<p>**Deprecated**: use [`SubresourceIntegrityPlugin`](./subresource-integrity-plugin) instead.</p><p>Configure the SRI hash algorithm, which is disabled by default.</p>',
    },
    {
      name: '`minify`',
      type: '`boolean`',
      default: '`undefined`',
      description:
        'Controls whether to minify the output, disabled by default.',
    },
    {
      name: '`favicon`',
      type: '`string | undefined`',
      default: '`undefined`',
      description: 'Adds the given favicon path to the output HTML.',
    },
    {
      name: '`meta`',
      type: '`Record<string, string | Record<string, string>>`',
      default: '`{}`',
      description: 'Allows to inject meta-tags.',
    },
    {
      name: '`hash`',
      type: '`boolean`',
      default: '`undefined`',
      description:
        'If `true` then append a unique Rspack compilation hash to all included scripts and CSS files. This is useful for cache busting.',
    },
  ]}
/>

## Example

### Custom HTML template

If the default generated HTML doesn't meet your needs, you can use your own template.

#### Use a template file

The easiest way is to use the template option and pass a custom HTML file. The `rspack.HtmlRspackPlugin` will automatically inject all the necessary JS, CSS and favicon files into the HTML.

Specify the HTML template file through `template`:

```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"
import { rspack } from '@rspack/core';

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

#### Use template string

Specify the HTML template content through `templateContent`:

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

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

Use a function to generate the HTML template content:

- Pass the function in `templateContent`

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

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>
      `,
    }),
  ],
};
```

- Or pass a file path ending with `.js` or `.cjs` 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"
import { rspack } from '@rspack/core';

export default {
  plugins: [
    new rspack.HtmlRspackPlugin({
      title: "My HTML Template"
      template: "template.js",
    }),
  ],
};
```

#### Template parameters

The HTML template rendering parameters can be extended through `templateParameters`. The following variables are available by default:

- `htmlRspackPlugin`: Data of the plugin
  - `htmlRspackPlugin.options`: Configuration object of the plugin
  - `htmlRspackPlugin.tags`: Prepared tag information for injection in the template
    - `htmlRspackPlugin.tags.headTags`: List of `<base>`, `<meta>`, `<link>`, `<script>` tags for injection in `<head>`
    - `htmlRspackPlugin.tags.bodyTags`: List of `<script>` tags for injection in `<body>`
  - `htmlRspackPlugin.files`: Asset files generated in this compilation
    - `htmlRspackPlugin.files.js`: List of paths of JS assets generated in this compilation
    - `htmlRspackPlugin.files.css`: List of paths of CSS assets generated in this compilation
    - `htmlRspackPlugin.files.favicon`: If `favicon` is configured, here is the calculated final favicon asset path
    - `htmlRspackPlugin.files.publicPath`: The `publicPath` of the asset files
- `rspackConfig`: Rspack configuration object used in this compilation
- `compilation`: Compilation object of this compilation

:::warning
If `htmlRspackPlugin.tags` is used to insert tags during template rendering, please configure `inject` as `false`, otherwise the tags will be injected twice.
:::

:::info Differences
There are some differences with HtmlWebpackPlugin:

- Does not support using `!` to add loader to process the template file
- The `rspackConfig` object currently only supports `mode`, `output.publicPath` and `output.crossOriginLoading`
- The `compilation` object is currently only supported when [using the template function](#use-template-function)
- When rendering the tag list (such as `htmlRspackPlugin.tags.headTags`) or a single tag (such as `htmlRspackPlugin.tags.headTags[0]`) in the template, the `toHtml()` function is required to generate the HTML code

:::

### Filter chunks

The chunks that need to be injected can be specified through the following configuration:

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

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

Specific chunks can also be excluded through the following configuration:

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

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

### Meta tags

If `meta` is set, HtmlRspackPlugin will inject `<meta>` tags.

> Please check out this well-maintained list of almost all available [meta tags](https://github.com/joshbuchea/HEAD#meta).

Add key-value pairs through the following configuration to generate `<meta>` tags:

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

export default {
  plugins: [
    new HtmlRspackPlugin({
      meta: {
        // Will generate: <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
        viewport: 'width=device-width, initial-scale=1, shrink-to-fit=no',
        // Will generate: <meta name="theme-color" content="#4285f4">
        'theme-color': '#4285f4',
        // Will generate:  <meta http-equiv="Content-Security-Policy" content="default-src https:">
        'Content-Security-Policy': {
          'http-equiv': 'Content-Security-Policy',
          content: 'default-src https:',
        },
      },
    }),
  ],
};
```

### Base tags

If `base` is set, HtmlRspackPlugin will inject the `<base>` tag.

> For more information about the `<base>` tag, please check the [documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base)

The `<base>` tag can be generated through the following configuration:

```js
new HtmlWebpackPlugin({
  // Will generate: <base href="http://example.com/some/page.html">
  base: 'http://example.com/some/page.html',
});

new HtmlWebpackPlugin({
  // Will generate: <base href="http://example.com/some/page.html" target="_blank">
  base: {
    href: 'http://example.com/some/page.html',
    target: '_blank',
  },
});
```

### Generate multiple HTML files

If you have multiple entry points and want to generate an HTML file for each entry, you can register multiple `rspack.HtmlRspackPlugin`:

- Use `filename` to specify the name for each HTML file.
- Use `chunks` to specify the JS bundles to include in each HTML file.

For example, the following configuration will generate foo.html and bar.html, where foo.html contains only the JS bundles generated by foo.js.

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

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'],
    }),
  ],
};
```

## Hooks

HtmlRspackPlugin provides some hooks that allow you to modify tags or generated HTML code. The hooks object can be obtained through `rspack.HtmlRspackPlugin.getCompilationHooks`:

```js title="rspack.config.mjs"
const HtmlModifyPlugin = {
  apply(compiler) {
    compiler.hooks.compilation.tap('HtmlModifyPlugin', (compilation) => {
      const hooks = 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 HtmlRspackPlugin(), HtmlModifyPlugin],
};
```

### beforeAssetTagGeneration

This hook will be called after collecting the assets from the compilation and generating the loading path, but before generating the tags.

The `assets` can be modified here to add custom JS and CSS asset files.

- **Type**: `AsyncSeriesWaterfallHook<[BeforeAssetTagGenerationData]>`
- **Parameters**:
  ```ts
  type BeforeAssetTagGenerationData = {
    assets: {
      publicPath: string;
      js: Array<string>;
      css: Array<string>;
      favicon?: string;
    };
    outputName: string;
    plugin: {
      options: HtmlRspackPluginOptions;
    };
  };
  ```

:::warning
Only `assets.js`, `assets.css`, and `assets.favicon` can be modified. Modifications to other items will not take effect.
:::

The following code adds an additional `extra-script.js` and generates a `<script defer src="extra-script.js"></script>` tag in the final html content.

```js title="rspack.config.mjs"
const AddScriptPlugin = {
  apply(compiler) {
    compiler.hooks.compilation.tap('AddScriptPlugin', (compilation) => {
      const hooks = HtmlRspackPlugin.getCompilationHooks(compilation);
      hooks.beforeAssetTagGeneration.tapPromise(
        'AddScriptPlugin',
        async (data) => {
          data.assets.js.push('extra-script.js');
        },
      );
    });
  },
};

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

### alterAssetTags

This hook will be called after generating the asset tags based on the asset files, but before determining the insertion position of the tags.

The tags can be adjusted here.

- **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>;
    };
    outputName: string;
    plugin: {
      options: HtmlRspackPluginOptions;
    };
  };
  ```

:::warning
Only `assetTags` can be modified. Modifications to other items will not take effect.
:::

- When set the attribute value to `true`, a valueless attribute will be added, and `<script defer specialattribute src="main.js"></script>` will be generated.
- When set the attribute value to a `string`, a valued attribute will be added, and `<script defer specialattribute="some value" src="main.js"></script>` will be generated.
- When set the attribute value to `false`, the attribute will be removed.

The following code adds the `specialAttribute` property to all `script` type tags:

```js title="rspack.config.mjs"
const AddAttributePlugin = {
  apply(compiler) {
    compiler.hooks.compilation.tap('AddAttributePlugin', (compilation) => {
      const hooks = 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 HtmlRspackPlugin(), AddAttributePlugin],
};
```

### alterAssetTagGroups

This hook will be called after generating the tag groups of `head` and `body`, but before the template is rendered by function or template engine.

The insertion position of the tags can be adjusted here.

- **Type**: `AsyncSeriesWaterfallHook<[AlterAssetTagGroupsData]>`
- **Parameters**:
  ```ts
  type AlterAssetTagGroupsData = {
    headTags: Array<HtmlTag>;
    bodyTags: Array<HtmlTag>;
    outputName: string;
    plugin: {
      options: HtmlRspackPluginOptions;
    };
  };
  ```

:::warning Warning
Only `headTags` and `bodyTags` can be modified. Modifications to other items will not take effect.
:::

The following code moves the `async` `script` tags from `body` to `head`:

```js title="rspack.config.mjs"
const MoveTagsPlugin = {
  apply(compiler) {
    compiler.hooks.compilation.tap('MoveTagsPlugin', (compilation) => {
      const hooks = HtmlRspackPlugin.getCompilationHooks(compilation);
      hooks.alterAssetTagGroups.tapPromise('MoveTagsPlugin', async (data) => {
        data.headTags.push(data.headTags.bodyTags.filter((i) => i.async));
        data.bodyTags = data.bodyTags.filter((i) => !i.async);
      });
    });
  },
};

export default {
  //...
  plugins: [
    new HtmlRspackPlugin({
      inject: 'body',
    }),
    AllHeadTagsPlugin,
  ],
};
```

### afterTemplateExecution

This hook will be called after the template rendering is completed, but before the tags are injected.

The HTML content and the tags to be injected can be modified here.

- When using the function `templateContent` or the `template` ending with `.js/.cjs`, and using this function to render the template, here `html` is the result returned by the function.
- In other scenarios, the HTML template will be compiled through a template engine inside, and here `html` is the compiled result.

- **Type**: `AsyncSeriesWaterfallHook<[AfterTemplateExecutionData]>`
- **Parameters**:
  ```ts
  type AfterTemplateExecutionData = {
    html: string;
    headTags: Array<HtmlTag>;
    bodyTags: Array<HtmlTag>;
    outputName: string;
    plugin: {
      options: HtmlRspackPluginOptions;
    };
  };
  ```
  :::warning Warning
  Only `html`, `headTags`, and `bodyTags` can be modified. Modifications to other items will not take effect.
  :::

The following code adds `Injected by plugin` at the end of the body. Then the tags will be injected after this text. Therefore, it will be `<Injected by plugin<script defer src="main.js"></script></body>` in the final HTML content:

```js title="rspack.config.mjs"
const InjectContentPlugin = {
  apply(compiler) {
    compiler.hooks.compilation.tap('InjectContentPlugin', (compilation) => {
      const hooks = HtmlRspackPlugin.getCompilationHooks(compilation);
      hooks.afterTemplateExecution.tapPromise(
        'InjectContentPlugin',
        async (data) => {
          data.html = data.html.replace('</body>', 'Injected by plugin</body>');
        },
      );
    });
  },
};

export default {
  //...
  plugins: [
    new HtmlRspackPlugin({
      inject: 'body',
    }),
    InjectContentPlugin,
  ],
};
```

### beforeEmit

This hook will be called before generating the HTML asset file, and it is the final chance to modify the HTML content.

- **Type**: `SyncHook<[BeforeEmitData]>`
- **Parameters**:
  ```ts
  type BeforeEmitData = {
    html: string;
    outputName: string;
    plugin: {
      options: HtmlRspackPluginOptions;
    };
  };
  ```

:::warning Warning
Only `html` can be modified. Modifications to other items will not take effect.
:::

The following code adds `Injected by plugin` at the end of the body. It will be `<script defer src="main.js"></script>Injected by plugin</body>` in the final HTML content:

```js title="rspack.config.mjs"
const InjectContentPlugin = {
  apply(compiler) {
    compiler.hooks.compilation.tap('InjectContentPlugin', (compilation) => {
      const hooks = HtmlRspackPlugin.getCompilationHooks(compilation);
      hooks.beforeEmit.tapPromise('InjectContentPlugin', async (data) => {
        data.html = data.html.replace('</body>', 'Injected by plugin</body>');
      });
    });
  },
};

export default {
  //...
  plugins: [
    new HtmlRspackPlugin({
      inject: 'body',
    }),
    InjectContentPlugin,
  ],
};
```

### afterEmit

This hook will be called after generating the HTML asset file and is only used for notification.

- **Type**: `SyncHook<[AfterEmitData]>`
- **Parameters**:
  ```ts
  type AfterEmitData = {
    outputName: string;
    plugin: {
      options: HtmlRspackPluginOptions;
    };
  };
  ```



---
url: /plugins/rspack/lightning-css-minimizer-rspack-plugin.md
---

import { ApiMeta } from '@components/ApiMeta.tsx';

# LightningCssMinimizerRspackPlugin

<ApiMeta specific={['Rspack']} />

This plugin uses [lightningcss](https://lightningcss.dev/) to minify CSS assets. See [optimization.minimizer](/config/optimization#optimizationminimizer).

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

export default {
  optimization: {
    minimizer: [new rspack.LightningCssMinimizerRspackPlugin(options)],
  },
};
```

## 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:

{/* prettier-ignore */}
```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 default `targets` is set to `"fully supports es6"` to ensure 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) 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 LightningCssMinimizerOptions = {
  errorRecovery?: boolean;
  targets?: string[] | string;
  include?: LightningcssFeatureOptions;
  exclude?: LightningcssFeatureOptions;
  /**
   * @deprecated Use `drafts` instead.
   * This will be removed in the next major version.
   */
  draft?: Drafts;
  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/rspack/subresource-integrity-plugin.md
---

import { ApiMeta } from '@components/ApiMeta.tsx';

# SubresourceIntegrityPlugin

<ApiMeta specific={['Rspack']} addedVersion="1.7.0" />

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/rspack/html-rspack-plugin) 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.

## Usage

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#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/rspack/html-rspack-plugin.mdx) 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/rspack/html-rspack-plugin.mdx) 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/rspack/html-rspack-plugin.mdx), the grammar of the template is a bit different with `.ejs`(see [here](/plugins/rspack/html-rspack-plugin#supported-ejs-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.plugin('done', (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) 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/rspack/swc-js-minimizer-rspack-plugin.md
---

import { ApiMeta } from '@components/ApiMeta.tsx';

# SwcJsMinimizerRspackPlugin

<ApiMeta specific={['Rspack']} />

This plugin is used to minify JavaScript files using [SWC](https://swc.rs/).

## Example

Use this plugin via [optimization.minimizer](/config/optimization#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/rspack/lightning-css-minimizer-rspack-plugin) 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

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,
});
```

#### RegExp

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

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 `/*! For license information please see {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,
  compress: {
    passes: 2,
  }
  format: {
    comments: false,
  },
};
```

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/rspack/virtual-modules-plugin.md
---

import { ApiMeta } from '@components/ApiMeta.tsx';

# VirtualModulesPlugin

<ApiMeta specific={['Rspack']} addedVersion="1.5.0" />

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

## Usage

### 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
});
```

- **Parameters:**
  - `modules` (optional): An object where keys are file paths and values are file contents.

```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#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);
        });
      },
    },
  ],
};
```



---
url: /plugins/webpack/index.md
---

import { Table } from '@builtIns';
import { PluginSupportStatusTable } from '@components/PluginSupportStatusTable';

# Overview

The table below shows the support status of Rspack for the built-in plugins in webpack. If you are interested in participating in the development of plugins or features that have not yet been implemented, we would be very happy to have you join us.

<PluginSupportStatusTable />



---
url: /plugins/webpack/banner-plugin.md
---

import { Table } from '@builtIns';

# BannerPlugin

```js
new rspack.BannerPlugin(options);
```

Adds a banner to the top or bottom of each generated chunk.

## Options

- **Type:**

```ts
type BannerFunction = (args: {
  hash: string;
  chunk: Chunk;
  filename: string;
}) => string;
type BannerContent = string | BannerFunction;
type BannerPluginOptions = {
  banner: BannerContent;
  entryOnly?: boolean;
  footer?: boolean;
  raw?: boolean;
  stage?: number;
  test?: BannerRules;
  include?: BannerRules;
  exclude?: BannerRules;
};
type BannerPluginArgument = BannerContent | BannerPluginOptions;
```

- **Default:** `undefined`

<Table
  header={[
    {
      name: 'Name',
      key: 'name',
    },
    {
      name: 'Type',
      key: 'type',
    },
    {
      name: 'Default',
      key: 'default',
    },
    {
      name: 'Description',
      key: 'description',
    },
  ]}
  body={[
    {
      name: '`banner`',
      type: '`BannerFunction|string`',
      default: 'undefined',
      description: 'Specifies the banner, it will be wrapped in a comment.',
    },
    {
      name: '`entryOnly`',
      type: '`boolean|undefined`',
      default: 'undefined',
      description:
        'If true, the banner will only be added to the entry chunks.',
    },
    {
      name: '`footer`',
      type: '`boolean|undefined`',
      default: 'undefined',
      description: 'If true, banner will be placed at the end of the output.',
    },
    {
      name: '`raw`',
      type: '`boolean|undefined`',
      default: 'undefined',
      description: 'If true, banner will not be wrapped in a comment.',
    },
    {
      name: '`stage`',
      type: '`number|undefined`',
      default: '`PROCESS_ASSETS_STAGE_ADDITIONS`(-100)',
      description:
        'The stage of the compilation in which the banner should be injected.',
    },
    {
      name: '`test`',
      type: '`BannerRules|undefined`',
      default: 'undefined',
      description: 'Include all modules that pass test assertion.',
    },
    {
      name: '`include`',
      type: '`BannerRules|undefined`',
      default: 'undefined',
      description: 'Include all modules matching any of these conditions.',
    },
    {
      name: '`exclude`',
      type: '`BannerRules|undefined`',
      default: 'undefined',
      description: 'Exclude all modules matching any of these conditions.',
    },
  ]}
/>

## Examples

Add a banner to the bottom of each chunk file.

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

export default {
  plugins: [
    new rspack.BannerPlugin({
      banner: 'hello world',
      footer: true,
    }),
  ],
};
```



---
url: /plugins/webpack/context-replacement-plugin.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/plugins/context-replacement-plugin/" />

# ContextReplacementPlugin

`Context` refers to a `require` or dynamic `import()` with an expression such as `require('./locale/' + name + '.json')`.
When encountering such an expression, Rspack infers the directory (`'./locale/'`) and a regular expression (`/^.*\.json$/`).
Since the name is not known at compile time, Rspack includes every file as module in the bundle.

The `ContextReplacementPlugin` allows you to override the inferred information. There are various ways to configure the plugin:

## Options

- **Type:**

```ts
new rspack.ContextReplacementPlugin(
  resourceRegExp: RegExp,
  newContentResource?: string,
  newContentRecursive?: boolean,
  newContentRegExp?: RegExp
)
```

If the resource (directory) matches `resourceRegExp`, the plugin replaces the default resource, recursive flag or generated regular expression with `newContentResource`, `newContentRecursive` or `newContextRegExp` respectively.
If `newContentResource` is relative, it is resolved relative to the previous resource.

## Examples

### Basic use case

```js
new rspack.ContextReplacementPlugin(/moment[/\\]locale$/, /de|fr|hu/);
```

The `moment/locale` context is restricted to files matching `/de|fr|hu/`. Thus only those locales are included (see [this issue](https://github.com/moment/moment/issues/2373) for more information).

### Other options

The `newContentResource` and `newContentCreateContextMap` parameters are also available:

```ts
new rspack.ContextReplacementPlugin(
  resourceRegExp: RegExp,
  newContentResource: string,
  newContentCreateContextMap: object // mapping runtime-request (userRequest) to compile-time-request (request)
);
```

These two parameters can be used together to redirect requests in a more targeted way. The `newContentCreateContextMap` allows you to map runtime requests to compile requests in the form of an object:

```js
new rspack.ContextReplacementPlugin(/selector/, './folder', {
  './request': './request',
  './other-request': './new-request',
});
```



---
url: /plugins/webpack/define-plugin.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/plugins/define-plugin/" />

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

```js
new rspack.DefinePlugin({
  // Definitions...
});
```

## 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>;
```

## 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'),
});
```



---
url: /plugins/webpack/dll-plugin.md
---

import { Table } from '@builtIns';
import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/plugins/dll-plugin/" />

# DllPlugin

The `DllPlugin` is used in a separate rspack configuration exclusively to create a dll-only-bundle.

## Options

- **Type:**

```ts
type DllPluginOptions = {
  context?: string;
  entryOnly?: boolean;
  format?: boolean;
  name?: string;
  path: string;
  type?: string;
};
```

<Table
  header={[
    {
      name: 'Name',
      key: 'name',
    },
    {
      name: 'Type',
      key: 'type',
    },
    {
      name: 'Default',
      key: 'default',
    },
    {
      name: 'Description',
      key: 'description',
    },
  ]}
  body={[
    {
      name: '`context`',
      type: '`string`',
      default: `The rspack compiler context`,
      description: 'context of requests in the manifest file',
    },
    {
      name: '`path`',
      type: '`string`',
      default: `undefined`,
      description: 'absolute path to the manifest json file ',
    },
    {
      name: '`entryOnly`',
      type: '`boolean`',
      default: '`true`',
      description: 'if `true`, only entry points will be exposed',
    },
    {
      name: '`format`',
      type: '`boolean`',
      default: 'undefined',
      description: 'Whether or not format manifest json',
    },
    {
      name: '`name`',
      type: '`string`',
      default: 'undefined',
      description: 'The expose dll function name',
    },
    {
      name: '`type`',
      type: '`string`',
      default: 'undefined',
      description: 'type of the dll 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/webpack/dll-reference-plugin)

Combine this plugin with `output.library` options to expose the dll function.



---
url: /plugins/webpack/dll-reference-plugin.md
---

import { Table } from '@builtIns';
import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/plugins/dll-plugin/#dllreferenceplugin" />

# DllReferencePlugin

The `DllReferencePlugin` is used be reference the dll-only-bundle to require pre-built dependencies.

## 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;
  };
};

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';
    };
```

This plugin references a dll manifest file to map dependency names to module ids, then require them as needed.

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



---
url: /plugins/webpack/electron-target-plugin.md
---

# ElectronTargetPlugin

This plugin is used to external the Electron built-in modules during bundling, and is used by [`externalsPresets.electron`](/config/externals#electron), [`externalsPresets.electronMain`](/config/externals#electronmain), [`externalsPresets.electronRenderer`](/config/externals#electronrenderer), and [`externalsPresets.electronPreload`](/config/externals#electronpreload) under the hood.

```js
new rspack.electron.ElectronTargetPlugin();
```



---
url: /plugins/webpack/enable-chunk-loading-plugin.md
---

# EnableChunkLoadingPlugin

Enable runtime module bundling for this chunkLoadingType, and is used by [output.enabledChunkLoadingTypes](/config/output#outputenabledchunkloadingtypes) under the hood.

## Examples

### Use built-in chunk loading

Available values: `"jsonp" | "import-scripts" | "require" | "async-node" | "import"`

```js
new rspack.javascript.EnableChunkLoadingPlugin('import');
```

See [output.chunkLoading](/config/output#outputchunkloading) for details.

### Use custom chunk loading

Implement a custom chunk loading plugin using `EnableChunkLoadingPlugin.setEnabled`:

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

export class CustomChunkLoadingPlugin {
  apply(compiler) {
    rspack.javascript.EnableChunkLoadingPlugin.setEnabled(
      compiler,
      'custom-chunk-loading',
    );
  }
}
```

Then use `output.chunkLoading: 'custom-chunk-loading'` in Rspack config:

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

export default {
  output: {
    chunkLoading: 'custom-chunk-loading',
  },
  plugins: [new CustomChunkLoadingPlugin()],
};
```



---
url: /plugins/webpack/enable-library-plugin.md
---

# EnableLibraryPlugin

Enable library format bundling for this libraryType, and is used by [output.enabledLibraryTypes](/config/output#outputenabledlibrarytypes) under the hood.

```js
new rspack.library.EnableLibraryPlugin('var');
```



---
url: /plugins/webpack/enable-wasm-loading-plugin.md
---

# EnableWasmLoadingPlugin

Enable runtime module bundling for this wasmLoadingType, and is used by [output.enabledWasmLoadingTypes](/config/output#outputenabledwasmloadingtypes) under the hood.

```js
new rspack.library.EnableWasmLoadingPlugin('fetch');
```



---
url: /plugins/webpack/entry-plugin.md
---

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

```js
new rspack.EntryPlugin(context, entry, options);
```

## 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#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/webpack/environment-plugin.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/plugins/environment-plugin/" />

# EnvironmentPlugin

The `EnvironmentPlugin` is shorthand for using the [`DefinePlugin`](/plugins/webpack/define-plugin) on [`process.env`](https://nodejs.org/api/process.html#process_process_env) keys.

## Options

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

## Examples

### Basic use case

The `EnvironmentPlugin` accepts either an array of keys or an object mapping its keys to their default values.

```js
new rspack.EnvironmentPlugin(['NODE_ENV', 'DEBUG']);
```

This is equivalent to the following `DefinePlugin` application:

```js
new rspack.DefinePlugin({
  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
  'process.env.DEBUG': JSON.stringify(process.env.DEBUG),
});
```

:::tip
Not specifying the environment variable raises an "`EnvironmentPlugin` - `${key}` environment variable is undefined" error.
:::

### Usage with default values

Alternatively, the `EnvironmentPlugin` supports an object, which maps keys to their default values. The default value for a key is taken if the key is undefined in `process.env`.

```js
new rspack.EnvironmentPlugin({
  NODE_ENV: 'development', // use 'development' unless process.env.NODE_ENV is defined
  DEBUG: false,
});
```

:::warning
Variables coming from `process.env` are always strings.
:::

:::tip
Unlike [`DefinePlugin`](/plugins/webpack/define-plugin), default values are applied to `JSON.stringify` by the `EnvironmentPlugin`.
:::

:::tip
Default values of `null` and `undefined` behave differently. Use `undefined` for variables that must be provided during bundling, or `null` if they are optional.
:::

:::warning
If an environment variable is not found during bundling and no default value was provided, Rspack will throw an error instead of a warning.
:::

Let's investigate the result when running the previous `EnvironmentPlugin` configuration on a test file `entry.js`:

```js
if (process.env.NODE_ENV === 'production') {
  console.log('Welcome to production');
}
if (process.env.DEBUG) {
  console.log('Debugging output');
}
```

When executing `NODE_ENV=production` Rspack in the terminal to build, `entry.js` becomes this:

```js
if ('production' === 'production') {
  // <-- 'production' from NODE_ENV is taken
  console.log('Welcome to production');
}
if (false) {
  // <-- default value is taken
  console.log('Debugging output');
}
```

Running `DEBUG=false` Rspack yields:

```js
if ('development' === 'production') {
  // <-- default value is taken
  console.log('Welcome to production');
}
if ('false') {
  // <-- 'false' from DEBUG is taken
  console.log('Debugging output');
}
```

### Git version

The following `EnvironmentPlugin` configuration provides `process.env.GIT_VERSION` (such as "v5.4.0-2-g25139f57f") and `process.env.GIT_AUTHOR_DATE` (such as "2020-11-04T12:25:16+01:00") corresponding to the last Git commit of the repository:

```js
const child_process = require('child_process');
function git(command) {
  return child_process.execSync(`git ${command}`, { encoding: 'utf8' }).trim();
}

new rspack.EnvironmentPlugin({
  GIT_VERSION: git('describe --always'),
  GIT_AUTHOR_DATE: git('log -1 --format=%aI'),
});
```

### DotenvPlugin

The third-party [`DotenvPlugin`](https://github.com/mrsteele/dotenv-webpack) (`dotenv-webpack`) allows you to expose (a subset of) [dotenv variables](https://www.npmjs.com/package/dotenv):

```js
// .env
DB_HOST=127.0.0.1
DB_PASS=foobar
S3_API=mysecretkey
```

```js
new Dotenv({
  path: './.env', // Path to .env file (this is the default)
  safe: true, // load .env.example (defaults to "false" which does not use dotenv-safe)
});
```



---
url: /plugins/webpack/eval-source-map-dev-tool-plugin.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/plugins/eval-source-map-dev-tool-plugin/" />

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

```js
new webpack.EvalSourceMapDevToolPlugin(options);
```

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

## 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'],
});
```



---
url: /plugins/webpack/externals-plugin.md
---

# 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#externalstype) and [`externals`](/config/externals#externals-1) configurations leverage the plugin internally. Therefore, you can utilize the respective functionality directly through these configuration options without needing to use the plugin separately.

```js
new rspack.ExternalsPlugin(type, externals);
```

## 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'
  | 'script'
  | 'node-commonjs';
```

Specifies the default type for the `externals`.

For more details, refer to [externalsType](/config/externals#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#externals-1).



---
url: /plugins/webpack/hot-module-replacement-plugin.md
---

# HotModuleReplacementPlugin

Enables hot module replacement (HMR).

```js
new rspack.HotModuleReplacementPlugin();
```

## Example

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) 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/tech/react#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/tech/preact#preact-refresh) for more details.



---
url: /plugins/webpack/ignore-plugin.md
---

# IgnorePlugin

This plugin will prevent the generation of modules for `import` or `require` calls matching the regular expressions.

```js
new rspack.IgnorePlugin(options);
```

## Options

- **Type:**

```ts
| {
    /** A RegExp to test the resource against. */
    resourceRegExp: RegExp;
    /** A RegExp to test the context (directory) against. */
    contextRegExp?: RegExp;
  }
| {
    /** A Filter function that receives `resource` and `context` as arguments, must return boolean. */
    checkResource: (resource: string, context: string) => boolean;
  }
```

- **Default:** `undefined`

## Example

When using the following configuration:

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

export default {
  plugins: [
    new rspack.IgnorePlugin({
      resourceRegExp: /^\.\/locale$/,
      contextRegExp: /moment$/,
    });
  ],
};
```

which means any require statement matching './locale' from any directories ending with 'moment' will be ignored.



---
url: /plugins/webpack/javascript-modules-plugin.md
---

import { ApiMeta } from '@components/ApiMeta.tsx';

# JavascriptModulesPlugin

<ApiMeta addedVersion={'1.0.0-alpha.0'} />

Handles the bundling of JavaScript, usually used to access the [hooks of the JavascriptModulesPlugin](/api/plugin-api/javascript-modules-plugin-hooks):

```js
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);
        },
      );
    });
  }
}
```



---
url: /plugins/webpack/limit-chunk-count-plugin.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/plugins/limit-chunk-count-plugin/" />

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

```js
new rspack.optimize.LimitChunkCountPlugin({
  // Options...
});
```

## 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,
});
```



---
url: /plugins/webpack/module-federation-plugin.md
---

import { Stability, ApiMeta } from '@components/ApiMeta';

# ModuleFederationPlugin

This plugin implements [Module Federation 1.5](https://github.com/module-federation/universe/tree/main/packages/enhanced).

## Example

```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
    }),
  ],
};
```

## 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: `string[]`

Provide the plugin required to run Module Federation 1.5, which can extend the behavior and capabilities of Module Federation.

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

Define the output format of remote container entry. The default libraryType is "var".

### shareScope

- Type: `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#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[];
  interface RemotesObject {
    [k: string]: RemotesConfig | RemotesItem | RemotesItems;
  }
  interface RemotesConfig {
    external: RemotesItem | RemotesItems;
    shareScope?: string;
  }
  ```

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;
  interface SharedObject {
    [k: string]: SharedConfig | SharedItem;
  }
  interface SharedConfig {
    import?: false | SharedItem;
    eager?: boolean;
    packageName?: string;
    requiredVersion?: false | string;
    shareKey?: string;
    shareScope?: string;
    singleton?: boolean;
    strictVersion?: boolean;
    version?: false | string;
  }
  ```

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.

### manifest

<ApiMeta addedVersion="1.6.0-beta.0" />

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

## 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) 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/webpack/module-federation-plugin-v1.md
---

import { Stability } from '@components/ApiMeta';

# ModuleFederationPluginV1

This plugin corresponds to Module Federation v1.0, which is the [ModuleFederationPlugin in webpack](https://webpack.js.org/plugins/module-federation-plugin/).

The configuration is consistent with the ModuleFederationPlugin above, except for the three fields `implementation`, `runtimePlugins` and `shareStrategy`.

```js
new rspack.container.ModuleFederationPluginV1();
```

:::tip
Module Federation v1.0 is no longer being iterated. We recommend using Module Federation v1.5 or v2.0. See [Module Federation](/guide/features/module-federation).
:::

## Example

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

export default {
  plugins: [
    new rspack.container.ModuleFederationPluginV1({
      // options
    }),
  ],
};
```



---
url: /plugins/webpack/no-emit-on-errors-plugin.md
---

import { ApiMeta } from '@components/ApiMeta.tsx';

# NoEmitOnErrorsPlugin

<ApiMeta addedVersion={'1.0.0'} />

This plugin is used to prevent the assets emitting when there are compilation errors. [`optimization.emitOnErrors`](/config/optimization#optimizationemitonerrors) uses this plugin.

```js
new rspack.NoEmitOnErrorsPlugin();
```



---
url: /plugins/webpack/node-target-plugin.md
---

# NodeTargetPlugin

This plugin is used to external the Node.js built-in modules during bundling, and is used by [`externalsPresets.node`](/config/externals#node) under the hood.

```js
new rspack.node.NodeTargetPlugin();
```



---
url: /plugins/webpack/node-template-plugin.md
---

# NodeTemplatePlugin

This plugin is used to bundle out Node.js assets, often used with childCompiler.

```js
new rspack.node.NodeTemplatePlugin();
```



---
url: /plugins/webpack/normal-module-replacement-plugin.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/plugins/normal-module-replacement-plugin/" />

# NormalModuleReplacementPlugin

The `NormalModuleReplacementPlugin` allows you to replace resources that match `resourceRegExp` with `newResource`.

```js
new rspack.NormalModuleReplacementPlugin(resourceRegExp, 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.
:::

## 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
module.exports = 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'
```



---
url: /plugins/webpack/progress-plugin.md
---

import { Table } from '@builtIns';

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

```js
new rspack.ProgressPlugin(options);
```

## Options

### Function

Provide a handler function which will be called when hooks report progress. `handler` function arguments:

- `percentage`: a number between 0 and 1 indicating the completion percentage of the compilation
- `message`: a short description of the currently-executing hook
- `...args`: zero or more additional strings describing the current progress

```js
const handler = (percentage, message, ...args) => {
  // e.g. Output each progress message directly to the console:
  console.info(percentage, message, ...args);
};

new rspack.ProgressPlugin(handler);
```

### Object

#### prefix

- **Type:** `string`
- **Default:** `'Rspack'`

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/webpack/provide-plugin.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/plugins/provide-plugin/" />

# ProvidePlugin

Automatically load modules instead of having to `import` or `require` them everywhere.

```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
const path = require('node:path');

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.

## Options

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

## Examples

### Using process in the browser

Enable `process` object support within a browser context.

```js
new rspack.ProvidePlugin({
  process: [require.resolve('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'],
});
```



---
url: /plugins/webpack/runtime-chunk-plugin.md
---

# RuntimeChunkPlugin

Used to control how the runtime chunk is generated, it is used by [`optimization.runtimeChunk`](/config/optimization#optimizationruntimechunk) under the hood.

## 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/webpack/source-map-dev-tool-plugin.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/plugins/source-map-dev-tool-plugin/" />

# 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.html) configuration option.

```js
new rspack.SourceMapDevToolPlugin(options);
```

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

### fallbackModuleFilenameTemplate

- **Type:** `string`

See link above.

### namespace

- **Type:** `string`

See [`output.devtoolNamespace`](/config/output#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#development), make sure to disable the default one. I.e. set `devtool: false`.
:::

## 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
```



---
url: /plugins/webpack/split-chunks-plugin.md
---

import WebpackLicense from '@components/WebpackLicense';
import { ApiMeta } from '../../../../components/ApiMeta';

<WebpackLicense from="https://webpack.js.org/configuration/optimization/" />

# SplitChunksPlugin

SplitChunksPlugin is a built-in plugin that splits code into multiple [chunks](/misc/glossary#chunk) to optimize application loading performance and achieve better caching strategies and parallel loading.

SplitChunksPlugin can be configured through the [optimization.splitChunks](/config/optimization#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 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.

## 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#initial-chunk) and [async chunks](/misc/glossary#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.

```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/features/module-federation) 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.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/webpack/split-chunks-plugin#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.

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

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.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:** `string | function`
- **Default:** `false`

> where the version of the function type is `>=0.4.1`.

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.

If the `splitChunks.name` matches an [entry point](/config/entry) 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

<ApiMeta addedVersion="1.0.0" />

- **Type:** `boolean`
- **Default:** Value of [optimization.usedExports](/config/optimization#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/webpack/split-chunks-plugin#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)
```

### splitChunks.defaultSizeTypes

- **Type:** `string[]`
- **Default:** `["javascript", "unknown"]`, and if `experiments.css` is enabled, it will also include `"css"`

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`

> where the version of the function type is `>=0.4.1`.

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.



---
url: /plugins/webpack/case-sensitive-plugin.md
---

import { ApiMeta } from '@components/ApiMeta.tsx';

# CaseSensitivePlugin

<ApiMeta addedVersion={'1.2.0'} />

:::tip
This plugin was renamed to `CaseSensitivePlugin` in v1.7.0. `WarnCaseSensitiveModulesPlugin` is deprecated and will be removed in a future release.
:::

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.

```js
new rspack.CaseSensitivePlugin();
```

## Register

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

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

## Example

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/webpack/internal-plugins.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/plugins/internal-plugins/" />

# Internal plugins

This is a list of plugins used internally by Rspack, aligned with the plugins used internally by webpack.

:::warning
You should only concern yourself with these plugins if you are building your own compiler based on Rspack, or for internal inspection.
:::

Categories of internal plugins:

- [environment](#environment)
- [compiler](#compiler)
- [entry](#entry)
- [output](#output)
- [source](#source)
- [optimize](#optimize)
- [loader](#loader)
- [module federation](#module-federation)

## environment

Plugins affecting the environment of the compiler.

### ElectronTargetPlugin

`electron.ElectronTargetPlugin(context)`

Customizes the handling of external dependencies for different contexts (such as main process, preload scripts, and renderer process) in Electron applications.

[`externalsPresets.electron`](/config/externals#electron), [`externalsPresets.electronMain`](/config/externals#electronmain), [`externalsPresets.electronRenderer`](/config/externals#electronrenderer), and [`externalsPresets.electronPreload`](/config/externals#electronpreload) all rely on this plugin.

### NodeEnvironmentPlugin

`node.NodeEnvironmentPlugin()`

Applies Node.js style filesystem to the compiler.

## compiler

Plugins affecting the compiler.

### ProgressPlugin

`ProgressPlugin(handler)`

Hook into the compiler to extract progress information. The `handler` must have the signature `function(percentage, message)`. Percentage is called with a value between 0 and 1, where 0 indicates the start and 1 the end.

## entry

Plugins, which add entry chunks to the compilation.

### DynamicEntryPlugin

`DynamicEntryPlugin(context, entry)`

Similar to `EntryPlugin` but accepts a function as the `entry` argument. This function is called during each `make` event in the build process to support dynamically determining the entry points.

### EntryOptionPlugin

`EntryOptionPlugin()`

## output

### EvalDevToolModulePlugin

`EvalDevToolModulePlugin(options)`

Decorates the module template by wrapping each module in a `eval` annotated with `// @sourceURL`.

### WebWorkerTemplatePlugin

`webworker.WebWorkerTemplatePlugin(options)`

Chunks are loaded by `importScripts`.

`options` are the output options.

### FetchCompileAsyncWasmPlugin

This plugin is used to provide runtime code for WASM bundling and is often used together with a child compiler.

`web.FetchCompileAsyncWasmPlugin()`

## source

Plugins affecting the source code of modules.

### ProvidePlugin

`ProvidePlugin(name, request)`

If `name` is used in a module it is filled by a module loaded by `require(<request>)`.

### NodeTargetPlugin

`node.NodeTargetPlugin()`

The plugins should be used if you run the bundle in a Node.js environment.

If ensures that native modules are loaded correctly even if bundled.

## optimize

Note that all plugins under `rspack.optimize` namespace should only be used when `mode` set to `'none'`. Otherwise you might get into trouble where plugins are applied twice.

### LimitChunkCountPlugin

`optimize.LimitChunkCountPlugin(options)`

Merge chunks limit chunk count is lower than `options.maxChunks`.

The overhead for each chunks is provided by `options.chunkOverhead` or defaults to 10000. Entry chunks sizes are multiplied by `options.entryChunkMultiplicator` (or 10).

Chunks that reduce the total size the most are merged first. If multiple combinations are equal the minimal merged size wins.

## loader

### LoaderOptionsPlugin

`LoaderOptionsPlugin(options)`

### LoaderTargetPlugin

`LoaderTargetPlugin(target)`

## module federation

Internal plugins used with Module Federation, which are the basis of the `ModuleFederationPlugin`.

### ContainerPlugin

`container.ContainerPlugin(options)`

### ContainerReferencePlugin

`container.ContainerReferencePlugin(options)`

### ConsumeSharedPlugin

`sharing.ConsumeSharedPlugin(options)`

### ProvideSharedPlugin

`sharing.ProvideSharedPlugin(options)`

### SharePlugin

`sharing.SharePlugin(options)`

## experiments

### RemoveDuplicateModulesPlugin

`experiments.RemoveDuplicateModulesPlugin()`



---
url: /api/index.md
---

# 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) and a few flags (e.g. `--env`).

[Learn more about the CLI →](/api/cli)

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

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

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

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



---
url: /api/cli.md
---

# 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) 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#specify-the-configuration-file)                |
| --configLoader       | Specify the loader to load the config file, can be `native` or `register`, defaults to `register`                                             |
| --configName         | Specify the name of the configuration to use.                                                                                                 |
| --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#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        devtool                        [boolean] [default: false]
      --analyze        analyze                        [boolean] [default: false]
      --json           emit stats json
      --profile        capture timing information for each module
                                                      [boolean] [default: false]
```

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

```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
```

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        devtool                        [boolean] [default: false]
      --hot            enables hot module replacement
      --port           allows to specify a port to use                  [number]
      --host           allows to specify a hostname to use              [string]
```

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

```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
---

import WebpackLicense from '@components/WebpackLicense';
import { ApiMeta } from '@components/ApiMeta';

<WebpackLicense from="https://webpack.js.org/api/module-methods/" />

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

<ApiMeta specific={['Rspack', 'Webpack']} />

Inline comments to make features work. By adding comments to the import, we can do things such as specify chunk name or select different loading modes. For a full list of these magic comments see the code below followed by an explanation of what these comments do.

```js
// Single target
import(
  /* webpackChunkName: "my-chunk-name" */
  /* webpackMode: "lazy" */
  /* webpackExports: ["default", "named"] */
  /* webpackFetchPriority: "high" */
  'module'
);

// Multiple possible targets
import(
  /* webpackInclude: /\.json$/ */
  /* webpackExclude: /\.noimport\.json$/ */
  /* webpackChunkName: "my-chunk-name" */
  /* webpackMode: "lazy" */
  /* webpackPrefetch: true */
  /* webpackPreload: true */
  `./locale/${language}`
);
```

##### webpackIgnore

- **Type:** `boolean`

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' /* webpackIgnore: true */).then((React) => {
  console.log(React.version); // 19.0.0
});
```

`webpackIgnore` 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 `webpackIgnore: 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(/* webpackIgnore: true */ './index.css', import.meta.url);
```

##### webpackMode

- **Type:** `"eager" | "lazy" | "weak" | "lazy-once"`
- **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.

##### webpackPrefetch

- **Type:**
  - `number`: chunk prefetch priority
  - `boolean`: `false` means not to prefetch, `true` means priority is `0`

Tells the browser that the resource is probably needed for some navigation in the future, see [Prefetching/Preloading modules](/guide/optimization/code-splitting#prefetchingpreloading-modules) for more details.

##### webpackPreload

- **Type:**
  - `number`: chunk preload priority
  - `boolean`: `false` means not to preload, `true` means priority is `0`

Tells the browser that the resource might be needed during the current navigation, , see [Prefetching/Preloading modules](/guide/optimization/code-splitting#prefetchingpreloading-modules) for more details.

##### webpackChunkName

- **Type:**: `string`

A name for the new chunk.

##### webpackFetchPriority

<ApiMeta addedVersion="1.0.0" />

- **Type:**: `"low" | "high" | "auto"`

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.

##### webpackInclude

<ApiMeta addedVersion="1.0.0" />

- **Type:**: `Regexp`

A regular expression that will be matched against during import resolution. Only modules that match **will be bundled**.

##### webpackExclude

<ApiMeta addedVersion="1.0.0" />

- **Type:**: `Regexp`

A regular expression that will be matched against during import resolution. Any module that matches **will not be bundled**.

:::info
Note that `webpackInclude` and `webpackExclude` options do not interfere with the prefix. eg: `./locale`.
:::

##### webpackExports

<ApiMeta addedVersion="1.0.0" />

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

Tells webpack to only bundle the specified exports of a dynamically `import()`ed module. It can decrease the output size of a chunk.

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

<ApiMeta specific={['Rspack', 'Webpack']} />

`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#importmetawebpackcontext). We recommend using `import.meta.webpackContext`, which is more powerful.
:::

- **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

<ApiMeta specific={['Rspack', 'Webpack']} />

:::tip
`require.ensure()` is specific to rspack/webpack and superseded by `import()`.
:::

Split out the given `dependencies` to a separate bundle that will be loaded asynchronously. When using CommonJS module syntax, this is the only way to dynamically load `dependencies`. Meaning, this code can be run within execution, only loading the dependencies if certain conditions are met.

:::warning
This feature relies on [Promise](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise) internally. If you use `require.ensure` with 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).
:::

- **Type:**

```ts
function requireEnsure(
  /**
   * An array of strings declaring all modules required for the code in the callback to execute.
   */
  dependencies: String[],
  /**
   * A function that webpack will execute once the dependencies are loaded.
   * An implementation of the require function is sent as a parameter to this function.
   * The function body can use this to further require() modules it needs for execution
   */
  callback: function(require),
  /**
   * A function that is executed when webpack 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;
```

- **Example:**

```ts
var a = require('normal-dep');

if (module.hot) {
  require.ensure(['b'], function (require) {
    var c = require('c');

    // Do something special...
  });
}
```

### require.resolveWeak

<ApiMeta specific={['Rspack', 'Webpack']} />

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#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: [
          // ...
        ],
      },
    ],
  },
};
```



---
url: /api/runtime-api/module-variables.md
---

import WebpackLicense from '@components/WebpackLicense';
import Columns from '@components/Columns';
import { ApiMeta } from '@components/ApiMeta';

<WebpackLicense from="https://webpack.js.org/api/module-variables/" />

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

<Columns>
```js title=Source
global['property']
```

```js title=Compiled
__webpack_require__.g['property'];

// webpack/runtime/global
__webpack_require__.g = (function () {
  // compatibility code
})();
```

</Columns>

### \_\_filename

Depends on the configuration [`node.__filename`](/config/node#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`.

<Columns>
```js title=Source
__filename
```

```js title=Compiled
'src/main.js';
```

</Columns>

### \_\_dirname

Depends on the configuration [`node.__dirname`](/config/node#node__dirname).

- `false`: undefined
- `mock`: equal to `'/index.js'`
- `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`.

<Columns>
```js title=Source
__dirname
```

```js title=Compiled
'src';
```

</Columns>

## import.meta (ESM)

The `import.meta` exposes context-specific metadata to a JavaScript module, such as the URL of the module. It is only available in ESM.

> Please note that Rspack does not support direct access to `import.meta`. Instead, you should access its properties or use destructuring assignment. E.g.,

<Columns>
```js title="Source"
import.meta
typeof import.meta
```

```js title="Compiled"
{
} // Warning: Direct access to import.meta is not supported (only property access or destructuring is supported)
('object');
```

</Columns>

### import.meta.url

Returns the absolute `file:` URL of the module.

<Columns>
```js title=Source
import.meta.url
typeof import.meta.url
```

```js title=Compiled
'file://project_root/src/main.js';
'string';
```

</Columns>

### import.meta.webpackContext

<ApiMeta specific={['Rspack', 'Webpack']} />

`import.meta.webpackContext` is a function specific to webpack that allows you to dynamically import a set of modules.

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

<ApiMeta specific={['Rspack', 'Webpack']} />

An alias for [`module.hot`](#modulehot), however `import.meta.webpackHot` can be used in strict ESM while `module.hot` can't.

## Runtime

### \_\_webpack_hash\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

It provides access to the hash of the compilation.

<Columns>
```js title=Source
__webpack_hash__
```

```js title=Compiled
__webpack_require__.h();

// webpack/runtime/get_full_hash
__webpack_require__.h = function () {
  return '9210c6f859a51c6f9a62';
};
```

</Columns>

### \_\_webpack_runtime_id\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

Access the runtime id of current entry.

<Columns>
```js title=Source
__webpack_runtime_id__
```

```js title=Compiled
__webpack_require__.j;

// webpack/runtime/runtime_id
__webpack_require__.j = '909';
```

</Columns>

### \_\_webpack_public_path\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

Equals the configuration option's [`output.publicPath`](/config/output#outputpublicpath).

<Columns>
```js title=Source
__webpack_public_path__
```

```js title=Compiled
__webpack_require__.p;

// output.publicPath !== "auto"
__webpack_require__.p = 'output.publicPath';
// output.publicPath === "auto"
__webpack_require__.p = 'calculated from document/location';
```

</Columns>

> See [Dynamically set publicPath](/guide/features/asset-base-path#dynamically-set-publicpath) for more information about the usage of `__webpack_public_path__`.

### \_\_webpack_base_uri\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

Get or change base URI at runtime.

<Columns>
```js title=Source
__webpack_base_uri__
```

```js title=Compiled
__webpack_require__.b;

// chunk loading
__webpack_require__.b = document.baseURI || self.location.href;
```

</Columns>

### \_\_webpack_nonce\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

Rspack is capable of adding a nonce to all scripts that it loads.
To activate this feature, set a `__webpack_nonce__` variable and include it in your entry script.

<Columns>
```js title=Source
__webpack_nonce__ = 'your_nonce_code';
```

```js title=Compiled
__webpack_require__.nc = '2312312';

// webpack/runtime/load_script
if (__webpack_require__.nc) {
  script.setAttribute('nonce', __webpack_require__.nc);
}
```

</Columns>

## Modules

### \_\_webpack_modules\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

Access to the internal object of all modules.

<Columns>
```js title=Source
__webpack_modules__
```

```js title=Compiled
var __webpack_modules__ = {
  'main.js': function () {
    __webpack_require__.m;
  },
};
__webpack_require__.m = __webpack_modules__;
```

</Columns>

### \_\_webpack_module\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

It provides access to the the current `module`. `module` is not available in strict ESM.

<Columns>
```js title=Source
__webpack_module__
```

```js title=Compiled
"main.js": function(renamed_module) {
  renamed_module
}
```

</Columns>

### \_\_webpack_module\_\_.id

<ApiMeta specific={['Rspack', 'Webpack']} />

It provides access to the ID of current module (`module.id`). `module` is not available in strict ESM.

<Columns>
```js title=Source
__webpack_module__.id
```

```js title=Compiled
"main.js": function(renamed_module) {
  renamed_module.id
}
```

</Columns>

### \_\_webpack_require\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

The raw require function.
This expression isn't parsed by the Parser for dependencies.

<Columns>
```js title=Source
__webpack_require__('./dep.js')
```

```js title=Compiled
"main.js": function(_, __, renamed_require) {
  renamed_require('./dep.js')
}
```

</Columns>

### \_\_non_webpack_require\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

Generates a `require` function that is not parsed by webpack.
Can be used to do cool stuff with a global require function if available.

<Columns>
```js title=Source
__non_webpack_require__('outer.js')
```

```js title=Compiled
"main.js": function(_, __, __webpack_require__) {
  require('outer.js')
}
```

</Columns>

### \_\_webpack_is_included\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

Test whether or not the given module is bundled by webpack.

<Columns>
```js title=Source
if (__webpack_is_included__('./dep.js')) {
  // do something
}
```

```js title=Compiled
if (true) {
  // do something
}
```

</Columns>

### \_\_resourceQuery

<ApiMeta specific={['Rspack', 'Webpack']} />

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');
```

<Columns>
```js title=Source
__resourceQuery
```

```js title=Compiled
'?test';
```

</Columns>

### \_\_webpack_exports_info\_\_

<ApiMeta addedVersion="1.0.0" specific={['Rspack', 'Webpack']} />

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`

<Columns>
```js title=Source
if (__webpack_exports_info__.someUsedExport.used) { }
if (__webpack_exports_info__.someUnusedExport.used) { }
```

```js title=Compiled
if (true) {
}
if (false) {
}
```

</Columns>

## Chunks

### \_\_webpack_chunkname\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

Get current chunk name.

<Columns>
```js title=Source
__webpack_chunkname__
```

```js title=Compiled
__webpack_require__.cn;

// webpack/runtime/chunk_name
__webpack_require__.cn = 'main';
```

</Columns>

### \_\_webpack_chunk_load\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

The internal chunk loading function. Takes one argument:

- `chunkId`: the id for the chunk to load.

<Columns>
```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
};
```

</Columns>

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) {
    __webpack_public_path__ = 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\_\_

<ApiMeta addedVersion="1.0.0" specific={['Rspack', 'Webpack']} />

It provides filename of the chunk by its id.

<Columns>
```js title=Source
__webpack_get_script_filename__
```

```js title=Compiled
__webpack_require__.u;

// webpack/runtime/get_chunk_filename
__webpack_require__.u = function (chunkId) {
  // ...
};
```

</Columns>

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\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

This object is used as a shared scope in the remote container and is filled with the provided modules from a host

### \_\_webpack_init_sharing\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

This method is used to initialize modules of a shared scope in the host container.

## System.js

### \_\_system_context\_\_

<ApiMeta specific={['Rspack', 'Webpack']} />

Context from System.js when `output.libraryTarget="system"`

## Rspack

### \_\_rspack_version\_\_

<ApiMeta specific={['Rspack']} />
Current Rspack version, default to version in `@rspack/core/package.json`, can
be modified through experiments.rspackFuture.bundlerInfo.version.

<Columns>
```js title=Source
__rspack_version__
```

```js title=Compiled
__webpack_require__.rv;

// webpack/runtime/rspack_version
__webpack_require__.rv = '0.7.4';
```

</Columns>

### \_\_rspack_unique_id\_\_

<ApiMeta addedVersion="1.0.0" specific={['Rspack']} />

The ID of the current bundler, the value is `bundler={bundler}@{version}`:

- `bundler`: Default to `"rspack"` and can be modified through [experiments.rspackFuture.bundlerInfo.bundler](/config/experiments#rspackfuturebundlerinfo).
- `version`: Default to version in `@rspack/core/package.json` and can be modified through [experiments.rspackFuture.bundlerInfo.version](/config/experiments#rspackfuturebundlerinfo).

<Columns>
```js title=Source
__rspack_unique_id__
```

```js title=Compiled
__webpack_require__.ruid;

// webpack/runtime/rspack_unique_id
__webpack_require__.ruid = 'bundler=rspack@0.7.4';
```

</Columns>



---
url: /api/runtime-api/hmr.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/api/hot-module-replacement/" />

# Hot module replacement

Rspack provides the same interface as webpack for implementing HMR.

If you've enabled Hot Module Replacement via the [HotModuleReplacementPlugin](/plugins/webpack/hot-module-replacement-plugin), 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);
```



---
url: /api/javascript-api/index.md
---

import WebpackLicense from '@components/WebpackLicense';
import { Collapse, CollapsePanel } from '@components/Collapse';
import { Tab, Tabs, PackageManagerTabs } from '@theme';
import { Stability } from '@components/ApiMeta';




<WebpackLicense from="https://webpack.js.org/api/node/" />

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

## Installation

To start using the Rspack JavaScript API, first install `@rspack/core` if you haven't yet:

<PackageManagerTabs command="add @rspack/core -D" />

Then introduce the `@rspack/core` module in your JavaScript file:

<Tabs>
  <Tab label="ESM">

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

  </Tab>
  <Tab label="CJS">

```js title="build.cjs"
const { rspack } = require('@rspack/core');
```

  </Tab>
</Tabs>

## 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#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#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). 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) for more details.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compiler.ts"
    key="compiler"
  >
    <>

```ts
type Compiler = {
  hooks: CompilerHooks;
  inputFileSystem: InputFileSystem | null;
  outputFileSystem: OutputFileSystem | null;
  watchFileSystem: WatchFileSystem | null;
  options: RspackOptionsNormalized;
  watching: Watching;

  getInfrastructureLogger(name: string | (() => string)): Logger;
  getCache(name: string): CacheFacade;
  watch(
    watchOptions: Watchpack.WatchOptions,
    handler: liteTapable.Callback<Error, Stats>,
  ): Watching;
  run(callback: liteTapable.Callback<Error, Stats>): void;
  runAsChild(
    callback: (
      err?: null | Error,
      entries?: Chunk[],
      compilation?: Compilation,
    ) => any,
  ): void;
  createChildCompiler(
    compilation: Compilation,
    compilerName: string,
    compilerIndex: number,
    outputOptions: OutputNormalized,
    plugins: RspackPluginInstance[],
  ): Compiler;
  compile(callback: liteTapable.Callback<Error, Compilation>): void;
  close(callback: (error?: Error | null) => void): void;
};
```

</>

  </CollapsePanel>
</Collapse>

## 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#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#watch) for more details.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Watching.ts"
    key="watching"
  >
    <>

```ts
type Watching = {
  watch(
    files: Iterable<string>,
    dirs: Iterable<string>,
    missing: Iterable<string>,
  ): void;
  suspend(): void;
  resume(): void;
  invalidate(callback?: Callback<Error, void>): void;
  close(callback?: () => void): void;
};
```

</>

  </CollapsePanel>
</Collapse>

## Stats object

The `stats` object that is passed as a second argument of the [`rspack()`](/api/javascript-api/index#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) 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) for more details.

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Stats.ts" key="stats">
    <>

```ts
type Stats = {
  compilation: Compilation;
  hash: Readonly<string | null>;
  startTime?: number;
  endTime?: number;
  hasErrors(): bool;
  hasWarnings(): bool;
  toJson(opts?: StatsValue): StatsCompilation;
  toString(opts?: StatsValue): string;
};
```

</>

  </CollapsePanel>
</Collapse>

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



---
url: /api/javascript-api/compiler.md
---










import { Collapse, CollapsePanel } from '@components/Collapse';
import { Badge } from '@theme';

# 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) or [CLI](/api/cli).

It provides methods like [run](#run) and [watch](#watch) to start builds, and exposes [Compiler hooks](/api/plugin-api/compiler-hooks) 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) => {});
  });
});
```

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Stats.ts" key="Stats">
    <>

```ts
type Stats = {
  compilation: Compilation;
  hash: Readonly<string | null>;
  startTime?: number;
  endTime?: number;
  hasErrors(): bool;
  hasWarnings(): bool;
  toJson(opts?: StatsValue): StatsCompilation;
  toString(opts?: StatsValue): string;
};
```

</>

  </CollapsePanel>
</Collapse>

### 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: string[], dirs: string[], missing: 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.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="WatchOptions.ts"
    key="WatchOptions"
  >

    > See [watch options](/config/watch#watchoptions) for more details.

  </CollapsePanel>
  <CollapsePanel
    className="collapse-code-panel"
    header="Stats.ts"
    key="Stats"
  >
    <>

```ts
type Stats = {
  compilation: Compilation;
  hash: Readonly<string | null>;
  startTime?: number;
  endTime?: number;
  hasErrors(): bool;
  hasWarnings(): bool;
  toJson(opts?: StatsValue): StatsCompilation;
  toString(opts?: StatsValue): string;
};
```

</>

  </CollapsePanel>
</Collapse>

### 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) that is not associated with any compilation, which is used to print global logs.

```ts
function getInfrastructureLogger(name: string): Logger;
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Logger.ts"
    key="Logger"
  >
    <>

> See [Logger API](/api/javascript-api/logger) for more details

```ts
type Logger = {
  getChildLogger: (name: string | (() => string)) => Logger; // create a child logger
  error(...args: any[]): void; // display errors
  warn(...args: any[]): void; //  display warnings
  info(...args: any[]): void; // display important information
  log(...args: any[]): void; // display unimportant information
  debug(...args: string[]): void; // display debug information
  assert(assertion: any, ...args: any[]): void; // display errors if assertion failed
  trace(): void; // display a stack trace
  clear(): void; // clear all logs
  status(...args: any[]): void; // display status information
  group(...args: any[]): void; // start a logging group
  groupEnd(...args: any[]): void; // end a logging group
  groupCollapsed(...args: any[]): void; // group logs together
  profile(label: any): void; // start capturing a profile
  profileEnd(label: any): void; // end capturing a profile
  time(label: any): void; // start a timer
  timeLog(label: any): void; // not end the timer and record the time difference
  timeEnd(label: any): void; // end the timer and record the time difference
  timeAggregate(label: any): void; // aggregate capture the time difference
  timeAggregateEnd(label: any): void; // end the aggregate capturing
};
```

</>

  </CollapsePanel>
</Collapse>

### getCache

Creates a cache object to share data during the build process.

```ts
function getCache(name: string): CacheFacade;
```

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Cache.ts" key="Cache">
    <>

> See [cache object](/api/javascript-api/cache) for more details.

```ts
type CacheFacade = {
  getChildCache(name: string): CacheFacade; // create a named child cache object
  getItemCache(identifier, etag): ItemCacheFacade; // create a cache object for an data item
  getLazyHashedEtag(obj: HashableObject): Etag; // create a lazy computed etag
  mergeEtags(a: Etag, b: Etag): Etag; // merge two etags
  get<T>( // async data getter, callback by function
    identifier: string,
    etag: Etag,
    callback: (err: Error, result: T) => void,
  ): void;
  getPromise<T>( // async data getter, callback by promise
    identifier: string,
    etag: Etag,
  ): Promise<T>;
  store<T>( // async data setter, callback by function
    identifier: string,
    etag: Etag,
    data: T,
    callback: (err: Error) => void,
  ): void;
  storePromise<T>( // async data setter, callback by promise
    identifier: string,
    etag: Etag,
    data: T,
  ): Promise<void>;
  provide<T>( // try to get the data, use function to compute if not exists, callback by function
    identifier: string,
    etag: Etag,
    computer: () => T | Promise<T>,
    callback: (err: Error, result: T) => void,
  ): void;
  providePromise<T>( // try to get the data, use function to compute if not exists, callback by function
    identifier: string,
    etag: Etag,
    computer: () => T | Promise<T>,
  ): Promise<T>;
};
```

</>

  </CollapsePanel>
</Collapse>

### 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;
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compilation.ts"
    key="Compilation"
  >
    <>

> See [compilation object](/api/javascript-api/compilation) for more details.

```ts
type Compilation = {
  emitAsset(): void; // add a new asset
  updateAsset(): void; // update content of the asset
  renameAsset(): void; // rename the asset
  deleteAsset(): void; // delete an existing asset
  getAssets(): Asset[]; // get all assets
  getAsset(): Asset; // get asset from name
  getPath(): string; // generate path from template
  getPathWithInfo(): PathWithInfo; // generate path and asset info from template
  getStats(): Stats; // get stats object
  createChildCompiler(): Compiler; // create a child compiler
  rebuildModule(): void; // run module.build again
  getLogger(): Logger; // get compilation related logger object
  getCache(): CacheFacade; // get compilation related cache object
  options: RspackOptionsNormalized; // the compiler options
  compiler: Compiler; // current compiler
  hooks: CompilationHooks; // hooks of compilation
  hash: string | null; // hash of this compilation
  fullhash: string | null; // same as 'hash'
  assets: Record<string, Source>; // mapping from filename to asset content
  chunkGroups: ChunkGroup[]; // list of chunk groups
  entrypoints: Map<string, Entrypoint>; // mapping from name to entrypoint
  namedChunkGroups: Map<string, ChunkGroup>; // mapping named chunk groups
  modules: Set<Module>; // set of all modules
  chunks: Set<Chunk>; // set of all chunks
  namedChunks: Map<string, Chunk>; // mapping of named chunks
  fileDependencies: CompilationDependencies; // dependent files
  contextDependencies: CompilationDependencies; // dependent directories
  missingDependencies: CompilationDependencies; // dependent missing files
  buildDependencies: CompilationDependencies; // dependent build files
  errors: RspackError[]; // errors during compilation
  warnings: RspackError[]; // warnings during compilation
};
```

</>

  </CollapsePanel>
  <CollapsePanel
    className="collapse-code-panel"
    header="OutputOptions.ts"
    key="OutputOptions"
  >

    > See [output options](/config/output) for more details.

  </CollapsePanel>
  <CollapsePanel
    className="collapse-code-panel"
    header="RspackPlugin.ts"
    key="RspackPlugin"
  >

    > See [plugins options](/config/plugins) for more details

  </CollapsePanel>
</Collapse>

### 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;
```

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Chunk.ts" key="Chunk">
    <>

> See [cache object](/api/javascript-api/cache) for more details.

```ts
type CacheFacade = {
  getChildCache(name: string): CacheFacade; // create a named child cache object
  getItemCache(identifier, etag): ItemCacheFacade; // create a cache object for an data item
  getLazyHashedEtag(obj: HashableObject): Etag; // create a lazy computed etag
  mergeEtags(a: Etag, b: Etag): Etag; // merge two etags
  get<T>( // async data getter, callback by function
    identifier: string,
    etag: Etag,
    callback: (err: Error, result: T) => void,
  ): void;
  getPromise<T>( // async data getter, callback by promise
    identifier: string,
    etag: Etag,
  ): Promise<T>;
  store<T>( // async data setter, callback by function
    identifier: string,
    etag: Etag,
    data: T,
    callback: (err: Error) => void,
  ): void;
  storePromise<T>( // async data setter, callback by promise
    identifier: string,
    etag: Etag,
    data: T,
  ): Promise<void>;
  provide<T>( // try to get the data, use function to compute if not exists, callback by function
    identifier: string,
    etag: Etag,
    computer: () => T | Promise<T>,
    callback: (err: Error, result: T) => void,
  ): void;
  providePromise<T>( // try to get the data, use function to compute if not exists, callback by function
    identifier: string,
    etag: Etag,
    computer: () => T | Promise<T>,
  ): Promise<T>;
};
```

</>

  </CollapsePanel>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compilation.ts"
    key="Compilation"
  >
    <>

> See [compilation object](/api/javascript-api/compilation) for more details.

```ts
type Compilation = {
  emitAsset(): void; // add a new asset
  updateAsset(): void; // update content of the asset
  renameAsset(): void; // rename the asset
  deleteAsset(): void; // delete an existing asset
  getAssets(): Asset[]; // get all assets
  getAsset(): Asset; // get asset from name
  getPath(): string; // generate path from template
  getPathWithInfo(): PathWithInfo; // generate path and asset info from template
  getStats(): Stats; // get stats object
  createChildCompiler(): Compiler; // create a child compiler
  rebuildModule(): void; // run module.build again
  getLogger(): Logger; // get compilation related logger object
  getCache(): CacheFacade; // get compilation related cache object
  options: RspackOptionsNormalized; // the compiler options
  compiler: Compiler; // current compiler
  hooks: CompilationHooks; // hooks of compilation
  hash: string | null; // hash of this compilation
  fullhash: string | null; // same as 'hash'
  assets: Record<string, Source>; // mapping from filename to asset content
  chunkGroups: ChunkGroup[]; // list of chunk groups
  entrypoints: Map<string, Entrypoint>; // mapping from name to entrypoint
  namedChunkGroups: Map<string, ChunkGroup>; // mapping named chunk groups
  modules: Set<Module>; // set of all modules
  chunks: Set<Chunk>; // set of all chunks
  namedChunks: Map<string, Chunk>; // mapping of named chunks
  fileDependencies: CompilationDependencies; // dependent files
  contextDependencies: CompilationDependencies; // dependent directories
  missingDependencies: CompilationDependencies; // dependent missing files
  buildDependencies: CompilationDependencies; // dependent build files
  errors: RspackError[]; // errors during compilation
  warnings: RspackError[]; // warnings during compilation
};
```

</>

  </CollapsePanel>
</Collapse>

### isChild

Whether this compiler is a child compiler.

```ts
function isChild(): boolean;
```

## Compiler properties

### hooks

See [compiler hooks](/api/plugin-api/compiler-hooks) 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#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#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).

### root

- **Type:** `Compiler`

Get the root of the child compiler tree.

### options

- **Type:** `RspackOptionsNormalized`

Get the full options used by this compiler.

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

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="InputFileSystem.ts"
    key="InputFileSystem"
  >
    <>

```ts
import fs from 'fs';
type InputFileSystem = {
  readFile: typeof fs.readFile;
  readFileSync: typeof fs.readFileSync;
  readlink: typeof fs.readlink;
  readlinkSync: typeof fs.readlinkSync;
  readdir: typeof fs.readdir;
  readdirSync: typeof fs.readdirSync;
  stat: typeof fs.stat;
  statSync: typeof fs.statSync;
  lstat: typeof fs.lstat;
  lstatSync: typeof fs.lstatSync;
  realpath: typeof fs.realpath;
  realpathSync: typeof fs.realpathSync;
  readJson: typeof fs.readJson;
  readJsonSync: typeof fs.readJsonSync;
  purge: (arg0?: (string | string[] | Set<string>) | undefined) => void;
};
```

</>

  </CollapsePanel>
</Collapse>

### outputFileSystem

- **Type:** `OutputFileSystem`

Get the proxy object used for writing to the file system, `fs` by default.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="OutputFileSystem.ts"
    key="OutputFileSystem"
  >
    <>

```ts
import fs from 'fs';
type OutputFileSystem = {
  writeFile: typeof fs.writeFile;
  mkdir: typeof fs.mkdir;
  readdir: typeof fs.readdir;
  rmdir: typeof fs.rmdir;
  unlink: typeof fs.unlink;
  stat: typeof fs.stat;
  lstat: typeof fs.lstat;
  readFile: typeof fs.readFile;
};
```

</>

  </CollapsePanel>
</Collapse>

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

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="WatchFileSystem.ts"
    key="WatchFileSystem"
  >
    <>

```ts
type WatchFileSystem = {
  watch(
    files: string[],
    directories: string[],
    missing: string[],
    startTime: number,
    options: WatchOptions,
    callback: (
      err: Error | null,
      fileEntries: Map<string, FileSystemInfoEntry>,
      contextEntries: Map<string, FileSystemInfoEntry>,
      changes: Set<string>,
      removals: Set<string>
    ): void,
    callbackUndelayed: ( // Triggered immediately after the first change
      file: string,
      time: number
    ): void;
  ): {
    close(): void,
    pause(): void,
    getAggregatedChanges(): Set<string>,
    getAggregatedRemovals(): Set<string>,
    getFileTimeInfoEntries():  Map<string, FileSystemInfoEntry | "ignore">,
    getContextTimeInfoEntries():  Map<string, FileSystemInfoEntry | "ignore">,
    getInfo: WatcherInfo
  }
};
```

</>

  </CollapsePanel>
</Collapse>

## 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
const { rspack } = require('@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) that is not associated with any compilation, which is used to print global logs.

```ts
getInfrastructureLogger(name: string): Logger;
```

> Same with `compilers[0].getInfrastructureLogger()`

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Logger.ts"
    key="Logger"
  >
    <>

> See [Logger API](/api/javascript-api/logger) for more details

```ts
type Logger = {
  getChildLogger: (name: string | (() => string)) => Logger; // create a child logger
  error(...args: any[]): void; // display errors
  warn(...args: any[]): void; //  display warnings
  info(...args: any[]): void; // display important information
  log(...args: any[]): void; // display unimportant information
  debug(...args: string[]): void; // display debug information
  assert(assertion: any, ...args: any[]): void; // display errors if assertion failed
  trace(): void; // display a stack trace
  clear(): void; // clear all logs
  status(...args: any[]): void; // display status information
  group(...args: any[]): void; // start a logging group
  groupEnd(...args: any[]): void; // end a logging group
  groupCollapsed(...args: any[]): void; // group logs together
  profile(label: any): void; // start capturing a profile
  profileEnd(label: any): void; // end capturing a profile
  time(label: any): void; // start a timer
  timeLog(label: any): void; // not end the timer and record the time difference
  timeEnd(label: any): void; // end the timer and record the time difference
  timeAggregate(label: any): void; // aggregate capture the time difference
  timeAggregateEnd(label: any): void; // end the aggregate capturing
};
```

</>

  </CollapsePanel>
</Collapse>

### MultiCompiler properties

#### compilers

- **Type:** `Compiler[]`

Get all included compilers.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compiler.ts"
    key="Compiler"
  >
    <>

```ts
type Compiler = {
  hooks: CompilerHooks;
  inputFileSystem: InputFileSystem | null;
  outputFileSystem: OutputFileSystem | null;
  watchFileSystem: WatchFileSystem | null;
  options: RspackOptionsNormalized;
  watching: Watching;

  getInfrastructureLogger(name: string | (() => string)): Logger;
  getCache(name: string): CacheFacade;
  watch(
    watchOptions: Watchpack.WatchOptions,
    handler: liteTapable.Callback<Error, Stats>,
  ): Watching;
  run(callback: liteTapable.Callback<Error, Stats>): void;
  runAsChild(
    callback: (
      err?: null | Error,
      entries?: Chunk[],
      compilation?: Compilation,
    ) => any,
  ): void;
  createChildCompiler(
    compilation: Compilation,
    compilerName: string,
    compilerIndex: number,
    outputOptions: OutputNormalized,
    plugins: RspackPluginInstance[],
  ): Compiler;
  compile(callback: liteTapable.Callback<Error, Compilation>): void;
  close(callback: (error?: Error | null) => void): void;
};
```

</>

  </CollapsePanel>
</Collapse>

#### options

<Badge text="ReadOnly" type="info" />

- **Type:** `RspackOptionsNormalized[]`

Get all the [full options](/config/index) used by the compilers.

#### inputFileSystem

<Badge text="WriteOnly" type="info" />

- **Type:** `InputFileSystem`

Set the proxy object used for reading from the file system for each compiler.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="InputFileSystem.ts"
    key="InputFileSystem"
  >
    <>

```ts
import fs from 'fs';
type InputFileSystem = {
  readFile: typeof fs.readFile;
  readFileSync: typeof fs.readFileSync;
  readlink: typeof fs.readlink;
  readlinkSync: typeof fs.readlinkSync;
  readdir: typeof fs.readdir;
  readdirSync: typeof fs.readdirSync;
  stat: typeof fs.stat;
  statSync: typeof fs.statSync;
  lstat: typeof fs.lstat;
  lstatSync: typeof fs.lstatSync;
  realpath: typeof fs.realpath;
  realpathSync: typeof fs.realpathSync;
  readJson: typeof fs.readJson;
  readJsonSync: typeof fs.readJsonSync;
  purge: (arg0?: (string | string[] | Set<string>) | undefined) => void;
};
```

</>

  </CollapsePanel>
</Collapse>

#### outputFileSystem

<Badge text="WriteOnly" type="info" />

- **Type:** `OutputFileSystem`

Set the proxy object used for writing from the file system for each compiler.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="OutputFileSystem.ts"
    key="OutputFileSystem"
  >
    <>

```ts
import fs from 'fs';
type OutputFileSystem = {
  writeFile: typeof fs.writeFile;
  mkdir: typeof fs.mkdir;
  readdir: typeof fs.readdir;
  rmdir: typeof fs.rmdir;
  unlink: typeof fs.unlink;
  stat: typeof fs.stat;
  lstat: typeof fs.lstat;
  readFile: typeof fs.readFile;
};
```

</>

  </CollapsePanel>
</Collapse>

#### watchFileSystem

<Badge text="WriteOnly" type="info" />

- **Type:** `WatchFileSystem`

Set the proxy object used for watching files or directories changes for each compiler.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="WatchFileSystem.ts"
    key="WatchFileSystem"
  >
    <>

```ts
type WatchFileSystem = {
  watch(
    files: string[],
    directories: string[],
    missing: string[],
    startTime: number,
    options: WatchOptions,
    callback: (
      err: Error | null,
      fileEntries: Map<string, FileSystemInfoEntry>,
      contextEntries: Map<string, FileSystemInfoEntry>,
      changes: Set<string>,
      removals: Set<string>
    ): void,
    callbackUndelayed: ( // Triggered immediately after the first change
      file: string,
      time: number
    ): void;
  ): {
    close(): void,
    pause(): void,
    getAggregatedChanges(): Set<string>,
    getAggregatedRemovals(): Set<string>,
    getFileTimeInfoEntries():  Map<string, FileSystemInfoEntry | "ignore">,
    getContextTimeInfoEntries():  Map<string, FileSystemInfoEntry | "ignore">,
    getInfo: WatcherInfo
  }
};
```

</>

  </CollapsePanel>
</Collapse>

#### running

- **Type:** `boolean`

Whether the compilation is currently being executed.



---
url: /api/javascript-api/compilation.md
---

import WebpackLicense from '@components/WebpackLicense';














import { Collapse, CollapsePanel } from '@components/Collapse';
import { ApiMeta } from '@components/ApiMeta';

<WebpackLicense from="https://webpack.js.org/api/compilation-object/" />

# 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) 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#thiscompilation) or [compiler.hooks.compilation](/api/plugin-api/compiler-hooks#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:

```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,
    });
  });
});
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Source.ts"
    key="Source"
  >
    <>

```ts
type Source = {
  source(): string | ArrayBuffer;
  buffer(): Buffer;
  size(): number;
  map(options?: MapOptions): RawSourceMap | null;
  sourceAndMap(options?: MapOptions): SourceAndMapResult;
};
```

</>

  </CollapsePanel>
  <CollapsePanel
    className="collapse-code-panel"
    header="AssetInfo.ts"
    key="AssetInfo"
  >
    <>

```ts
type AssetInfo = {
  immutable: boolean;
  minimized: boolean;
  fullhash: Array<string>;
  chunkhash: Array<string>;
  contenthash: Array<string>;
  sourceFilename?: string;
  development: boolean;
  hotModuleReplacement: boolean;
  javascriptModule?: boolean;
  related: JsAssetInfoRelated;
  cssUnusedIdents?: Array<string>;
};
```

</>

  </CollapsePanel>
</Collapse>

### 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)
): void;
```

The following code replaces the content of `main.js` and not to minimize it:

```js
compiler.hooks.thisCompilation.tap('MyPlugin', (compilation) => {
  const { RawSource } = compiler.rspack.sources;
  compilation.hooks.processAssets.tap('MyPlugin', () => {
    const updatedSource = new RawSource(
      `module.exports = "This is the updated"`,
    );
    compilation.updateAsset('main.js', updatedSource, {
      minimized: true,
    });
  });
});
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Source.ts"
    key="Source"
  >
    <>

```ts
type Source = {
  source(): string | ArrayBuffer;
  buffer(): Buffer;
  size(): number;
  map(options?: MapOptions): RawSourceMap | null;
  sourceAndMap(options?: MapOptions): SourceAndMapResult;
};
```

</>

  </CollapsePanel>
  <CollapsePanel
    className="collapse-code-panel"
    header="AssetInfo.ts"
    key="AssetInfo"
  >
    <>

```ts
type AssetInfo = {
  immutable: boolean;
  minimized: boolean;
  fullhash: Array<string>;
  chunkhash: Array<string>;
  contenthash: Array<string>;
  sourceFilename?: string;
  development: boolean;
  hotModuleReplacement: boolean;
  javascriptModule?: boolean;
  related: JsAssetInfoRelated;
  cssUnusedIdents?: Array<string>;
};
```

</>

  </CollapsePanel>
</Collapse>

### 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<{
  filename: 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}`);
  });
});
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Source.ts"
    key="Source"
  >
    <>

```ts
type Source = {
  source(): string | ArrayBuffer;
  buffer(): Buffer;
  size(): number;
  map(options?: MapOptions): RawSourceMap | null;
  sourceAndMap(options?: MapOptions): SourceAndMapResult;
};
```

</>

  </CollapsePanel>
  <CollapsePanel
    className="collapse-code-panel"
    header="AssetInfo.ts"
    key="AssetInfo"
  >
    <>

```ts
type AssetInfo = {
  immutable: boolean;
  minimized: boolean;
  fullhash: Array<string>;
  chunkhash: Array<string>;
  contenthash: Array<string>;
  sourceFilename?: string;
  development: boolean;
  hotModuleReplacement: boolean;
  javascriptModule?: boolean;
  related: JsAssetInfoRelated;
  cssUnusedIdents?: Array<string>;
};
```

</>

  </CollapsePanel>
</Collapse>

### getAsset

Get the asset object with the specified name.

```ts
getAsset(
  filename: string // filename of the getting asset
): Readonly<{
  filename: 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}`);
  });
});
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Source.ts"
    key="Source"
  >
    <>

```ts
type Source = {
  source(): string | ArrayBuffer;
  buffer(): Buffer;
  size(): number;
  map(options?: MapOptions): RawSourceMap | null;
  sourceAndMap(options?: MapOptions): SourceAndMapResult;
};
```

</>

  </CollapsePanel>
  <CollapsePanel
    className="collapse-code-panel"
    header="AssetInfo.ts"
    key="AssetInfo"
  >
    <>

```ts
type AssetInfo = {
  immutable: boolean;
  minimized: boolean;
  fullhash: Array<string>;
  chunkhash: Array<string>;
  contenthash: Array<string>;
  sourceFilename?: string;
  development: boolean;
  hotModuleReplacement: boolean;
  javascriptModule?: boolean;
  related: JsAssetInfoRelated;
  cssUnusedIdents?: Array<string>;
};
```

</>

  </CollapsePanel>
</Collapse>

### getPath

Generate path string based on the Filename template, see [Filename placeholders](/config/filename-placeholders) 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"
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Filename.ts"
    key="FileName"
  >
    <>

```ts
type Filename = string | (data: PathData, info: AssetInfo) => string;
```

</>

  </CollapsePanel>
  <CollapsePanel
    className="collapse-code-panel"
    header="PathData.ts"
    key="PathData"
  >
    <>

```ts
type PathData = {
  filename?: string;
  hash?: string;
  contentHash?: string;
  runtime?: string;
  url?: string;
  id?: string;
  chunk?: JsChunkPathData;
};
```

</>

  </CollapsePanel>
</Collapse>

### getPathWithInfo

Generate path string and asset info based on the Filename template, see [Filename placeholders](/config/filename-placeholders).

```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: {}
} */
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Filename.ts"
    key="FileName"
  >
    <>

```ts
type Filename = string | (data: PathData, info: AssetInfo) => string;
```

</>

  </CollapsePanel>
  <CollapsePanel
    className="collapse-code-panel"
    header="PathData.ts"
    key="PathData"
  >
    <>

```ts
type PathData = {
  filename?: string;
  hash?: string;
  contentHash?: string;
  runtime?: string;
  url?: string;
  id?: string;
  chunk?: JsChunkPathData;
};
```

</>

  </CollapsePanel>
  <CollapsePanel
    className="collapse-code-panel"
    header="AssetInfo.ts"
    key="AssetInfo"
  >
    <>

```ts
type AssetInfo = {
  immutable: boolean;
  minimized: boolean;
  fullhash: Array<string>;
  chunkhash: Array<string>;
  contenthash: Array<string>;
  sourceFilename?: string;
  development: boolean;
  hotModuleReplacement: boolean;
  javascriptModule?: boolean;
  related: JsAssetInfoRelated;
  cssUnusedIdents?: Array<string>;
};
```

</>

  </CollapsePanel>
</Collapse>

### 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}`);
});
```

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Stats.ts" key="Stats">
    <>

```ts
type Stats = {
  compilation: Compilation;
  hash: Readonly<string | null>;
  startTime?: number;
  endTime?: number;
  hasErrors(): bool;
  hasWarnings(): bool;
  toJson(opts?: StatsValue): StatsCompilation;
  toString(opts?: StatsValue): string;
};
```

</>

  </CollapsePanel>
</Collapse>

### 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) => {});
});
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compiler.ts"
    key="Compiler"
  >
    <>

```ts
type Compiler = {
  hooks: CompilerHooks;
  inputFileSystem: InputFileSystem | null;
  outputFileSystem: OutputFileSystem | null;
  watchFileSystem: WatchFileSystem | null;
  options: RspackOptionsNormalized;
  watching: Watching;

  getInfrastructureLogger(name: string | (() => string)): Logger;
  getCache(name: string): CacheFacade;
  watch(
    watchOptions: Watchpack.WatchOptions,
    handler: liteTapable.Callback<Error, Stats>,
  ): Watching;
  run(callback: liteTapable.Callback<Error, Stats>): void;
  runAsChild(
    callback: (
      err?: null | Error,
      entries?: Chunk[],
      compilation?: Compilation,
    ) => any,
  ): void;
  createChildCompiler(
    compilation: Compilation,
    compilerName: string,
    compilerIndex: number,
    outputOptions: OutputNormalized,
    plugins: RspackPluginInstance[],
  ): Compiler;
  compile(callback: liteTapable.Callback<Error, Compilation>): void;
  close(callback: (error?: Error | null) => void): void;
};
```

</>

  </CollapsePanel>
</Collapse>

### addRuntimeModule

<ApiMeta addedVersion="1.0.6" />

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()}.`);
    });
  });
});
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Module.ts"
    key="Module"
  >
    <>

```ts
type Module = {
  context?: string;
  resource?: string;
  request?: string;
  userRequest?: string;
  rawRequest?: string;
  factoryMeta?: JsFactoryMeta;
  buildInfo: Record<string, any>;
  buildMeta: Record<string, any>;
  originalSource(): {
    isRaw: boolean;
    isBuffer: boolean;
    source: Buffer;
    map?: Buffer;
  } | null;
  identifier(): string;
  nameForCondition(): string | null;
};
```

</>

  </CollapsePanel>
</Collapse>

### 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}`);
    }
  });
});
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Logger.ts"
    key="Logger"
  >
    <>

> See [Logger API](/api/javascript-api/logger) for more details

```ts
type Logger = {
  getChildLogger: (name: string | (() => string)) => Logger; // create a child logger
  error(...args: any[]): void; // display errors
  warn(...args: any[]): void; //  display warnings
  info(...args: any[]): void; // display important information
  log(...args: any[]): void; // display unimportant information
  debug(...args: string[]): void; // display debug information
  assert(assertion: any, ...args: any[]): void; // display errors if assertion failed
  trace(): void; // display a stack trace
  clear(): void; // clear all logs
  status(...args: any[]): void; // display status information
  group(...args: any[]): void; // start a logging group
  groupEnd(...args: any[]): void; // end a logging group
  groupCollapsed(...args: any[]): void; // group logs together
  profile(label: any): void; // start capturing a profile
  profileEnd(label: any): void; // end capturing a profile
  time(label: any): void; // start a timer
  timeLog(label: any): void; // not end the timer and record the time difference
  timeEnd(label: any): void; // end the timer and record the time difference
  timeAggregate(label: any): void; // aggregate capture the time difference
  timeAggregateEnd(label: any): void; // end the aggregate capturing
};
```

</>

  </CollapsePanel>
</Collapse>

### 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;
```

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Cache.ts" key="Cache">
    <>

> See [cache object](/api/javascript-api/cache) for more details.

```ts
type CacheFacade = {
  getChildCache(name: string): CacheFacade; // create a named child cache object
  getItemCache(identifier, etag): ItemCacheFacade; // create a cache object for an data item
  getLazyHashedEtag(obj: HashableObject): Etag; // create a lazy computed etag
  mergeEtags(a: Etag, b: Etag): Etag; // merge two etags
  get<T>( // async data getter, callback by function
    identifier: string,
    etag: Etag,
    callback: (err: Error, result: T) => void,
  ): void;
  getPromise<T>( // async data getter, callback by promise
    identifier: string,
    etag: Etag,
  ): Promise<T>;
  store<T>( // async data setter, callback by function
    identifier: string,
    etag: Etag,
    data: T,
    callback: (err: Error) => void,
  ): void;
  storePromise<T>( // async data setter, callback by promise
    identifier: string,
    etag: Etag,
    data: T,
  ): Promise<void>;
  provide<T>( // try to get the data, use function to compute if not exists, callback by function
    identifier: string,
    etag: Etag,
    computer: () => T | Promise<T>,
    callback: (err: Error, result: T) => void,
  ): void;
  providePromise<T>( // try to get the data, use function to compute if not exists, callback by function
    identifier: string,
    etag: Etag,
    computer: () => T | Promise<T>,
  ): Promise<T>;
};
```

</>

  </CollapsePanel>
</Collapse>

## Compilation properties

### options

**Type**: `RspackOptionsNormalized`

The normalized options used by this Compilation, see [Configure Rspack](/config/index) for details.

### compiler

**Type**: `Compiler`

Current [compiler object](/api/javascript-api/index).

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compiler.ts"
    key="Compiler"
  >
    <>

```ts
type Compiler = {
  hooks: CompilerHooks;
  inputFileSystem: InputFileSystem | null;
  outputFileSystem: OutputFileSystem | null;
  watchFileSystem: WatchFileSystem | null;
  options: RspackOptionsNormalized;
  watching: Watching;

  getInfrastructureLogger(name: string | (() => string)): Logger;
  getCache(name: string): CacheFacade;
  watch(
    watchOptions: Watchpack.WatchOptions,
    handler: liteTapable.Callback<Error, Stats>,
  ): Watching;
  run(callback: liteTapable.Callback<Error, Stats>): void;
  runAsChild(
    callback: (
      err?: null | Error,
      entries?: Chunk[],
      compilation?: Compilation,
    ) => any,
  ): void;
  createChildCompiler(
    compilation: Compilation,
    compilerName: string,
    compilerIndex: number,
    outputOptions: OutputNormalized,
    plugins: RspackPluginInstance[],
  ): Compiler;
  compile(callback: liteTapable.Callback<Error, Compilation>): void;
  close(callback: (error?: Error | null) => void): void;
};
```

</>

  </CollapsePanel>
</Collapse>

### hooks

The [Compilation hooks](/api/plugin-api/compilation-hooks).

### hash/fullhash

**Type**: `Readonly<string | null>`

The hash of this compilation.

### assets

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

The mapping from asset filenames and content sources.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Source.ts"
    key="Source"
  >
    <>

```ts
type Source = {
  source(): string | ArrayBuffer;
  buffer(): Buffer;
  size(): number;
  map(options?: MapOptions): RawSourceMap | null;
  sourceAndMap(options?: MapOptions): SourceAndMapResult;
};
```

</>

  </CollapsePanel>
</Collapse>

### chunkGroups

**Type**: `ReadonlyArray<ChunkGroup>`

The list of chunk group objects, with the structure as follows:

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="ChunkGroup.ts"
    key="ChunkGroup"
  >
    <>

```ts
type ChunkGroup = {
  name?: Readonly<string>; // name of this chunk group
  index?: Readonly<number>; // creating index of chunk group
  chunks: ReadonlyArray<Chunk>; // chunks in this chunk group
  origins: ReadonlyArray<{
    // where this chunk group is imported
    module?: Module;
    request?: string;
  }>;
  isInitial(): boolean; // whether this chunk group will be loaded on initial page load
  getFiles(): ReadonlyArray<string>; // the files contained this chunk group
  getParents(): ReadonlyArray<ChunkGroup>; // returns the parent chunk groups
};
```

</>

  </CollapsePanel>
</Collapse>

### entrypoints

**Type**: `ReadonlyMap<string, Entrypoint>`

The mapping from name to entrypoint, which is a special chunk group and include a runtime chunk.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Entrypoint.ts"
    key="entrypoint"
  >
    <>

```ts
type Entrypoint = {
  name?: Readonly<string>; // name of this chunk group
  index?: Readonly<number>; // creating index of chunk group
  chunks: ReadonlyArray<Chunk>; // chunks in this chunk group
  origins: ReadonlyArray<{
    // the origin request of this entrypoint
    module?: Module;
    request?: string;
  }>;
  isInitial(): boolean; // whether this chunk group will be loaded on initial page load
  getFiles(): ReadonlyArray<string>; // the files contained this chunk group
  getParents(): ReadonlyArray<ChunkGroup>; // returns the parent chunk groups
  getRuntimeChunk(): Readonly<Chunk | null>; // get the runtime chunk of this entrypoint (runtime chunk refers to a chunk that contains runtime code. Generally, the runtime chunk and the entrypoint chunk are the same chunk. Only when the runtime is split into a separate chunk via `dependOn` or `optimization.runtimeChunk` do they refer to different chunks)
  getEntrypointChunk(): Readonly<Chunk | null>; // get the entrypoint chunk of this entrypoint (entrypoint chunk refers to a chunk that contains entry modules)
};
```

</>

  </CollapsePanel>
</Collapse>

### namedChunkGroups

**Type**: `ReadonlyMap<string, Readonly<ChunkGroup>>`

The mapping from names to chunk groups.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="ChunkGroup.ts"
    key="ChunkGroup"
  >
    <>

```ts
type ChunkGroup = {
  name?: Readonly<string>; // name of this chunk group
  index?: Readonly<number>; // creating index of chunk group
  chunks: ReadonlyArray<Chunk>; // chunks in this chunk group
  origins: ReadonlyArray<{
    // where this chunk group is imported
    module?: Module;
    request?: string;
  }>;
  isInitial(): boolean; // whether this chunk group will be loaded on initial page load
  getFiles(): ReadonlyArray<string>; // the files contained this chunk group
  getParents(): ReadonlyArray<ChunkGroup>; // returns the parent chunk groups
};
```

</>

  </CollapsePanel>
</Collapse>

### modules

**Type:** `ReadonlySet<Module>`

List of all modules, with the structure as follows:

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Module.ts"
    key="Module"
  >
    <>

```ts
type Module = {
  context?: string;
  resource?: string;
  request?: string;
  userRequest?: string;
  rawRequest?: string;
  factoryMeta?: JsFactoryMeta;
  buildInfo: Record<string, any>;
  buildMeta: Record<string, any>;
  originalSource(): {
    isRaw: boolean;
    isBuffer: boolean;
    source: Buffer;
    map?: Buffer;
  } | null;
  identifier(): string;
  nameForCondition(): string | null;
};
```

</>

  </CollapsePanel>
</Collapse>

### builtModules

**Type:** `ReadonlySet<Module>`

List of built modules that were not be cached, with the structure as follows:

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Module.ts"
    key="Module"
  >
    <>

```ts
type Module = {
  context?: string;
  resource?: string;
  request?: string;
  userRequest?: string;
  rawRequest?: string;
  factoryMeta?: JsFactoryMeta;
  buildInfo: Record<string, any>;
  buildMeta: Record<string, any>;
  originalSource(): {
    isRaw: boolean;
    isBuffer: boolean;
    source: Buffer;
    map?: Buffer;
  } | null;
  identifier(): string;
  nameForCondition(): string | null;
};
```

</>

  </CollapsePanel>
</Collapse>

### chunks

**Type:** `ReadonlySet<Chunk>`

List of all chunks, with the structure as follows:

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Chunk.ts" key="Chunk">
    <>

```ts
type Chunk = {
  auxiliaryFiles: ReadonlySet<string>;
  canBeInitial(): boolean;
  chunkReason?: Readonly<string>;
  contentHash: Readonly<Record<string, string>>;
  cssFilenameTemplate?: Readonly<string>;
  filenameTemplate?: Readonly<string>;
  files: ReadonlySet<string>;
  getAllAsyncChunks(): Iterable<Chunk>;
  getAllInitialChunks(): Iterable<Chunk>;
  getAllReferencedChunks(): Iterable<Chunk>;
  getEntryOptions(): EntryOptions | undefined;
  get groupsIterable(): Iterable<ChunkGroup>;
  hash?: Readonly<string>;
  hasRuntime(): boolean;
  id?: Readonly<string>;
  idNameHints: ReadonlyArray<string>;
  ids: ReadonlyArray<string>;
  isOnlyInitial(): boolean;
  name?: Readonly<string>;
  renderedHash?: Readonly<string>;
  runtime: ReadonlySet<string>;
};
```

</>

  </CollapsePanel>
</Collapse>

### namedChunks

**Type:** `ReadonlyMap<string, Readonly<Chunk>>`

The mapping from names to chunks.

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Chunk.ts" key="Chunk">
    <>

```ts
type Chunk = {
  auxiliaryFiles: ReadonlySet<string>;
  canBeInitial(): boolean;
  chunkReason?: Readonly<string>;
  contentHash: Readonly<Record<string, string>>;
  cssFilenameTemplate?: Readonly<string>;
  filenameTemplate?: Readonly<string>;
  files: ReadonlySet<string>;
  getAllAsyncChunks(): Iterable<Chunk>;
  getAllInitialChunks(): Iterable<Chunk>;
  getAllReferencedChunks(): Iterable<Chunk>;
  getEntryOptions(): EntryOptions | undefined;
  get groupsIterable(): Iterable<ChunkGroup>;
  hash?: Readonly<string>;
  hasRuntime(): boolean;
  id?: Readonly<string>;
  idNameHints: ReadonlyArray<string>;
  ids: ReadonlyArray<string>;
  isOnlyInitial(): boolean;
  name?: Readonly<string>;
  renderedHash?: Readonly<string>;
  runtime: ReadonlySet<string>;
};
```

</>

  </CollapsePanel>
</Collapse>

### fileDependencies

**Type:** `CompilationDependencies`

List of files this compilation depends on.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="CompilationDependencies.ts"
    key="CompilationDependencies"
  >
    <>

```ts
type CompilationDependencies = {
  has(dep: string): boolean;
  add(dep: string): void;
  addAll(deps: Iterable<string>): void;
};
```

</>

  </CollapsePanel>
</Collapse>

### contextDependencies

**Type:** `CompilationDependencies`

List of directories this compilation depends on.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="CompilationDependencies.ts"
    key="CompilationDependencies"
  >
    <>

```ts
type CompilationDependencies = {
  has(dep: string): boolean;
  add(dep: string): void;
  addAll(deps: Iterable<string>): void;
};
```

</>

  </CollapsePanel>
</Collapse>

### missingDependencies

**Type:** `CompilationDependencies`

List of not existing files this compilation depends on.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="CompilationDependencies.ts"
    key="CompilationDependencies"
  >
    <>

```ts
type CompilationDependencies = {
  has(dep: string): boolean;
  add(dep: string): void;
  addAll(deps: Iterable<string>): void;
};
```

</>

  </CollapsePanel>
</Collapse>

### buildDependencies

**Type:** `CompilationDependencies`

List of build dependencies this compilation depends on.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="CompilationDependencies.ts"
    key="CompilationDependencies"
  >
    <>

```ts
type CompilationDependencies = {
  has(dep: string): boolean;
  add(dep: string): void;
  addAll(deps: Iterable<string>): void;
};
```

</>

  </CollapsePanel>
</Collapse>

### errors

**Type:** `RspackError[]`

List of emitted errors during this compilation, with the structure as follows:

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="RspackError.ts"
    key="RspackError"
  >
    <>

```ts
type RspackError = {
  name: string;
  message: string;
  moduleIdentifier?: string;
  file?: string;
  stack?: string;
  hideStack?: boolean;
};
```

</>

  </CollapsePanel>
</Collapse>

### warnings

**Type:** `RspackError[]`

List of emitted warnings during this compilation.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="RspackError.ts"
    key="RspackError"
  >
    <>

```ts
type RspackError = {
  name: string;
  message: string;
  moduleIdentifier?: string;
  file?: string;
  stack?: string;
  hideStack?: boolean;
};
```

</>

  </CollapsePanel>
</Collapse>



---
url: /api/javascript-api/stats.md
---

import Columns from '@components/Columns';
import { Collapse, CollapsePanel } from '@components/Collapse';

import { Badge } from '@theme';

# Stats

The `stats` object that is passed as a second argument of the [`rspack()`](/api/javascript-api/index#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) 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#getstats) or `new Stats(compilation)`.

## Stats methods

### hasErrors

Can be used to check if there were errors while compiling.

```ts
hasErrors(): boolean;
```

### hasWarnings

Can be used to check if there were warnings while compiling.

```ts
hasWarnings(): boolean;
```

### toJson

Return the compilation information in the form of a [Stats JSON](/api/javascript-api/stats-json) object. The [Stats configuration](/config/stats) can be a string (preset value) or an object for granular control:

```js
stats.toJson('minimal');
```

```js
stats.toJson({
  assets: false,
  hash: true,
});
```

### toString

Return the compilation information in the form of a formatted string (similar to the output of [CLI](/api/cli)).

```ts
toJson(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.

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Stats.ts" key="stats">
    <>

> See [compilation object](/api/javascript-api/compilation) for more details.

```ts
type Compilation = {
  emitAsset(): void; // add a new asset
  updateAsset(): void; // update content of the asset
  renameAsset(): void; // rename the asset
  deleteAsset(): void; // delete an existing asset
  getAssets(): Asset[]; // get all assets
  getAsset(): Asset; // get asset from name
  getPath(): string; // generate path from template
  getPathWithInfo(): PathWithInfo; // generate path and asset info from template
  getStats(): Stats; // get stats object
  createChildCompiler(): Compiler; // create a child compiler
  rebuildModule(): void; // run module.build again
  getLogger(): Logger; // get compilation related logger object
  getCache(): CacheFacade; // get compilation related cache object
  options: RspackOptionsNormalized; // the compiler options
  compiler: Compiler; // current compiler
  hooks: CompilationHooks; // hooks of compilation
  hash: string | null; // hash of this compilation
  fullhash: string | null; // same as 'hash'
  assets: Record<string, Source>; // mapping from filename to asset content
  chunkGroups: ChunkGroup[]; // list of chunk groups
  entrypoints: Map<string, Entrypoint>; // mapping from name to entrypoint
  namedChunkGroups: Map<string, ChunkGroup>; // mapping named chunk groups
  modules: Set<Module>; // set of all modules
  chunks: Set<Chunk>; // set of all chunks
  namedChunks: Map<string, Chunk>; // mapping of named chunks
  fileDependencies: CompilationDependencies; // dependent files
  contextDependencies: CompilationDependencies; // dependent directories
  missingDependencies: CompilationDependencies; // dependent missing files
  buildDependencies: CompilationDependencies; // dependent build files
  errors: RspackError[]; // errors during compilation
  warnings: RspackError[]; // warnings during compilation
};
```

</>

  </CollapsePanel>
</Collapse>

### hash

**Type:** `string`

Get the hash of this compilation, same as [`Compilation.hash`](/api/javascript-api/compilation#hashfullhash).

## MultiStats

When using `MultiCompiler` to execute multiple compilation tasks, their compilation stats will be packaged as a `MultiStats` object, which provides similar methods and properties as `Stats`.

### hash

<Badge text="ReadOnly" type="info" />

**Type:** `string`

Get the unique hash after merging the hashes of all compilations.

### hasErrors

Used to check if there are errors during the compilation period, and only if there are no errors in all compilations will it return `false`.

```ts
hasErrors(): boolean;
```

### hasWarnings

Used to check if there are warnings during the compilation period, and only if there are no warnings in all compilations will it return `false`.

```ts
hasWarnings(): boolean;
```

### toJson

According to the [stats configuration](/config/stats), generate all the [stats json](/api/javascript-api/stats-json) objects, wrap them in the `children` field, and also summarize the `errors` and `warnings`.

```ts
toJson(options?: StatsValue): {
  hash: string;
  errorsCount: number;
  warningsCount: number;
  errors: StatsError[];
  warnings: StatsError[];
  children: StatsCompilation[];
};
```

### toString

Concatenate the stats output strings of all compilations according to the [stats configuration](/config/stats).

```ts
toString(options?: StatsValue): string;
```

## 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#statsfactory). Or create a new one by `new StatsFactory()`.

### Hooks

See [StatsFactory hooks](/api/plugin-api/stats-hooks#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#statsprinter). Or create a new one by `new StatsPrinter()`.

### Hooks

See [StatsPrinter hooks](/api/plugin-api/stats-hooks#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
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/api/stats/" />

# 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 top-level structure of the output object is 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;
  // 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[];
  // 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;
  // List of warning objects, refer to the "Error/Warning Object"
  warnings?: StatsWarnings[];
  // Number of warnings
  warningsCount?: number;
};
```

## Asset object

Each asset object represents an output file emitted from the compilation, and its structure is as follows:

```ts
type StatsAsset = {
  // The `output` filename
  name: string;
  // The size of the file in bytes
  size: number;
  // Indicates whether or not the asset made it to the `output` directory
  emitted: boolean;
  // The chunk IDs this asset related
  chunks: Array<string | undefined | null>;
  // The chunks this asset related
  chunkNames: Array<string>;
  // The chunk idHints this asset related
  chunkIdHints: Array<string>;
  // The chunk IDs this auxiliary asset related
  auxiliaryChunks: Array<string | undefined | null>;
  // The chunks this auxiliary asset related
  auxiliaryChunkNames: Array<string>;
  // The chunk idHints this auxiliary asset related
  auxiliaryChunkIdHints: Array<string>;
  info: {
    // whether the asset is minimized
    minimized: boolean;
    // A flag telling whether the asset is only used for development and doesn't count towards user-facing assets
    development: boolean;
    // A flag telling whether the asset ships data for updating an existing application (HMR)
    hotModuleReplacement: boolean;
    // sourceFilename when asset was created from a source file (potentially transformed)
    sourceFilename?: string;
    // true, if the asset can be long term cached forever (contains a hash)
    immutable: boolean;
    // true, when asset is javascript and an ESM
    javascriptModule?: boolean;
    // the value(s) of the chunk hash used for this asset
    chunkHash: Array<string>;
    // the value(s) of the content hash used for this asset
    contentHash: Array<string>;
  };
  // related assets, like source-map
  related: StatsAsset[];
  // whether the asset exceeds performance.maxAssetSize
  isOverSizeLimit?: boolean;
};
```

## Chunk object

Each chunk object represents a group of modules known as a chunk, and its structure is as follows:

```ts
type StatsChunk = {
  // The list of product files contained in the chunk
  files: Array<string>;
  // The list of attached product files contained in the chunk
  auxiliaryFiles: Array<string>;
  // Chunk ID
  id?: string;
  // List of chunk names contained within this chunk
  names: Array<string>;
  // The runtime used by the chunk
  runtime: Array<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 the rspack runtime
  entry: boolean;
  // Whether the chunk is loaded on initial page load or on demand
  initial: boolean;
  // Whether the chunk went through Code Generation
  rendered: boolean;

  // Parent chunk IDs
  parents?: Array<string>;
  // Children chunk IDs
  children?: Array<string>;
  // Sibling chunk IDs
  siblings?: Array<string>;

  // Chunk create reason when splitting chunks (need to enable `optimization.splitChunks`).
  reason?: string;
  // List of idHints of the cache groups hit when splitting chunks (need to enable `optimization.splitChunks`).
  idHints: Array<string>;

  // List of origins describing how the given chunk originated
  origins: Array<{
    // Path to the module
    module: string;
    // ID of the module
    moduleId: string;
    // The identifier of the module
    moduleIdentifier: string;
    // Relative path to the module
    moduleName: string;
    // Lines of code that generated this chunk
    loc: string;
    // The dependency request in the module
    request: string;
  }>;

  // List of modules contained in the chunk, for details, refer to the "Module Object"
  modules?: Array<StatsModule>;
};
```

## Module object

Each module object represents a module in the dependency graph, and its structure is as follows:

```ts
type StatsModule = {
  // Module ID
  id?: string;
  // Module source type
  moduleType: string;
  // A unique identifier used internally
  identifier: string;
  // Path to the actual file
  name: string;
  // Estimated size of the module in bytes
  size: number;
  // Total size of module group by the output type (in bytes)
  sizes: Record<string, number>;

  // Whether the module went through loaders and parsing
  built: boolean;
  // Whether the module went through code generation
  codeGenerated: boolean;
  // Whether the module is run during the compilation (you can see it while using css-extract)
  buildTimeExecuted: boolean;
  // Whether the module is cached
  cached: boolean;
  // Whether the module can be cached
  cacheable: boolean;
  // Whether the module is optional, and if it is optional, only a warning will be issued when the module is not found
  optional: boolean;
  // Whether the module is dependent by other modules
  dependent?: boolean;

  // List of reasons why the module is introduced, similar to the structure of chunk.origins
  reasons?: Array<JsStatsModuleReason>;
  // Unique identifier of the parent module
  issuer?: string;
  // Parent module ID
  issuerId?: string;
  // Path to the actual file of parent module
  issuerName?: string;
  // Reference path from the entry to the current module
  issuerPath: Array<JsStatsModuleIssuer>;
  // Absolute path used by the module for conditional matching (usually the resource path)
  nameForCondition?: string;
  // The top-down index of the module in the ChunkGroup
  preOrderIndex?: number;
  // The bottom-up index of the module in the ChunkGroup
  postOrderIndex?: number;
  // The level in module graph
  depth?: number;
  // Whether the module is not included by any chunk
  orphan: boolean;
  // List of IDs of chunks that contain the module
  chunks: Array<string | undefined | null>;
  // List of assets generated by the module
  assets?: Array<string>;

  // Whether the module compiles failed
  failed: boolean;
  // Number of errors
  errors: number;
  // Number of warnings
  warnings: number;

  // Used module exports, true indicates that all are used, string[] indicates that some fields are used (need to enable `optimization.usedExports`)
  usedExports?: null | string[] | boolean;
  // List of fields exported by the module (need to enable `optimization.providedExports`)
  providedExports?: null | string[];
  // Optimization bailout reasons (need to enable `optimization.concatenateModules`)
  optimizationBailout?: null | string[];

  // If current module is generated by scope hoisting, this is the list of the original modules (need to enable `optimization.concatenateModules`)
  modules?: Array<JsStatsModule>;

  // Source code
  source?: string | Buffer;

  // The compilation time statistics for each phase (in milliseconds, need to enable `profile`)
  profile?: {
    // Finding the module
    resolving: number;
    // Compiling the module
    building: number;
  };
};
```

## 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 entry
  name: string;
  // List of IDs of the chunks included
  chunks: Array<string | undefined | null>;
  // Assets generated by the chunk group
  assets: Array<{
    // File name
    name: string;
    // File size
    size: 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?: Array<StatsChunkGroup>;
    // prefetch children chunk groups
    prefetch?: Array<StatsChunkGroup>;
  };
  // Assets of ordered children chunk groups, order by preload/prefetch
  childAssets?: {
    // preload assets
    preload?: Array<string>;
    // prefetch assets
    prefetch?: Array<string>;
  };
  // Whether the assets of this entrypoint exceeds performance.maxEntrypointSize
  isOverSizeLimit?: boolean;
};
```

## 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;
  // A custom filename associated with this error/warning.
  file?: string;
  // Detail info of the error/warning
  details?: string;
  // 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;
  // ID of the module where the error/warning occurs
  moduleId?: string;
  // Module import trace from entry module
  moduleTrace: Array<{
    // parent module
    origin: {
      identifier: string;
      name?: string;
      id?: string;
    };
    // imported module
    module: {
      identifier: string;
      name?: string;
      id?: string;
    };
  }>;

  // 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;
};
```



---
url: /api/javascript-api/logger.md
---

import WebpackLicense from '@components/WebpackLicense';
import { Collapse, CollapsePanel } from '@components/Collapse';

import Columns from '@components/Columns';

<WebpackLicense from="https://webpack.js.org/api/logging/" />

# Logger

Logging output is an additional way to display messages to the end users.

Rspack logger is available to [loaders](/guide/features/loader) and [plugins](/guide/features/plugin). Emitting as part of the [Stats](/api/javascript-api/stats-json) and configured by the user in [rspack configuration](/config/).

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#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=MyLoader.js
module.exports = 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`:

<Columns>
```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
```

</Columns>

While using `compiler.getInfrastructureLogger`, the output level can be controlled by `infrastructureLogging.level` and `infrastructureLogging.debug`:

<Columns>
```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
```

</Columns>

### assert

Display errors when assertion is false.

- **Level:** `error`
- **Type:**: `assert(assertion: any, ...args: any[]): void;`

<Columns>
```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
```

</Columns>

### status

Display progress status information, use `console.status` if exists, otherwise fallback to `console.info.

- **Level:** `info`
- **Type:** `status(...args: any[]): void`

<Columns>
```js
logger.status("status info");
```

```js title=Output
[TEST] status info
```

</Columns>

### trace

Display a stack trace, only available while using compilation logger and also need to enable the `stats.loggingTrace`.

- **Level:** `debug`
- **Type:** `trace(): void`

<Columns>
```js
logger.trace();
```

```js title=Output
DEBUG LOG from TEST
    Trace
|     at Object.fn
|     at SyncHook.callAsyncStageRange
```

</Columns>

### clear

Clean all logs, just like `console.clear()`.

- **Level:** `log`
- **Type:** `clear(): void;`

<Columns>
```js
logger.debug("not displayed");
logger.clear();
logger.debug("will displayed");
```

```js title=Output
[TEST] will displayed
```

</Columns>

### 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'`.

<Columns>
```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
```

</Columns>

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

<Columns>
```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
````

</Columns>

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

<Columns>
```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
```

</Columns>



---
url: /api/javascript-api/cache.md
---

import { Collapse, CollapsePanel } from '@components/Collapse';

import Columns from '@components/Columns';

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

<Columns>

```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' ]
```

</Columns>

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

<Columns>
```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
```

</Columns>

### 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>;
};
```

<Columns>

```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
```

</Columns>

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

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

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

import { ApiMeta } from '../../../../components/ApiMeta';

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

## Basic example

The following example demonstrates the basic usage of `@rspack/browser`. Except for the additional APIs used to read and write project files and outputs, other APIs are consistent with the [JavaScript API](/api/javascript-api/) of `@rspack/core`.

```ts
import { rspack, builtinMemFs } from '@rspack/browser';

// Write files to memfs
builtinMemFs.volume.fromJSON({
  // ...project files
});

rspack({}, (err, stats) => {
  if (err || stats.hasErrors()) {
    // ...
  }
  // Get output from memfs after bundling
  const files = builtinMemFs.volume.toJSON();
});
```

## 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#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#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#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#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#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) or the template functions of [HtmlRspackPlugin](/plugins/rspack/html-rspack-plugin#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`

<ApiMeta addedVersion="1.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/webpack/module-federation-plugin). 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#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"
new rspack.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/webpack/module-federation-plugin#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/webpack/module-federation-plugin#implementation) option is not supported.



---
url: /api/loader-api/index.md
---

# 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) to get started.

If you need to use an existing loader, you can refer to [Features - Loader](/guide/features/loader) to learn how to use it.

## Loader API

Loader API includes:

- [Loader context](/api/loader-api/context): Represents the properties that are available inside of a loader assigned to the `this` property.
- [Inline loader](/api/loader-api/inline): Specify a loader in an `import` statement.
- [Inline matchResource](/api/loader-api/inline-match-resource): Allows you to dynamically change the matching rules when loading resources.



---
url: /api/loader-api/writing-loaders.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/api/loaders/#examples" />

# 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#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#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"
  // 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#thissourcemap) to determine whether source map generation is required.
- Use [this.callback](/api/loader-api/context#thiscallback) or [this.async](/api/loader-api/context#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):

```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);
  }
}
```



---
url: /api/loader-api/context.md
---

import { ApiMeta, Stability } from '@components/ApiMeta';
import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/api/loaders/#the-loader-context" />

# Loader context

The loader context represents the properties that are available inside of a loader assigned to the `this` property.

## 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.js"
const path = require('node:path');

module.exports = 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.js"
const path = require('node:path');

module.exports = 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.js"
const path = require('node:path');

module.exports = 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#async-loader) for more details.

## this.cacheable()

- **Type:**

```ts
function cacheable(flag: boolean = true): void;
```

A function that sets the cacheable flag.

By default, the processing results of the loader are marked as cacheable. Calling this method and passing `false` turns off the loader's ability to cache processing results.

```js title="loader.js"
module.exports = function loader(source) {
  this.cacheable(false);
  return source;
};
```

## this.callback()

- **Type:**

```ts
function callback(
  err: Error | null,
  content: string | Buffer,
  sourceMap?: Rspack.RawSourceMap,
  meta?: any,
): void;
```

A function that can be called synchronously or asynchronously in order to return multiple results. The expected arguments are:

1. The first parameter must be `Error` or `null`, which marks the current module as a compilation failure.
2. The second argument is a `string` or `Buffer`, which indicates the contents of the file after the module has been processed by the loader.
3. The third parameter is a source map that can be processed by the loader.
4. The fourth parameter is ignored by Rspack and can be anything (e.g. some metadata).

> See [Sync loader](/api/loader-api/writing-loaders#sync-loader) for more details.

:::warning
In case this function is called, you should return `undefined` to avoid ambiguous loader results.

The value passed to `this.callback` will be passed to the next loader in the chain.
The `sourceMap` and `meta` parameters are optional. If they are not passed, the next loader will not receive them.
:::

## this.clearDependencies()

- **Type:**

```ts
function clearDependencies(): void;
```

Removes all dependencies of the loader 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.js"
module.exports = function loader(source) {
  console.log(this.context); // '/project/src/components'
  return source;
};
```

If the module being processed is not from the file system, such as a virtual module, then the value of `this.context` is `null`.

## this.loaderIndex

- **Type:** `number`

The index in the loaders array of the current loader.

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

<ApiMeta stability={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 a diagnostic message (error or warning log). Supports the display of module paths, source code snippets and line/column numbers.

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

- Basic example:

When only `message` and `severity` are provided, only the basic module error information will be printed.

```js title="loader.js"
/** @type {import("@rspack/core").LoaderDefinition} */
module.exports = 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.js!)
  × ModuleError: `React` is not defined

WARNING in (./loader.js!)
  ⚠ ModuleWarning: `React` is not defined
```

- Printing code snippet:

```js title="loader.js"
/** @type {import("@rspack/core").LoaderDefinition} */
module.exports = 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.js"
module.exports = 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.js"
module.exports = 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.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.js',
          options: {
            foo: 'bar',
          },
        },
      },
    ],
  },
};
```

In `my-loader.js` get the options passed in:

```js title="my-loader.js"
module.exports = function myLoader(source) {
  const options = this.getOptions();
  console.log(options); // { foo: 'bar' }
  return source;
};
```

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 [scheme-utils](https://github.com/webpack/scheme-utils) or other schema validation libraries.
:::

## this.getResolve()

- **Type:**

```ts
function getResolve(options: ResolveOptions): resolve;
```

Create a resolver like `this.resolve`.

## this.hot

- **Type:** `boolean`

Whether HMR is enabled.

```js title="loader.js"
module.exports = 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.js"
const path = require('node:path');

module.exports = 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.js"
const path = require('node:path');

module.exports = 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 `?`.

## this.request

- **Type:** `string`

The module specifier string after being resolved.

For example, if a `resource.js` is processed by `loader1.js` and `loader2.js`, the value of `this.request` will be `/path/to/loader1.js!/path/to/loader2.js!/path/to/resource.js`.

## this.resolve()

- **Type:**

```ts
function resolve(
  context: string,
  request: string,
  callback: (err: Error | null, result: string) => 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` is a callback function that gives the resolved path.

## this.mode

- **Type:** `Mode`

The value of [`mode`](/config/mode) is read when Rspack is run.

The possible values are: `'production'`, `'development'`, `'none'`

```js title="loader.js"
module.exports = function loader(source) {
  console.log(this.mode); // 'production' or other values
  return source;
};
```

## this.target

- **Type:** `Target`

The current compilation target. Passed from [`target`](/config/target) configuration options.

```js title="loader.js"
module.exports = function loader(source) {
  console.log(this.target); // 'web' or other values
  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.js"
module.exports = 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.js"
module.exports = 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 `'/abc/resource.js?query#hash'` in `'/abc/resource.js'`.

```js title="loader.js"
module.exports = 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.js"
module.exports = 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.js"
module.exports = 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).

```js title="loader.js"
module.exports = 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#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) object of Rspack.

### this.\_compilation

- **Type:** `Compilation`

Access to the current [Compilation](/api/javascript-api/compilation) object of Rspack.



---
url: /api/loader-api/inline.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/concepts/loaders/#inline" />

# 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"}`.



---
url: /api/loader-api/inline-match-resource.md
---

import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.js.org/api/loaders/#inline-matchresource" />

# 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];
};
```



---
url: /api/plugin-api/index.md
---

# Overview

## Plugin hooks

Rspack plugin hooks are similar to the webpack plugin, mainly including the following categories:

- [Compiler hooks](/api/plugin-api/compiler-hooks): Intervene at various stages of the entire build process
- [Compilation hooks](/api/plugin-api/compilation-hooks): Intervene at various stages of a single build
- [RuntimePlugin hooks](/api/plugin-api/runtime-plugin-hooks): Intervene in the generation of runtime code
- [NormalModuleFactory hooks](/api/plugin-api/normal-module-factory-hooks): Intervene at various stages of the module creation process
- [Stats hooks](/api/plugin-api/stats-hooks): 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
---

import Mermaid from '@components/Mermaid';



import { Collapse, CollapsePanel } from '@components/Collapse';
import Columns from '@components/Columns';
import { NoSSR } from '@rspress/core/runtime';

# 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) for more information about the Compiler object.
:::

## Overview

<NoSSR>

<Columns>

<div>

<Mermaid title="rspack()" style={{width: '20rem'}}>
{`
flowchart TD
  CallRspack("rspack()") --> CreateCompiler("new Compiler()")
  CreateCompiler --> ApplyNodeEnvPlugin(Apply NodeEnvironmentPlugin)
  ApplyNodeEnvPlugin --> ApplyDefaultOptions(Apply default options)
  ApplyDefaultOptions --> ApplyCustomPlugins(Apply custom plugins)
  ApplyCustomPlugins --> HookEnvironment(<a href="#environment">hooks.environment</a>)
  HookEnvironment --> HookAfterEnvironment(<a href="#afterenvironment">hooks.afterEnvironment</a>)
  HookAfterEnvironment --> ApplyRspackPlugins(Apply internal plugins)
  ApplyRspackPlugins <--> HookEntryOptions(<a href="#entryoption">hooks.entryOption</a>)
  ApplyRspackPlugins --> HookAfterPlugins(<a href="#afterplugins">hooks.afterPlugins</a>)
  HookAfterPlugins --> ResolveOptions(Generate resolve options)
  ResolveOptions --> HookAfterResolvers(<a href="#afterresolvers">hooks.afterResolvers</a>)
  HookAfterResolvers --> HookInitialize(<a href="#initialize">hooks.initialize</a>)
  HookInitialize --> compiler("return compiler")

class CallRspack flow-start
class compiler flow-end
class CreateCompiler,ApplyNodeEnvPlugin,ApplyDefaultOptions,ApplyCustomPlugins,ApplyRspackPlugins,ResolveOptions flow-process
class HookEnvironment,HookAfterEnvironment,HookEntryOptions,HookAfterPlugins,HookAfterResolvers,HookInitialize flow-hook
`}

</Mermaid>

<br />

<Mermaid title="compiler.compile()">

{`
flowchart TD
Compile("compiler.compile(callback)") --> CompilationParams("Create module factories")
CompilationParams --> HookNormalModuleFactory(hooks.normalModuleFactory)
CompilationParams --> HookContextModuleFactory(hooks.contextModuleFactory)
CompilationParams --> HookBeforeCompile(<a href="#beforecompile">hooks.beforeCompile</a>)
HookBeforeCompile --> HookCompile(<a href="#compile">hooks.compile</a>)
HookCompile --> Compilation("new Compilation()")
Compilation --> HookThisCompilation(<a href="#thiscompilation">hooks.thisCompilation</a>)
HookThisCompilation --> HookCompilation(<a href="#compilation">hooks.compilation</a>)
HookCompilation --> HookMake(<a href="#make">hooks.make</a>)
HookMake --> CreateModuleGraph(Create module graph)
CreateModuleGraph <--> RunLoaders(Run loaders on modules)
CreateModuleGraph --> HookFinishMake(<a href="#finishmake">hooks.finishMake</a>)
HookFinishMake --> CompilationFinish("compilation.finish()")
CompilationFinish --> CompilationSeal("compilation.seal()")
CompilationSeal --> HookAfterCompile(<a href="#aftercompile">hooks.afterCompile</a>)
HookAfterCompile --> Callback("callback()")

class Compile flow-start
class Callback,CloseCallback flow-end
class CompilationParams,Compilation,CreateModuleGraph,RunLoaders,CompilationFinish,CompilationSeal flow-process
class HookBeforeCompile,HookCompile,HookThisCompilation,HookCompilation,HookMake,HookFinishMake,HookAfterCompile flow-hook
class HookNormalModuleFactory,HookContextModuleFactory flow-hook-non-support
`}

</Mermaid>

</div>

<Mermaid title="compiler.watch/run/close()">

{`
flowchart TD
WatchCompiler("compiler.watch(options, callback)") --> CreateWatching("new Watching()")
RunCompiler("compiler.run(callback)") --> HookBeforeRun(<a href="#beforerun">hooks.beforeRun</a>)
HookBeforeRun --> HookRun(<a href="#run">hooks.run</a>)
HookRun --> HookReadRecords(hooks.readRecords)
CreateWatching --> HookReadRecords
HookReadRecords --> Compile("compiler.compile()")
HookWatchRun --> Compile
HookReadRecords --> HookWatchRun(<a href="#watchrun">hooks.watchRun</a>)
Compile --> HookShouldEmit{<a href="#shouldemit">hooks.shouldEmit</a>}
HookShouldEmit --> |true| HookEmit(<a href="#emit">hooks.emit</a>)
HookShouldEmit --> |false| HookDone(<a href="#done">hooks.done</a>)
HookEmit --> EmitAssets(Emit asset files)
EmitAssets <--> HookAssetEmitted(hooks.assetEmitted)
EmitAssets --> HookAfterEmit(<a href="#afteremit">hooks.afterEmit</a>)
HookAfterEmit --> HookNeedAdditionalPass{hooks.needAdditionalPass}
HookNeedAdditionalPass --> |true| HookAdditionalDone(hooks.done)
HookAdditionalDone --> HookAdditionPass(hooks.additionalPass)
HookAdditionPass --> Compile
HookEmitRecords --> HookDone
HookDone --> HookFailed(<a href="#failed">hooks.failed</a>)
HookFailed --> Callback("callback(err, stats)")
Callback --> WatchingWatch("watching.watch()")
WatchingWatch --> HookAfterDone(<a href="#afterdone">hooks.afterDone</a>)
WatchingWatch --> CollectFileChanges("Collect file changes")
CollectFileChanges --> HookReadRecords
Callback --> HookAfterDone

HookAfterDone -.-> CloseCompile("compiler.close(callback)")
CloseCompile --> WatchingClose("watching.close()")
WatchingClose --> HookWatchClose(<a href="#watchclose">hooks.watchClose</a>)
HookWatchClose --> CloseCallback("callback()")
CloseCallback --> HookShutdown(<a href="#shutdown">hooks.shutdown</a>)

class RunCompiler,WatchCompiler flow-start
class Callback flow-end
class Compile,EmitAssets,CollectFileChanges,CreateWatching,WatchingWatch flow-process
class HookBeforeRun,HookRun,HookShouldEmit,HookEmit,HookAfterEmit,HookDone,HookFailed,HookAfterDone,HookWatchRun flow-hook
class HookReadRecords,HookAssetEmitted,HookNeedAdditionalPass,HookAdditionPass,HookAdditionalDone,HookEmitRecords flow-hook-non-support

class CloseCompile flow-start
class CloseCallback flow-end
class WatchingClose flow-process
class HookWatchClose,HookShutdown flow-hook
`}

</Mermaid>

</Columns>

</NoSSR>

## `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) configuration from Rspack options has been processed.

- **Type:** `SyncBailHook<[string, EntryNormalized]>`
- **Arguments:**
  - `string`: same with [`context`](/config/context)
  - `EntryNormalized`: normalized [`entry`](/config/entry)

## `afterPlugins`

Called after setting up initial set of internal plugins.

- **Type:** `SyncHook<[Compiler]>`
- **Arguments:**
  - `Compiler`: current compiler instance

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compiler.ts"
    key="Compiler"
  >
    <>

```ts
type Compiler = {
  hooks: CompilerHooks;
  inputFileSystem: InputFileSystem | null;
  outputFileSystem: OutputFileSystem | null;
  watchFileSystem: WatchFileSystem | null;
  options: RspackOptionsNormalized;
  watching: Watching;

  getInfrastructureLogger(name: string | (() => string)): Logger;
  getCache(name: string): CacheFacade;
  watch(
    watchOptions: Watchpack.WatchOptions,
    handler: liteTapable.Callback<Error, Stats>,
  ): Watching;
  run(callback: liteTapable.Callback<Error, Stats>): void;
  runAsChild(
    callback: (
      err?: null | Error,
      entries?: Chunk[],
      compilation?: Compilation,
    ) => any,
  ): void;
  createChildCompiler(
    compilation: Compilation,
    compilerName: string,
    compilerIndex: number,
    outputOptions: OutputNormalized,
    plugins: RspackPluginInstance[],
  ): Compiler;
  compile(callback: liteTapable.Callback<Error, Compilation>): void;
  close(callback: (error?: Error | null) => void): void;
};
```

</>

  </CollapsePanel>
</Collapse>

## `afterResolvers`

Triggered after resolver setup is complete.

- **Type:** `SyncHook<[Compiler]>`
- **Arguments:**
  - `Compiler`: current compiler instance

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compiler.ts"
    key="Compiler"
  >
    <>

```ts
type Compiler = {
  hooks: CompilerHooks;
  inputFileSystem: InputFileSystem | null;
  outputFileSystem: OutputFileSystem | null;
  watchFileSystem: WatchFileSystem | null;
  options: RspackOptionsNormalized;
  watching: Watching;

  getInfrastructureLogger(name: string | (() => string)): Logger;
  getCache(name: string): CacheFacade;
  watch(
    watchOptions: Watchpack.WatchOptions,
    handler: liteTapable.Callback<Error, Stats>,
  ): Watching;
  run(callback: liteTapable.Callback<Error, Stats>): void;
  runAsChild(
    callback: (
      err?: null | Error,
      entries?: Chunk[],
      compilation?: Compilation,
    ) => any,
  ): void;
  createChildCompiler(
    compilation: Compilation,
    compilerName: string,
    compilerIndex: number,
    outputOptions: OutputNormalized,
    plugins: RspackPluginInstance[],
  ): Compiler;
  compile(callback: liteTapable.Callback<Error, Compilation>): void;
  close(callback: (error?: Error | null) => void): void;
};
```

</>

  </CollapsePanel>
</Collapse>

## `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#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

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compiler.ts"
    key="Compiler"
  >
    <>

```ts
type Compiler = {
  hooks: CompilerHooks;
  inputFileSystem: InputFileSystem | null;
  outputFileSystem: OutputFileSystem | null;
  watchFileSystem: WatchFileSystem | null;
  options: RspackOptionsNormalized;
  watching: Watching;

  getInfrastructureLogger(name: string | (() => string)): Logger;
  getCache(name: string): CacheFacade;
  watch(
    watchOptions: Watchpack.WatchOptions,
    handler: liteTapable.Callback<Error, Stats>,
  ): Watching;
  run(callback: liteTapable.Callback<Error, Stats>): void;
  runAsChild(
    callback: (
      err?: null | Error,
      entries?: Chunk[],
      compilation?: Compilation,
    ) => any,
  ): void;
  createChildCompiler(
    compilation: Compilation,
    compilerName: string,
    compilerIndex: number,
    outputOptions: OutputNormalized,
    plugins: RspackPluginInstance[],
  ): Compiler;
  compile(callback: liteTapable.Callback<Error, Compilation>): void;
  close(callback: (error?: Error | null) => void): void;
};
```

</>

  </CollapsePanel>
</Collapse>

- **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#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

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compiler.ts"
    key="Compiler"
  >
    <>

```ts
type Compiler = {
  hooks: CompilerHooks;
  inputFileSystem: InputFileSystem | null;
  outputFileSystem: OutputFileSystem | null;
  watchFileSystem: WatchFileSystem | null;
  options: RspackOptionsNormalized;
  watching: Watching;

  getInfrastructureLogger(name: string | (() => string)): Logger;
  getCache(name: string): CacheFacade;
  watch(
    watchOptions: Watchpack.WatchOptions,
    handler: liteTapable.Callback<Error, Stats>,
  ): Watching;
  run(callback: liteTapable.Callback<Error, Stats>): void;
  runAsChild(
    callback: (
      err?: null | Error,
      entries?: Chunk[],
      compilation?: Compilation,
    ) => any,
  ): void;
  createChildCompiler(
    compilation: Compilation,
    compilerName: string,
    compilerIndex: number,
    outputOptions: OutputNormalized,
    plugins: RspackPluginInstance[],
  ): Compiler;
  compile(callback: liteTapable.Callback<Error, Compilation>): void;
  close(callback: (error?: Error | null) => void): void;
};
```

</>

  </CollapsePanel>
</Collapse>

- **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#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

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compiler.ts"
    key="Compiler"
  >
    <>

```ts
type Compiler = {
  hooks: CompilerHooks;
  inputFileSystem: InputFileSystem | null;
  outputFileSystem: OutputFileSystem | null;
  watchFileSystem: WatchFileSystem | null;
  options: RspackOptionsNormalized;
  watching: Watching;

  getInfrastructureLogger(name: string | (() => string)): Logger;
  getCache(name: string): CacheFacade;
  watch(
    watchOptions: Watchpack.WatchOptions,
    handler: liteTapable.Callback<Error, Stats>,
  ): Watching;
  run(callback: liteTapable.Callback<Error, Stats>): void;
  runAsChild(
    callback: (
      err?: null | Error,
      entries?: Chunk[],
      compilation?: Compilation,
    ) => any,
  ): void;
  createChildCompiler(
    compilation: Compilation,
    compilerName: string,
    compilerIndex: number,
    outputOptions: OutputNormalized,
    plugins: RspackPluginInstance[],
  ): Compiler;
  compile(callback: liteTapable.Callback<Error, Compilation>): void;
  close(callback: (error?: Error | null) => void): void;
};
```

</>

  </CollapsePanel>
</Collapse>

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

- **Type:** `SyncHook<[Compilation]>`
- **Arguments:**
  - `compilation`: created [compilation](/api/javascript-api/compilation) object

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compilation.ts"
    key="Compilation"
  >
    <>

> See [compilation object](/api/javascript-api/compilation) for more details.

```ts
type Compilation = {
  emitAsset(): void; // add a new asset
  updateAsset(): void; // update content of the asset
  renameAsset(): void; // rename the asset
  deleteAsset(): void; // delete an existing asset
  getAssets(): Asset[]; // get all assets
  getAsset(): Asset; // get asset from name
  getPath(): string; // generate path from template
  getPathWithInfo(): PathWithInfo; // generate path and asset info from template
  getStats(): Stats; // get stats object
  createChildCompiler(): Compiler; // create a child compiler
  rebuildModule(): void; // run module.build again
  getLogger(): Logger; // get compilation related logger object
  getCache(): CacheFacade; // get compilation related cache object
  options: RspackOptionsNormalized; // the compiler options
  compiler: Compiler; // current compiler
  hooks: CompilationHooks; // hooks of compilation
  hash: string | null; // hash of this compilation
  fullhash: string | null; // same as 'hash'
  assets: Record<string, Source>; // mapping from filename to asset content
  chunkGroups: ChunkGroup[]; // list of chunk groups
  entrypoints: Map<string, Entrypoint>; // mapping from name to entrypoint
  namedChunkGroups: Map<string, ChunkGroup>; // mapping named chunk groups
  modules: Set<Module>; // set of all modules
  chunks: Set<Chunk>; // set of all chunks
  namedChunks: Map<string, Chunk>; // mapping of named chunks
  fileDependencies: CompilationDependencies; // dependent files
  contextDependencies: CompilationDependencies; // dependent directories
  missingDependencies: CompilationDependencies; // dependent missing files
  buildDependencies: CompilationDependencies; // dependent build files
  errors: RspackError[]; // errors during compilation
  warnings: RspackError[]; // warnings during compilation
};
```

</>

  </CollapsePanel>
</Collapse>

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

`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) object

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compilation.ts"
    key="Compilation"
  >
    <>

> See [compilation object](/api/javascript-api/compilation) for more details.

```ts
type Compilation = {
  emitAsset(): void; // add a new asset
  updateAsset(): void; // update content of the asset
  renameAsset(): void; // rename the asset
  deleteAsset(): void; // delete an existing asset
  getAssets(): Asset[]; // get all assets
  getAsset(): Asset; // get asset from name
  getPath(): string; // generate path from template
  getPathWithInfo(): PathWithInfo; // generate path and asset info from template
  getStats(): Stats; // get stats object
  createChildCompiler(): Compiler; // create a child compiler
  rebuildModule(): void; // run module.build again
  getLogger(): Logger; // get compilation related logger object
  getCache(): CacheFacade; // get compilation related cache object
  options: RspackOptionsNormalized; // the compiler options
  compiler: Compiler; // current compiler
  hooks: CompilationHooks; // hooks of compilation
  hash: string | null; // hash of this compilation
  fullhash: string | null; // same as 'hash'
  assets: Record<string, Source>; // mapping from filename to asset content
  chunkGroups: ChunkGroup[]; // list of chunk groups
  entrypoints: Map<string, Entrypoint>; // mapping from name to entrypoint
  namedChunkGroups: Map<string, ChunkGroup>; // mapping named chunk groups
  modules: Set<Module>; // set of all modules
  chunks: Set<Chunk>; // set of all chunks
  namedChunks: Map<string, Chunk>; // mapping of named chunks
  fileDependencies: CompilationDependencies; // dependent files
  contextDependencies: CompilationDependencies; // dependent directories
  missingDependencies: CompilationDependencies; // dependent missing files
  buildDependencies: CompilationDependencies; // dependent build files
  errors: RspackError[]; // errors during compilation
  warnings: RspackError[]; // warnings during compilation
};
```

</>

  </CollapsePanel>
</Collapse>

```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) object

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compilation.ts"
    key="Compilation"
  >
    <>

> See [compilation object](/api/javascript-api/compilation) for more details.

```ts
type Compilation = {
  emitAsset(): void; // add a new asset
  updateAsset(): void; // update content of the asset
  renameAsset(): void; // rename the asset
  deleteAsset(): void; // delete an existing asset
  getAssets(): Asset[]; // get all assets
  getAsset(): Asset; // get asset from name
  getPath(): string; // generate path from template
  getPathWithInfo(): PathWithInfo; // generate path and asset info from template
  getStats(): Stats; // get stats object
  createChildCompiler(): Compiler; // create a child compiler
  rebuildModule(): void; // run module.build again
  getLogger(): Logger; // get compilation related logger object
  getCache(): CacheFacade; // get compilation related cache object
  options: RspackOptionsNormalized; // the compiler options
  compiler: Compiler; // current compiler
  hooks: CompilationHooks; // hooks of compilation
  hash: string | null; // hash of this compilation
  fullhash: string | null; // same as 'hash'
  assets: Record<string, Source>; // mapping from filename to asset content
  chunkGroups: ChunkGroup[]; // list of chunk groups
  entrypoints: Map<string, Entrypoint>; // mapping from name to entrypoint
  namedChunkGroups: Map<string, ChunkGroup>; // mapping named chunk groups
  modules: Set<Module>; // set of all modules
  chunks: Set<Chunk>; // set of all chunks
  namedChunks: Map<string, Chunk>; // mapping of named chunks
  fileDependencies: CompilationDependencies; // dependent files
  contextDependencies: CompilationDependencies; // dependent directories
  missingDependencies: CompilationDependencies; // dependent missing files
  buildDependencies: CompilationDependencies; // dependent build files
  errors: RspackError[]; // errors during compilation
  warnings: RspackError[]; // warnings during compilation
};
```

</>

  </CollapsePanel>
</Collapse>

## `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) object

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compilation.ts"
    key="Compilation"
  >
    <>

> See [compilation object](/api/javascript-api/compilation) for more details.

```ts
type Compilation = {
  emitAsset(): void; // add a new asset
  updateAsset(): void; // update content of the asset
  renameAsset(): void; // rename the asset
  deleteAsset(): void; // delete an existing asset
  getAssets(): Asset[]; // get all assets
  getAsset(): Asset; // get asset from name
  getPath(): string; // generate path from template
  getPathWithInfo(): PathWithInfo; // generate path and asset info from template
  getStats(): Stats; // get stats object
  createChildCompiler(): Compiler; // create a child compiler
  rebuildModule(): void; // run module.build again
  getLogger(): Logger; // get compilation related logger object
  getCache(): CacheFacade; // get compilation related cache object
  options: RspackOptionsNormalized; // the compiler options
  compiler: Compiler; // current compiler
  hooks: CompilationHooks; // hooks of compilation
  hash: string | null; // hash of this compilation
  fullhash: string | null; // same as 'hash'
  assets: Record<string, Source>; // mapping from filename to asset content
  chunkGroups: ChunkGroup[]; // list of chunk groups
  entrypoints: Map<string, Entrypoint>; // mapping from name to entrypoint
  namedChunkGroups: Map<string, ChunkGroup>; // mapping named chunk groups
  modules: Set<Module>; // set of all modules
  chunks: Set<Chunk>; // set of all chunks
  namedChunks: Map<string, Chunk>; // mapping of named chunks
  fileDependencies: CompilationDependencies; // dependent files
  contextDependencies: CompilationDependencies; // dependent directories
  missingDependencies: CompilationDependencies; // dependent missing files
  buildDependencies: CompilationDependencies; // dependent build files
  errors: RspackError[]; // errors during compilation
  warnings: RspackError[]; // warnings during compilation
};
```

</>

  </CollapsePanel>
</Collapse>

## `afterCompile`

Called after the make phase and before the seal phase.

In the seal phase, Rspack will create chunk graph from the module graph and then generate the assets.

- **Type:** `AsyncSeriesHook<[Compilation]>`
- **Arguments:**
  - `Compilation`: current [compilation](/api/javascript-api/compilation) object

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compilation.ts"
    key="Compilation"
  >
    <>

> See [compilation object](/api/javascript-api/compilation) for more details.

```ts
type Compilation = {
  emitAsset(): void; // add a new asset
  updateAsset(): void; // update content of the asset
  renameAsset(): void; // rename the asset
  deleteAsset(): void; // delete an existing asset
  getAssets(): Asset[]; // get all assets
  getAsset(): Asset; // get asset from name
  getPath(): string; // generate path from template
  getPathWithInfo(): PathWithInfo; // generate path and asset info from template
  getStats(): Stats; // get stats object
  createChildCompiler(): Compiler; // create a child compiler
  rebuildModule(): void; // run module.build again
  getLogger(): Logger; // get compilation related logger object
  getCache(): CacheFacade; // get compilation related cache object
  options: RspackOptionsNormalized; // the compiler options
  compiler: Compiler; // current compiler
  hooks: CompilationHooks; // hooks of compilation
  hash: string | null; // hash of this compilation
  fullhash: string | null; // same as 'hash'
  assets: Record<string, Source>; // mapping from filename to asset content
  chunkGroups: ChunkGroup[]; // list of chunk groups
  entrypoints: Map<string, Entrypoint>; // mapping from name to entrypoint
  namedChunkGroups: Map<string, ChunkGroup>; // mapping named chunk groups
  modules: Set<Module>; // set of all modules
  chunks: Set<Chunk>; // set of all chunks
  namedChunks: Map<string, Chunk>; // mapping of named chunks
  fileDependencies: CompilationDependencies; // dependent files
  contextDependencies: CompilationDependencies; // dependent directories
  missingDependencies: CompilationDependencies; // dependent missing files
  buildDependencies: CompilationDependencies; // dependent build files
  errors: RspackError[]; // errors during compilation
  warnings: RspackError[]; // warnings during compilation
};
```

</>

  </CollapsePanel>
</Collapse>

## `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) object

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compilation.ts"
    key="Compilation"
  >
    <>

> See [compilation object](/api/javascript-api/compilation) for more details.

```ts
type Compilation = {
  emitAsset(): void; // add a new asset
  updateAsset(): void; // update content of the asset
  renameAsset(): void; // rename the asset
  deleteAsset(): void; // delete an existing asset
  getAssets(): Asset[]; // get all assets
  getAsset(): Asset; // get asset from name
  getPath(): string; // generate path from template
  getPathWithInfo(): PathWithInfo; // generate path and asset info from template
  getStats(): Stats; // get stats object
  createChildCompiler(): Compiler; // create a child compiler
  rebuildModule(): void; // run module.build again
  getLogger(): Logger; // get compilation related logger object
  getCache(): CacheFacade; // get compilation related cache object
  options: RspackOptionsNormalized; // the compiler options
  compiler: Compiler; // current compiler
  hooks: CompilationHooks; // hooks of compilation
  hash: string | null; // hash of this compilation
  fullhash: string | null; // same as 'hash'
  assets: Record<string, Source>; // mapping from filename to asset content
  chunkGroups: ChunkGroup[]; // list of chunk groups
  entrypoints: Map<string, Entrypoint>; // mapping from name to entrypoint
  namedChunkGroups: Map<string, ChunkGroup>; // mapping named chunk groups
  modules: Set<Module>; // set of all modules
  chunks: Set<Chunk>; // set of all chunks
  namedChunks: Map<string, Chunk>; // mapping of named chunks
  fileDependencies: CompilationDependencies; // dependent files
  contextDependencies: CompilationDependencies; // dependent directories
  missingDependencies: CompilationDependencies; // dependent missing files
  buildDependencies: CompilationDependencies; // dependent build files
  errors: RspackError[]; // errors during compilation
  warnings: RspackError[]; // warnings during compilation
};
```

</>

  </CollapsePanel>
</Collapse>

- **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) object

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compilation.ts"
    key="Compilation"
  >
    <>

> See [compilation object](/api/javascript-api/compilation) for more details.

```ts
type Compilation = {
  emitAsset(): void; // add a new asset
  updateAsset(): void; // update content of the asset
  renameAsset(): void; // rename the asset
  deleteAsset(): void; // delete an existing asset
  getAssets(): Asset[]; // get all assets
  getAsset(): Asset; // get asset from name
  getPath(): string; // generate path from template
  getPathWithInfo(): PathWithInfo; // generate path and asset info from template
  getStats(): Stats; // get stats object
  createChildCompiler(): Compiler; // create a child compiler
  rebuildModule(): void; // run module.build again
  getLogger(): Logger; // get compilation related logger object
  getCache(): CacheFacade; // get compilation related cache object
  options: RspackOptionsNormalized; // the compiler options
  compiler: Compiler; // current compiler
  hooks: CompilationHooks; // hooks of compilation
  hash: string | null; // hash of this compilation
  fullhash: string | null; // same as 'hash'
  assets: Record<string, Source>; // mapping from filename to asset content
  chunkGroups: ChunkGroup[]; // list of chunk groups
  entrypoints: Map<string, Entrypoint>; // mapping from name to entrypoint
  namedChunkGroups: Map<string, ChunkGroup>; // mapping named chunk groups
  modules: Set<Module>; // set of all modules
  chunks: Set<Chunk>; // set of all chunks
  namedChunks: Map<string, Chunk>; // mapping of named chunks
  fileDependencies: CompilationDependencies; // dependent files
  contextDependencies: CompilationDependencies; // dependent directories
  missingDependencies: CompilationDependencies; // dependent missing files
  buildDependencies: CompilationDependencies; // dependent build files
  errors: RspackError[]; // errors during compilation
  warnings: RspackError[]; // warnings during compilation
};
```

</>

  </CollapsePanel>
</Collapse>

## `afterEmit`

Called after emitting assets to output directory.

- **Type:** `AsyncSeriesHook<[Compilation]>`
- **Arguments:**
  - `Compilation`: current [compilation](/api/javascript-api/compilation) object

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compilation.ts"
    key="Compilation"
  >
    <>

> See [compilation object](/api/javascript-api/compilation) for more details.

```ts
type Compilation = {
  emitAsset(): void; // add a new asset
  updateAsset(): void; // update content of the asset
  renameAsset(): void; // rename the asset
  deleteAsset(): void; // delete an existing asset
  getAssets(): Asset[]; // get all assets
  getAsset(): Asset; // get asset from name
  getPath(): string; // generate path from template
  getPathWithInfo(): PathWithInfo; // generate path and asset info from template
  getStats(): Stats; // get stats object
  createChildCompiler(): Compiler; // create a child compiler
  rebuildModule(): void; // run module.build again
  getLogger(): Logger; // get compilation related logger object
  getCache(): CacheFacade; // get compilation related cache object
  options: RspackOptionsNormalized; // the compiler options
  compiler: Compiler; // current compiler
  hooks: CompilationHooks; // hooks of compilation
  hash: string | null; // hash of this compilation
  fullhash: string | null; // same as 'hash'
  assets: Record<string, Source>; // mapping from filename to asset content
  chunkGroups: ChunkGroup[]; // list of chunk groups
  entrypoints: Map<string, Entrypoint>; // mapping from name to entrypoint
  namedChunkGroups: Map<string, ChunkGroup>; // mapping named chunk groups
  modules: Set<Module>; // set of all modules
  chunks: Set<Chunk>; // set of all chunks
  namedChunks: Map<string, Chunk>; // mapping of named chunks
  fileDependencies: CompilationDependencies; // dependent files
  contextDependencies: CompilationDependencies; // dependent directories
  missingDependencies: CompilationDependencies; // dependent missing files
  buildDependencies: CompilationDependencies; // dependent build files
  errors: RspackError[]; // errors during compilation
  warnings: RspackError[]; // warnings during compilation
};
```

</>

  </CollapsePanel>
</Collapse>

## `done`

Called when the compilation has completed.

- **Type:** `AsyncSeriesHook<Stats>`
- **Arguments:**
  - `Stats`: generated stats object

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Stats.ts" key="Stats">
    <>

```ts
type Stats = {
  compilation: Compilation;
  hash: Readonly<string | null>;
  startTime?: number;
  endTime?: number;
  hasErrors(): bool;
  hasWarnings(): bool;
  toJson(opts?: StatsValue): StatsCompilation;
  toString(opts?: StatsValue): string;
};
```

</>

  </CollapsePanel>
</Collapse>

## `afterDone`

Called after `done` hook.

- **Type:** `SyncHook<Stats>`
- **Arguments:**
  - `Stats`: generated stats object

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Stats.ts" key="Stats">
    <>

```ts
type Stats = {
  compilation: Compilation;
  hash: Readonly<string | null>;
  startTime?: number;
  endTime?: number;
  hasErrors(): bool;
  hasWarnings(): bool;
  toJson(opts?: StatsValue): StatsCompilation;
  toString(opts?: StatsValue): string;
};
```

</>

  </CollapsePanel>
</Collapse>

## `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) to learn more about infrastructure logging.



---
url: /api/plugin-api/compilation-hooks.md
---

import Mermaid from '@components/Mermaid';
import { Badge } from '@theme';






import { Collapse, CollapsePanel } from '@components/Collapse';
import Columns from '@components/Columns';
import { NoSSR } from '@rspress/core/runtime';
import { ApiMeta } from '@components/ApiMeta';

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

<NoSSR>

<Columns styles={[{}, { flex: "0.6" }]}>

<Mermaid title="compilation.addEntry()">

{`
flowchart TD
EntryPlugin("EntryPlugin") --> AddEntry("compilation.addEntry(callback)")
AddEntry --> HookAddEntry(hooks.addEntry)
subgraph BuildModuleGraph["Create module graph"]
HookAddEntry --> FactorizeModule("ModuleFactory.create()")
FactorizeModule <--> SideEffectsResolve(<a href="/config/optimization#optimizationsideeffects">Tree shaking module side effects</a>)
FactorizeModule <--> Resolve("Resolve module path")

FactorizeModule --> BuildModule("compilation.buildModule()")
BuildModule --> HookStillValidModule{hooks.stillValidModule}
HookStillValidModule --> |true| ProcessDependencies("Process dependencies")
HookStillValidModule --> |false| HookBuildModule(<a href="#buildmodule">hooks.buildModule</a>)
HookBuildModule --> ModuleBuild("module.build()")
ModuleBuild --> RunLoaders("Run the loaders")
RunLoaders --> ParserParse("Parse dependencies")
ParserParse --> ModuleBuild
ParserParse <--> InnerGraph(<a href="/config/optimization#optimizationinnergraph">Tree shaking inner graph parsing</a>)
ParserParse <--> SideEffectsCode(<a href="/config/optimization#optimizationsideeffects">Tree shaking code side effects</a>)
ModuleBuild --> |success| HookSucceedModule(<a href="#succeedmodule">hooks.succeedModule</a>)
ModuleBuild --> |failed| HookFailedModule(hooks.failedModule)
HookSucceedModule --> ProcessDependencies
HookFailedModule --> ProcessDependencies
ProcessDependencies --> FactorizeModule
ProcessDependencies --> |failed| HookFailedEntry(hooks.failedEntry)
ProcessDependencies --> |success| HookSucceedEntry(hooks.succeedEntry)
HookFailedEntry --> Callback("callback()")
HookSucceedEntry --> Callback
end

class AddEntry flow-start
class Callback flow-end
class FactorizeModule,Resolve,BuildModule,ProcessDependencies,RunLoaders,ParserParse,ModuleBuild flow-process
class InnerGraph,SideEffectsResolve,SideEffectsCode flow-optimization
class HookBuildModule,HookSucceedModule flow-hook
class HookStillValidModule,HookAddEntry,HookFailedEntry,HookSucceedEntry,HookFailedModule flow-hook-non-support
`}

</Mermaid>

<div>
<Mermaid title="compilation.finish()">

{`
flowchart TD
CompilerCompile("compiler.compile()") --> CompilationFinish("compilation.finish(callback)")
CompilationFinish --> HookFinishModules(<a href="#finishmodules">hooks.finishModules</a>)
HookFinishModules <--> FlagDependencyExports(<a href="/config/optimization#optimizationprovidedexports">Tree shaking flag module exports</a>)
HookFinishModules --> Callback("callback()")

class CompilationFinish flow-start
class Callback flow-end
class FlagDependencyExports flow-optimization
class HookFinishModules flow-hook
`}

</Mermaid>

<br />

<Mermaid title="Stats">

{`
flowchart TD
StatsToString("stats.toString()") --> CreateStatsOptions("compilation.createStatsOptions")
CreateStatsOptions --> HookStatsPreset(<a href="#statspreset">hooks.statsPreset</a>)
HookStatsPreset --> HookStatsNormalize(<a href="#statsnormalize">hooks.statsNormalize</a>)
HookStatsNormalize --> CreateStatsOptions
CreateStatsOptions --> HookStatsFactory(<a href="#statsfactory">hooks.statsFactory</a>)
HookStatsFactory --> HookStatsPrinter(<a href="#statsprinter">hooks.statsPrinter</a>)
HookStatsPrinter --> StatsJSON("Generate stats JSON")
StatsJSON --> StatsOutput("Output stats string")

class StatsToString flow-start
class StatsOutput flow-end
class CreateStatsOptions,StatsJSON flow-process
class HookStatsFactory,HookStatsPrinter,HookStatsPreset,HookStatsNormalize flow-hook
`}

</Mermaid>

</div>

</Columns>

<br />

<Mermaid title="compilation.seal()">

{`
flowchart TD
subgraph Start
direction LR
CompilerCompile("compiler.compile()") --> Seal("compilation.seal(callback)")
Seal --> HookSeal(<a href="#seal">hooks.seal</a>)

class HookSeal flow-hook
end

Start --> ChunkGraph

subgraph ChunkGraph["Create chunk graph"]
direction LR

    subgraph OptimizeDependencies["Optimize module graph"]
    direction TB
    HooksOptimizationDependencies(hooks.optimizeDependencies) <--> FlagUsedExports(<a href="/config/optimization#optimizationusedexports">Tree shaking flag used exports</a>)
    HooksOptimizationDependencies --> HookAfterOptimizeDependencies(hooks.afterOptimizeDependencies)

    class HooksOptimizationDependencies,HookAfterOptimizeDependencies flow-hook-non-support
    class FlagUsedExports flow-optimization
    end

    OptimizeDependencies --> GenerateChunkGraph

    subgraph GenerateChunkGraph["Generate chunk graph"]
    direction TB
    HookBeforeChunks(hooks.beforeChunks) --> CreateEntryChunks("Create entry chunks")
    CreateEntryChunks --> BuildChunkGraph("Build chunk graph")
    BuildChunkGraph --> HookAfterChunks(hooks.afterChunks)

    class HookBeforeChunks,HookAfterChunks flow-hook-non-support
    class CreateEntryChunks,BuildChunkGraph flow-process
    class FlagUsedExports flow-optimization
    end

end

ChunkGraph --> Optimization

subgraph Optimization["Optimize modules and chunks"]
direction LR

    subgraph OptimizeModules["Optimize modules"]
    direction TB
    HookOptimize(hooks.optimize) --> HookOptimizeModules(<a href="#optimizemodules">hooks.optimizeModules</a>)
    HookOptimizeModules --> HookAfterOptimizeModules(<a href="#afteroptimizemodules">hooks.afterOptimizeModules</a>)

    class HookOptimize flow-hook-non-support
    class HookOptimizeModules,HookAfterOptimizeModules flow-hook-partial-support
    end

    OptimizeModules --> OptimizeChunks["Optimize chunks"]

    subgraph OptimizeChunks
    HookOptimizeChunks(hooks.optimizeChunks) <--> SplitChunks(<a href="/config/optimization#optimizationsplitchunks">Split chunks</a>)
    HookOptimizeChunks --> HookAfterOptimizeChunks(hooks.afterOptimizeChunks)

    class HookOptimizeChunks,HookAfterOptimizeChunks flow-hook-non-support
    class SplitChunks flow-optimization
    end

    OptimizeChunks --> OptimizeTree

    subgraph OptimizeTree["Optimize chunk groups"]
    HookOptimizeTree(<a href="#optimizetree">hooks.optimizeTree</a>) --> HookAfterOptimizeTree(hooks.afterOptimizeTree)

    class HookOptimizeTree flow-hook-partial-support
    class HookAfterOptimizeTree flow-hook-non-support
    end

    OptimizeTree --> OptimizeChunkModules

    subgraph OptimizeChunkModules["Optimize modules in chunks"]
    HookOptimizeChunkModules(<a href="#optimizechunkmodules">hooks.optimizeChunkModules</a>) <--> ModuleConcatenation(<a href="/config/optimization#optimizationconcatenatemodules">Module concatenation</a>)
    HookOptimizeChunkModules --> HookAfterOptimizeChunkModules(hooks.afterOptimizeChunkModules)
    HookAfterOptimizeChunkModules --> HookShouldRecord(hooks.shouldRecord)

    class HookOptimizeChunkModules flow-hook-partial-support
    class HookShouldRecord,HookAfterOptimizeChunkModules flow-hook-non-support
    class ModuleConcatenation flow-optimization
    end

end

Optimization --> GenerateIds

subgraph GenerateIds["Generate IDs of modules and chunks"]
direction LR

    subgraph CreateModuleIds["Generate IDs of modules"]
    HookReviveModules(hooks.reviveModules) --> HookBeforeModuleIds(hooks.beforeModuleIds)
    HookBeforeModuleIds --> HookModuleIds(hooks.moduleIds)
    HookModuleIds --> HookOptimizeModuleIds(hooks.optimizeModuleIds)
    HookOptimizeModuleIds --> HookAfterOptimizeModuleIds(hooks.afterOptimizeModuleIds)

    class HookReviveModules,HookModuleIds,HookBeforeModuleIds,HookOptimizeModuleIds,HookAfterOptimizeModuleIds flow-hook-non-support
    end

    CreateModuleIds --> CreateChunkIds

    subgraph CreateChunkIds["Generate IDs of chunks"]
    HookReviveChunks(hooks.reviveChunks) --> HookBeforeChunkIds(hooks.beforeChunkIds)
    HookBeforeChunkIds --> HookChunkIds(hooks.moduleIds)
    HookChunkIds --> HookOptimizeChunkIds(hooks.optimizeChunkIds)
    HookOptimizeChunkIds --> HookAfterOptimizeChunkIds(hooks.afterOptimizeChunkIds)

    class HookReviveChunks,HookChunkIds,HookBeforeChunkIds,HookOptimizeChunkIds,HookAfterOptimizeChunkIds flow-hook-non-support
    end

    CreateChunkIds --> CreateRecords

    subgraph CreateRecords["Generate records"]
    ShouldRecord{"shouldRecord"} --> |true| HookRecordModules(hooks.recordModules)
    ShouldRecord{"shouldRecord"} --> |false| HookOptimizeCodeGeneration(hooks.optimizeCodeGeneration)
    HookRecordModules --> HookRecordChunks(hooks.recordChunks)
    HookRecordChunks --> HookOptimizeCodeGeneration(hooks.optimizeCodeOptions)

    class ShouldRecord,HookRecordModules,HookRecordChunks,HookOptimizeCodeGeneration flow-hook-non-support
    class SplitChunks flow-optimization
    end

end

GenerateIds --> CodeGeneration

subgraph CodeGeneration["Generate code of modules"]
direction LR

    subgraph CreateModuleHashes["Generate hashes of modules"]
    HookBeforeModuleHash(hooks.beforeModuleHash) --> GenerateModuleHashes("Create module hashes")
    GenerateModuleHashes --> HookAfterModuleHash(hooks.afterModuleHash)

    class HookBeforeModuleHash,HookAfterModuleHash flow-hook-non-support
    class GenerateModuleHashes flow-process
    end

    CreateModuleHashes --> ModuleGeneration

    subgraph ModuleGeneration["Generate code of modules"]
    HookBeforeModuleCodeGeneration(hooks.beforeModuleCodeGeneration) --> ModuleCodeGeneration("Generate module codes")
    ModuleCodeGeneration --> HookAfterModuleCodeGeneration(hooks.afterModuleCodeGeneration)

    class HookBeforeModuleCodeGeneration,HookAfterModuleCodeGeneration flow-hook-non-support
    class ModuleCodeGeneration flow-process
    end

    ModuleGeneration --> CollectRuntimeRequirements

    subgraph CollectRuntimeRequirements["Collect runtime modules"]
    HookBeforeRuntime(hooks.beforeRuntimeRequirements) --> HookModuleRuntime(hooks.runtimeRequirementInModule)
    HookModuleRuntime --> HookAdditionalChunkRuntime(hooks.additionalChunkRuntimeRequirements)
    HookAdditionalChunkRuntime --> HookChunkRuntime(hooks.runtimeRequirementInChunk)
    HookChunkRuntime --> HookAdditionalTreeRuntime(<a href="#additionaltreeruntimerequirements">hooks.additionalTreeRuntimeRequirements</a>)
    HookAdditionalTreeRuntime --> HookTreeRuntime(<a href="#runtimerequirementintree">hooks.runtimeRequirementInTree</a>)
    HookTreeRuntime --> HookAfterRuntimeRequirements(hooks.afterRuntimeRequirements)
    HookTreeRuntime <--> HookRuntimeModule(<a href="#runtimemodule">hooks.runtimeModule</a>)

    class HookBeforeRuntime,HookModuleRuntime,HookAdditionalChunkRuntime,HookChunkRuntime,HookAfterRuntimeRequirements, flow-hook-non-support
    class HookAdditionalTreeRuntime,HookRuntimeModule,HookTreeRuntime flow-hook-partial-support
    class ModuleCodeGeneration flow-process
    end

    CollectRuntimeRequirements --> CompilationHash

    subgraph CompilationHash["Generate hash of compilation"]
    HookBeforeHash(hooks.beforeHash) --> CreateHash("Create compilation hash")
    CreateHash --> HookChunkHash(<a href="#chunkhash">hooks.chunkHash</a>)
    HookChunkHash --> HookFullHash(hooks.fullHash)
    HookFullHash --> CreateHash
    CreateHash --> HookAfterHash(hooks.afterHash)

    class HookBeforeHash,HookAfterHash,HookFullHash flow-hook-non-support
    class HookChunkHash flow-hook-partial-support
    class CreateHash flow-process
    end

end

CodeGeneration --> Assets

subgraph Assets["Generate assets"]
direction LR
subgraph CreateModuleAssets["Generate assets of modules"]
ShouldRecord2{"shouldRecord"} --> |true| HookRecordHash(hooks.recordHash)
HookRecordHash --> HookBeforeModuleAssets(hooks.beforeModuleAssets)
ShouldRecord2{"shouldRecord"} --> |false| HookBeforeModuleAssets
HookBeforeModuleAssets --> GenerateModuleAssets("Generate module assets")
GenerateModuleAssets <--> HookModuleAsset(hooks.moduleAsset)

    class ShouldRecord2,HookRecordHash,HookBeforeModuleAssets,HookModuleAsset flow-hook-non-support
    class GenerateModuleAssets flow-process
    end

    CreateModuleAssets --> CreateChunkAssets

    subgraph CreateChunkAssets["Generate assets of chunks"]
    HookShouldGenerateChunkAssets{hooks.shouldGenerateChunkAssets} --> |true| HookBeforeChunkAssets(hooks.beforeChunkAssets)
    HookBeforeChunkAssets --> GenerateChunkAssets("Generate chunk assets")
    GenerateChunkAssets --> HookRenderManifest(hooks.renderManifest)
    HookRenderManifest --> HookChunkAsset(<a href="#chunkasset">hooks.chunkAsset</a>)
    HookChunkAsset --> GenerateChunkAssets
    HookShouldGenerateChunkAssets --> |false| HookProcessAssets(<a href="#processassets">hooks.processAssets</a>)

    class HookBeforeChunkAssets,HookShouldGenerateChunkAssets,HookRenderManifest flow-hook-non-support
    class HookChunkAsset flow-hook-partial-support
    class HookProcessAssets flow-hook
    class GenerateChunkAssets flow-process
    end

    CreateChunkAssets --> ProcessAssets

    subgraph ProcessAssets["Process assets"]
      HookProcessAssets2(<a href="#processassets">hooks.processAssets</a>) --> HookAfterProcessAssets(<a href="#afterprocessassets">hooks.afterProcessAssets</a>)
      HookAfterProcessAssets --> |shouldRecord=true| HookRecord(hooks.record)

      class HookProcessAssets2,HookAfterProcessAssets flow-hook
      class HookRecord flow-hook-non-support

    end

end

Assets --> End

subgraph End
direction LR
HookNeedAdditionalSeal --> |true| HookUnseal(hooks.unseal)
HookNeedAdditionalSeal --> |false| HookAfterSeal
HookUnseal --> Reseal("compilation.seal()")
HookAfterSeal(<a href="#afterseal">hooks.afterSeal</a>) --> Callback("callback()")

class HookAfterSeal flow-hook
class HookNeedAdditionalSeal,HookUnseal flow-hook-non-support
class Reseal flow-start
end

End -. additional seal .-> Start

class Seal flow-start
class Callback flow-end

`}

</Mermaid>

</NoSSR>

## `buildModule`

<Badge text="Read-only" type="info" />

Triggered before a module build has started.

- **Type:** `SyncHook<[Module]>`
- **Arguments:**
  - `Module`: module instance

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Module.ts"
    key="Module"
  >
    <>

```ts
type Module = {
  context?: string;
  resource?: string;
  request?: string;
  userRequest?: string;
  rawRequest?: string;
  factoryMeta?: JsFactoryMeta;
  buildInfo: Record<string, any>;
  buildMeta: Record<string, any>;
  originalSource(): {
    isRaw: boolean;
    isBuffer: boolean;
    source: Buffer;
    map?: Buffer;
  } | null;
  identifier(): string;
  nameForCondition(): string | null;
};
```

</>

  </CollapsePanel>
</Collapse>

## `executeModule`

<Badge text="Read-only" type="info" />

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

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="ExecuteModuleArgument.ts" key="ExecuteModuleArgument">
```ts
type ExecuteModuleArgument = {
  codeGenerationResult: {
    get(sourceType: string): string;
  };
  moduleObject: {
    id: string;
    exports: any;
    loaded: boolean;
    error?: Error;
  };
};
```
  </CollapsePanel>
    <CollapsePanel className="collapse-code-panel" header="ExecuteModuleContext.ts" key="ExecuteModuleContext">
```ts
type ExecuteModuleContext = {
  __webpack_require__: (id: string) => any;
};
```
  </CollapsePanel>
</Collapse>

## `succeedModule`

<Badge text="Read-only" type="info" />

Executed when a module has been built successfully.

- **Type:** `SyncHook<[Module]>`
- **Arguments:**
  - `Module`: module instance

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Module.ts"
    key="Module"
  >
    <>

```ts
type Module = {
  context?: string;
  resource?: string;
  request?: string;
  userRequest?: string;
  rawRequest?: string;
  factoryMeta?: JsFactoryMeta;
  buildInfo: Record<string, any>;
  buildMeta: Record<string, any>;
  originalSource(): {
    isRaw: boolean;
    isBuffer: boolean;
    source: Buffer;
    map?: Buffer;
  } | null;
  identifier(): string;
  nameForCondition(): string | null;
};
```

</>

  </CollapsePanel>
</Collapse>

## `finishModules`

<Badge text="Read-only" type="info" />

Called when all modules have been built without errors.

- **Type:** `AsyncSeriesHook<[Module[]]>`
- **Arguments:**
  - `Module[]`: List of module instances

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Module.ts"
    key="Module"
  >
    <>

```ts
type Module = {
  context?: string;
  resource?: string;
  request?: string;
  userRequest?: string;
  rawRequest?: string;
  factoryMeta?: JsFactoryMeta;
  buildInfo: Record<string, any>;
  buildMeta: Record<string, any>;
  originalSource(): {
    isRaw: boolean;
    isBuffer: boolean;
    source: Buffer;
    map?: Buffer;
  } | null;
  identifier(): string;
  nameForCondition(): string | null;
};
```

</>

  </CollapsePanel>
</Collapse>

## `seal`

Called when the compilation stops accepting new modules and starts to optimize modules.

- **Type:** `SyncHook<[]>`

## `optimizeModules`

<Badge text="Read-only" type="info" />

Called at the beginning of the module optimization phase.

- **Type:** `SyncBailHook<[Module[]]>`
- **Arguments:**
  - `Module[]`: list of module instances

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Module.ts"
    key="Module"
  >
    <>

```ts
type Module = {
  context?: string;
  resource?: string;
  request?: string;
  userRequest?: string;
  rawRequest?: string;
  factoryMeta?: JsFactoryMeta;
  buildInfo: Record<string, any>;
  buildMeta: Record<string, any>;
  originalSource(): {
    isRaw: boolean;
    isBuffer: boolean;
    source: Buffer;
    map?: Buffer;
  } | null;
  identifier(): string;
  nameForCondition(): string | null;
};
```

</>

  </CollapsePanel>
</Collapse>

## `afterOptimizeModules`

<Badge text="Read-only" type="info" />

Called after modules optimization has completed.

- **Type:** `SyncBailHook<[Module[]]>`
- **Arguments:**
  - `Module[]`: list of module instances

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Module.ts"
    key="Module"
  >
    <>

```ts
type Module = {
  context?: string;
  resource?: string;
  request?: string;
  userRequest?: string;
  rawRequest?: string;
  factoryMeta?: JsFactoryMeta;
  buildInfo: Record<string, any>;
  buildMeta: Record<string, any>;
  originalSource(): {
    isRaw: boolean;
    isBuffer: boolean;
    source: Buffer;
    map?: Buffer;
  } | null;
  identifier(): string;
  nameForCondition(): string | null;
};
```

</>

  </CollapsePanel>
</Collapse>

## `optimizeTree`

<Badge text="Read-only" type="info" />

Called before optimizing the dependency tree.

- **Type:** `AsyncSeriesHook<[Chunk[], Module[]]>`
- **Arguments:**
  - `Chunk[]`: list of chunk instances
  - `Module[]`: list of module instances

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Chunk.ts" key="Chunk">
    <>

```ts
type Chunk = {
  auxiliaryFiles: ReadonlySet<string>;
  canBeInitial(): boolean;
  chunkReason?: Readonly<string>;
  contentHash: Readonly<Record<string, string>>;
  cssFilenameTemplate?: Readonly<string>;
  filenameTemplate?: Readonly<string>;
  files: ReadonlySet<string>;
  getAllAsyncChunks(): Iterable<Chunk>;
  getAllInitialChunks(): Iterable<Chunk>;
  getAllReferencedChunks(): Iterable<Chunk>;
  getEntryOptions(): EntryOptions | undefined;
  get groupsIterable(): Iterable<ChunkGroup>;
  hash?: Readonly<string>;
  hasRuntime(): boolean;
  id?: Readonly<string>;
  idNameHints: ReadonlyArray<string>;
  ids: ReadonlyArray<string>;
  isOnlyInitial(): boolean;
  name?: Readonly<string>;
  renderedHash?: Readonly<string>;
  runtime: ReadonlySet<string>;
};
```

</>

  </CollapsePanel>
  <CollapsePanel
    className="collapse-code-panel"
    header="Module.ts"
    key="Module"
  >
    <>

```ts
type Module = {
  context?: string;
  resource?: string;
  request?: string;
  userRequest?: string;
  rawRequest?: string;
  factoryMeta?: JsFactoryMeta;
  buildInfo: Record<string, any>;
  buildMeta: Record<string, any>;
  originalSource(): {
    isRaw: boolean;
    isBuffer: boolean;
    source: Buffer;
    map?: Buffer;
  } | null;
  identifier(): string;
  nameForCondition(): string | null;
};
```

</>

  </CollapsePanel>
</Collapse>

## `optimizeChunkModules`

<Badge text="Read-only" type="info" />

Called after the tree optimization, at the beginning of the chunk modules optimization.

- **Type:** `AsyncSeriesBailHook<[Chunk[], Module[]]>`
- **Arguments:**
  - `Chunk[]`: list of chunk instances
  - `Module[]`: list of module instances

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Chunk.ts" key="Chunk">
    <>

```ts
type Chunk = {
  auxiliaryFiles: ReadonlySet<string>;
  canBeInitial(): boolean;
  chunkReason?: Readonly<string>;
  contentHash: Readonly<Record<string, string>>;
  cssFilenameTemplate?: Readonly<string>;
  filenameTemplate?: Readonly<string>;
  files: ReadonlySet<string>;
  getAllAsyncChunks(): Iterable<Chunk>;
  getAllInitialChunks(): Iterable<Chunk>;
  getAllReferencedChunks(): Iterable<Chunk>;
  getEntryOptions(): EntryOptions | undefined;
  get groupsIterable(): Iterable<ChunkGroup>;
  hash?: Readonly<string>;
  hasRuntime(): boolean;
  id?: Readonly<string>;
  idNameHints: ReadonlyArray<string>;
  ids: ReadonlyArray<string>;
  isOnlyInitial(): boolean;
  name?: Readonly<string>;
  renderedHash?: Readonly<string>;
  runtime: ReadonlySet<string>;
};
```

</>

  </CollapsePanel>
  <CollapsePanel
    className="collapse-code-panel"
    header="Module.ts"
    key="Module"
  >
    <>

```ts
type Module = {
  context?: string;
  resource?: string;
  request?: string;
  userRequest?: string;
  rawRequest?: string;
  factoryMeta?: JsFactoryMeta;
  buildInfo: Record<string, any>;
  buildMeta: Record<string, any>;
  originalSource(): {
    isRaw: boolean;
    isBuffer: boolean;
    source: Buffer;
    map?: Buffer;
  } | null;
  identifier(): string;
  nameForCondition(): string | null;
};
```

</>

  </CollapsePanel>
</Collapse>

## `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`

<ApiMeta addedVersion="1.0.6" />

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#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);
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="RuntimeModule.ts"
    key="RuntimeModule"
  >
    <>

```ts
class RuntimeModule {
  source?: {
    isRaw: boolean;
    isBuffer: boolean;
    source: Buffer;
    map?: Buffer;
  };
  stage: number;
  name: string;
  identifier(): string;
  readableIdentifier(): string;
}
```

</>

  </CollapsePanel>
</Collapse>

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

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Source.ts"
    key="Source"
  >
    <>

```ts
type Source = {
  source(): string | ArrayBuffer;
  buffer(): Buffer;
  size(): number;
  map(options?: MapOptions): RawSourceMap | null;
  sourceAndMap(options?: MapOptions): SourceAndMapResult;
};
```

</>

  </CollapsePanel>
</Collapse>

### 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`

<Badge text="Read-only" type="info" />

Called after the [processAssets](#processAssets) hook had finished without error.

- **Type:** `SyncHook<Assets>`
- **Arguments:**
  - `Assets: Record<string, Source>`: list of asset instances

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Source.ts"
    key="Source"
  >
    <>

```ts
type Source = {
  source(): string | ArrayBuffer;
  buffer(): Buffer;
  size(): number;
  map(options?: MapOptions): RawSourceMap | null;
  sourceAndMap(options?: MapOptions): SourceAndMapResult;
};
```

</>

  </CollapsePanel>
</Collapse>

- **Example:**

```js
compilation.hooks.afterProcessAssets.tap('MyPlugin', (assets) => {
  console.log('assets', Object.keys(assets));
});
```

## `afterSeal`

<Badge text="Read-only" type="info" />

Called after the seal phase.

- **Type:** `AsyncSeriesHook<[]>`

## `chunkHash`

<Badge text="Read-only" type="info" />

Triggered to emit the hash for each chunk.

- **Type:** `SyncHook<[Chunk, Hash]>`
- **Arguments:**
  - `Chunk`: chunk instance
  - `Hash`: chunk hash instance

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Chunk.ts" key="Chunk">
    <>

```ts
type Chunk = {
  auxiliaryFiles: ReadonlySet<string>;
  canBeInitial(): boolean;
  chunkReason?: Readonly<string>;
  contentHash: Readonly<Record<string, string>>;
  cssFilenameTemplate?: Readonly<string>;
  filenameTemplate?: Readonly<string>;
  files: ReadonlySet<string>;
  getAllAsyncChunks(): Iterable<Chunk>;
  getAllInitialChunks(): Iterable<Chunk>;
  getAllReferencedChunks(): Iterable<Chunk>;
  getEntryOptions(): EntryOptions | undefined;
  get groupsIterable(): Iterable<ChunkGroup>;
  hash?: Readonly<string>;
  hasRuntime(): boolean;
  id?: Readonly<string>;
  idNameHints: ReadonlyArray<string>;
  ids: ReadonlyArray<string>;
  isOnlyInitial(): boolean;
  name?: Readonly<string>;
  renderedHash?: Readonly<string>;
  runtime: ReadonlySet<string>;
};
```

</>

  </CollapsePanel>
  <CollapsePanel className="collapse-code-panel" header="Hash.ts" key="Hash">
    <>

```ts
type Hash = {
  update(data: string | Buffer, inputEncoding?: string): Hash;
  digest(encoding?: string): string | Buffer;
};
```

</>

  </CollapsePanel>
</Collapse>

## `chunkAsset`

<Badge text="Read-only" type="info" />

Triggered when an asset from a chunk was added to the compilation.

- **Type:** `SyncHook<[Chunk, string]>`
- **Arguments:**
  - `Chunk`: chunk instance
  - `string`: asset filename

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Chunk.ts" key="Chunk">
    <>

```ts
type Chunk = {
  auxiliaryFiles: ReadonlySet<string>;
  canBeInitial(): boolean;
  chunkReason?: Readonly<string>;
  contentHash: Readonly<Record<string, string>>;
  cssFilenameTemplate?: Readonly<string>;
  filenameTemplate?: Readonly<string>;
  files: ReadonlySet<string>;
  getAllAsyncChunks(): Iterable<Chunk>;
  getAllInitialChunks(): Iterable<Chunk>;
  getAllReferencedChunks(): Iterable<Chunk>;
  getEntryOptions(): EntryOptions | undefined;
  get groupsIterable(): Iterable<ChunkGroup>;
  hash?: Readonly<string>;
  hasRuntime(): boolean;
  id?: Readonly<string>;
  idNameHints: ReadonlyArray<string>;
  ids: ReadonlyArray<string>;
  isOnlyInitial(): boolean;
  name?: Readonly<string>;
  renderedHash?: Readonly<string>;
  runtime: ReadonlySet<string>;
};
```

</>

  </CollapsePanel>
</Collapse>

## `childCompiler`

<Badge text="Read-only" type="info" />

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

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="Compiler.ts"
    key="Compiler"
  >
    <>

```ts
type Compiler = {
  hooks: CompilerHooks;
  inputFileSystem: InputFileSystem | null;
  outputFileSystem: OutputFileSystem | null;
  watchFileSystem: WatchFileSystem | null;
  options: RspackOptionsNormalized;
  watching: Watching;

  getInfrastructureLogger(name: string | (() => string)): Logger;
  getCache(name: string): CacheFacade;
  watch(
    watchOptions: Watchpack.WatchOptions,
    handler: liteTapable.Callback<Error, Stats>,
  ): Watching;
  run(callback: liteTapable.Callback<Error, Stats>): void;
  runAsChild(
    callback: (
      err?: null | Error,
      entries?: Chunk[],
      compilation?: Compilation,
    ) => any,
  ): void;
  createChildCompiler(
    compilation: Compilation,
    compilerName: string,
    compilerIndex: number,
    outputOptions: OutputNormalized,
    plugins: RspackPluginInstance[],
  ): Compiler;
  compile(callback: liteTapable.Callback<Error, Compilation>): void;
  close(callback: (error?: Error | null) => void): void;
};
```

</>

  </CollapsePanel>
</Collapse>

## `statsPreset`

<Badge text="Read-only" type="info" />

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

<Collapse>
  <CollapsePanel header="StatsOptions.ts" key="StatsOptions">
See [stats configuration](/config/stats) for details.
  </CollapsePanel>
  <CollapsePanel className="collapse-code-panel" header="CreateStatsOptionsContext.ts" key="CreateStatsOptionsContext">
```ts
type CreateStatsOptionsContext = {
  forToString?: boolean;
  [key: string]: any;
};
```
  </CollapsePanel>
</Collapse>

## `statsNormalize`

<Badge text="Read-only" type="info" />

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.

<Collapse>
  <CollapsePanel header="StatsOptions.ts" key="StatsOptions">
See [stats configuration](/config/stats) for details.
  </CollapsePanel>
  <CollapsePanel className="collapse-code-panel" header="CreateStatsOptionsContext.ts" key="CreateStatsOptionsContext">
```ts
type CreateStatsOptionsContext = {
  forToString?: boolean;
  [key: string]: any;
};
```
  </CollapsePanel>
</Collapse>

## `statsFactory`

<Badge text="Read-only" type="info" />

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#statsfactory) for more details
  - `StatsOptions`: stats options

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="StatsFactory.ts" key="StatsFactory">
```ts
type StatsFactory = {
  hooks: StatsFactoryHooks;
  create(
    type: string,
    data: any,
    baseContext: Omit<StatsFactoryContext, 'type'>,
  ): void;
};
```
  </CollapsePanel>
  <CollapsePanel header="StatsOptions.ts" key="StatsOptions">
See [stats configuration](/config/stats) for details.
  </CollapsePanel>
</Collapse>

## `statsPrinter`

<Badge text="Read-only" type="info" />

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#statsprinter) for more details.
  - `StatsOptions`: stats options

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="StatsPrinter.ts" key="StatsPrinter">
```ts
type StatsPrinter = {
  hooks: StatsPrinterHooks;
  print(
    type: string,
    object: {
      [key: string]: any;
    },
    baseContext?: {
      [key: string]: any;
    },
  ): string;
};
```
  </CollapsePanel>
  <CollapsePanel header="StatsOptions.ts" key="StatsOptions">
See [stats configuration](/config/stats) for details.
  </CollapsePanel>
</Collapse>



---
url: /api/plugin-api/normal-module-factory-hooks.md
---


import { Collapse, CollapsePanel } from '@components/Collapse';

# NormalModuleFactory

`NormalModuleFactory` is used by the [Compiler](/api/javascript-api/compiler) 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.

## `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));
    });
  },
);
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="ResolveData.ts"
    key="ResolveData"
  >
    <>

```ts
export type ResolveData = {
  contextInfo: {
    issuer: string;
  };
  context: string;
  request: string;
  fileDependencies: string[];
  missingDependencies: string[];
  contextDependencies: string[];
  createData?: {
    request?: string;
    userRequest?: string;
    resource?: string;
  };
};
```

</>

  </CollapsePanel>
</Collapse>

## `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));
    });
  },
);
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="ResolveData.ts"
    key="ResolveData"
  >
    <>

```ts
export type ResolveData = {
  contextInfo: {
    issuer: string;
  };
  context: string;
  request: string;
  fileDependencies: string[];
  missingDependencies: string[];
  contextDependencies: string[];
  createData?: {
    request?: string;
    userRequest?: string;
    resource?: string;
  };
};
```

</>

  </CollapsePanel>
</Collapse>

:::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));
    });
  },
);
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="ResolveData.ts"
    key="ResolveData"
  >
    <>

```ts
export type ResolveData = {
  contextInfo: {
    issuer: string;
  };
  context: string;
  request: string;
  fileDependencies: string[];
  missingDependencies: string[];
  contextDependencies: string[];
  createData?: {
    request?: string;
    userRequest?: string;
    resource?: string;
  };
};
```

</>

  </CollapsePanel>
</Collapse>

:::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));
    });
  },
);
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="ResolveData.ts"
    key="ResolveData"
  >
    <>

```ts
export type ResolveData = {
  contextInfo: {
    issuer: string;
  };
  context: string;
  request: string;
  fileDependencies: string[];
  missingDependencies: string[];
  contextDependencies: string[];
  createData?: {
    request?: string;
    userRequest?: string;
    resource?: string;
  };
};
```

</>

  </CollapsePanel>
</Collapse>

## `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));
      });
  },
);
```

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="ResourceDataWithData.ts" key="ResourceDataWithData">
```ts
type ResourceDataWithData = {
  resource: string;
  path: string;
  query?: string;
  fragment?: string;
  data?: Record<string, any>;
};
```
  </CollapsePanel>
</Collapse>



---
url: /api/plugin-api/context-module-factory-hooks.md
---

import { Collapse, CollapsePanel } from '@components/Collapse';

# ContextModuleFactory

The `ContextModuleFactory` module is used by the `Compiler` to generate dependencies from [require.context](/api/runtime-api/module-methods#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).

## `beforeResolve`

`AsyncSeriesBailHook<[BeforeResolveResult]>`

Called before resolving the requested directory. The request can be ignored by returning `false`.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="BeforeResolveResult.ts"
    key="BeforeResolveResult"
  >
```ts
type BeforeResolveData = {
  context: string;
  request: string;
  regExp: RegExp | undefined;
  recursive: boolean;
}

export type BeforeResolveResult =
  | false
  | BeforeResolveData;
```
  </CollapsePanel>
</Collapse>

## `afterResolve`

`AsyncSeriesBailHook<[AfterResolveResult]>`

Called after the requested directory resolved.

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="AfterResolveResult.ts"
    key="AfterResolveResult"
  >
```ts
type AfterResolveData = {
  resource: number;
  context: string;
  request: string;
  regExp: RegExp | undefined;
  recursive: boolean;
  dependencies: Dependency[];
}

export type AfterResolveResult = 
  | false
  | AfterResolveData;
```
  </CollapsePanel>
</Collapse>



---
url: /api/plugin-api/javascript-modules-plugin-hooks.md
---



import { Collapse, CollapsePanel } from '@components/Collapse';

# JavascriptModulesPlugin

## `chunkHash`

`SyncHook<[Chunk, Hash]>`

Called when computing the chunk hash for JavaScript chunks.

<Collapse>
  <CollapsePanel className="collapse-code-panel" header="Chunk.ts" key="Chunk">
    <>

```ts
type Chunk = {
  auxiliaryFiles: ReadonlySet<string>;
  canBeInitial(): boolean;
  chunkReason?: Readonly<string>;
  contentHash: Readonly<Record<string, string>>;
  cssFilenameTemplate?: Readonly<string>;
  filenameTemplate?: Readonly<string>;
  files: ReadonlySet<string>;
  getAllAsyncChunks(): Iterable<Chunk>;
  getAllInitialChunks(): Iterable<Chunk>;
  getAllReferencedChunks(): Iterable<Chunk>;
  getEntryOptions(): EntryOptions | undefined;
  get groupsIterable(): Iterable<ChunkGroup>;
  hash?: Readonly<string>;
  hasRuntime(): boolean;
  id?: Readonly<string>;
  idNameHints: ReadonlyArray<string>;
  ids: ReadonlyArray<string>;
  isOnlyInitial(): boolean;
  name?: Readonly<string>;
  renderedHash?: Readonly<string>;
  runtime: ReadonlySet<string>;
};
```

</>

  </CollapsePanel>
  <CollapsePanel className="collapse-code-panel" header="Hash.ts" key="Hash">
    <>

```ts
type Hash = {
  update(data: string | Buffer, inputEncoding?: string): Hash;
  digest(encoding?: string): string | Buffer;
};
```

</>

  </CollapsePanel>
</Collapse>



---
url: /api/plugin-api/stats-hooks.md
---

# Stats hooks

## StatsFactory

### StatsFactory.hooks.extract

A HookMap, called when generating the specified stats item.

- **Type:** `HookMap<SyncBailHook<[Object, any, StatsFactoryContext], undefined>>`
- **Arguments:**
  - `Object`: result stats item object which properties should be added.
  - `Class`: the original data of the stats item
  - `StatsFactoryContext`: generating context

```ts
type StatsFactoryContext = {
  type: string;
  makePathsRelative?: ((arg0: string) => string) | undefined;
  compilation?: Compilation | undefined;
  cachedGetErrors?: ((arg0: Compilation) => JsStatsError[]) | undefined;
  cachedGetWarnings?: ((arg0: Compilation) => JsStatsWarning[]) | undefined;
};
```

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, called after generating the specified stats item.

- **Type:** `HookMap<SyncWaterfallHook<[any[], StatsFactoryContext], undefined>>`
- **Arguments:**
  - `any[]`: generated stats item result
  - `StatsFactoryContext`: generating context

## StatsPrinter

### StatsPrinter.hooks.print

A HookMap, called

为一个 HookMap, 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
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;
};
```

### StatsPrinter.hooks.result

A HookMap, called after generating the printed string of the specified stats item.

- **Type:** `HookMap<SyncBailHook<[{}, StatsPrinterContext], string>>`
- **Arguments:**
  - `String`: printed string of the stats item
  - `StatsPrinterContext`: printing context



---
url: /api/plugin-api/runtime-plugin-hooks.md
---

import { Collapse, CollapsePanel } from '@components/Collapse';


# 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`

`SyncWaterallHook<[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';
  `;
});
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="CreateScript.ts"
    key="CreateScript"
  >
    <>

```ts
type Chunk = {
  auxiliaryFiles: ReadonlySet<string>;
  canBeInitial(): boolean;
  chunkReason?: Readonly<string>;
  contentHash: Readonly<Record<string, string>>;
  cssFilenameTemplate?: Readonly<string>;
  filenameTemplate?: Readonly<string>;
  files: ReadonlySet<string>;
  getAllAsyncChunks(): Iterable<Chunk>;
  getAllInitialChunks(): Iterable<Chunk>;
  getAllReferencedChunks(): Iterable<Chunk>;
  getEntryOptions(): EntryOptions | undefined;
  get groupsIterable(): Iterable<ChunkGroup>;
  hash?: Readonly<string>;
  hasRuntime(): boolean;
  id?: Readonly<string>;
  idNameHints: ReadonlyArray<string>;
  ids: ReadonlyArray<string>;
  isOnlyInitial(): boolean;
  name?: Readonly<string>;
  renderedHash?: Readonly<string>;
  runtime: ReadonlySet<string>;
};
```

</>

  </CollapsePanel>
</Collapse>

## `linkPrefetch`

`SyncWaterallHook<[string, chunk]>`

Can modify the code executed when creating the [prefetch](/guide/optimization/code-splitting#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';
  `;
});
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="CreateScript.ts"
    key="CreateScript"
  >
    <>

```ts
type Chunk = {
  auxiliaryFiles: ReadonlySet<string>;
  canBeInitial(): boolean;
  chunkReason?: Readonly<string>;
  contentHash: Readonly<Record<string, string>>;
  cssFilenameTemplate?: Readonly<string>;
  filenameTemplate?: Readonly<string>;
  files: ReadonlySet<string>;
  getAllAsyncChunks(): Iterable<Chunk>;
  getAllInitialChunks(): Iterable<Chunk>;
  getAllReferencedChunks(): Iterable<Chunk>;
  getEntryOptions(): EntryOptions | undefined;
  get groupsIterable(): Iterable<ChunkGroup>;
  hash?: Readonly<string>;
  hasRuntime(): boolean;
  id?: Readonly<string>;
  idNameHints: ReadonlyArray<string>;
  ids: ReadonlyArray<string>;
  isOnlyInitial(): boolean;
  name?: Readonly<string>;
  renderedHash?: Readonly<string>;
  runtime: ReadonlySet<string>;
};
```

</>

  </CollapsePanel>
</Collapse>

## `linkPreload`

`SyncWaterallHook<[string, chunk]>`

Can modify the code executed when creating the [preload](/guide/optimization/code-splitting#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';
  `;
});
```

<Collapse>
  <CollapsePanel
    className="collapse-code-panel"
    header="CreateScript.ts"
    key="CreateScript"
  >
    <>

```ts
type Chunk = {
  auxiliaryFiles: ReadonlySet<string>;
  canBeInitial(): boolean;
  chunkReason?: Readonly<string>;
  contentHash: Readonly<Record<string, string>>;
  cssFilenameTemplate?: Readonly<string>;
  filenameTemplate?: Readonly<string>;
  files: ReadonlySet<string>;
  getAllAsyncChunks(): Iterable<Chunk>;
  getAllInitialChunks(): Iterable<Chunk>;
  getAllReferencedChunks(): Iterable<Chunk>;
  getEntryOptions(): EntryOptions | undefined;
  get groupsIterable(): Iterable<ChunkGroup>;
  hash?: Readonly<string>;
  hasRuntime(): boolean;
  id?: Readonly<string>;
  idNameHints: ReadonlyArray<string>;
  ids: ReadonlyArray<string>;
  isOnlyInitial(): boolean;
  name?: Readonly<string>;
  renderedHash?: Readonly<string>;
  runtime: ReadonlySet<string>;
};
```

</>

  </CollapsePanel>
</Collapse>



---
url: /blog/index.md
---


# Rspack blogs

Check here for the latest articles and release announcements about Rspack.

## [Announcing Rspack 1.7](/blog/announcing-1-7)

> December 31, 2025

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

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.

## [Announcing Rspack 1.4](/blog/announcing-1-4)

> June 26, 2025

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

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.

## [Announcing Rspack 1.3](/blog/announcing-1-3)

> March 28, 2025

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

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

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

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

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

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

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

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 09, 2024

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 09, 2024

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

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 02, 2023

Rspack 0.5 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

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

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 0.3 is out, adding support for web workers and the builtin:swc-loader.

## [Announcing Rspack 0.2](/blog/announcing-0-2)

> June 02, 2023

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 06, 2023

Rspack has officially been released!



---
url: /blog/announcing-1-7.md
---


_December 31, 2025_

# Announcing Rspack 1.7

![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/features/lazy-compilation) 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) 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/deprecated-options#experimentsinlineconst) option is deprecated.
  - If you need to disable this behavior, use [optimization.inlineExports](/config/optimization#optimizationinlineexports) to control it.
- **TypeScript Enum Inlining Optimization**: This optimization is now stable.
  - The original [experiments.inlineEnum](/config/deprecated-options#experimentsinlineenum) option is deprecated.
  - Use [collectTypeScriptInfo.exportedEnum](/guide/features/builtin-swc-loader#collecttypescriptinfoexportedenum) to control whether to collect exported `enum` information.
  - Use [optimization.inlineExports](/config/optimization#optimizationinlineexports) to control whether to inline `enum`.
- **Type Re-export Check**: This optimization is now stable.
  - The original [experiments.typeReexportsPresence](/config/deprecated-options#experimentstypereexportspresence) 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](/plugins/rspack/esm-library-plugin#esmlibraryplugin) 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).

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


_October 30, 2025_

# Announcing Rspack 1.6

![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-1-6)
  - [Rspress v2 beta](#rspress-v2-beta)
  - [Rslib 0.16](#rslib-0-16)
  - [Rstest 0.6](#rstest-0-6)
  - [Rsdoctor 1.3](#rsdoctor-1-3)
- 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#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#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](/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](/config/experiments#experimentslazybarrel) 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](/config/experiments#experimentslayers) 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 [Layer guide](/guide/features/layer#layer).

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

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


_August 26, 2025_

# Announcing Rspack 1.5

![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](/config/experiments#experimentslazybarrel) 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](/config/experiments#experimentslazybarrel).

### 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#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), 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/experiments#experimentsinlineconst) and [experiments.inlineEnum](/config/experiments#experimentsinlineenum) — 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/experiments#experimentsinlineconst). 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/experiments#experimentsinlineenum).

### 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/experiments#experimentstypereexportspresence) 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/experiments#experimentstypereexportspresence).

### Built-in virtual modules plugin

In Rspack 1.4, we introduced [custom InputFileSystem](/blog/announcing-1-4#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/rspack/virtual-modules-plugin).

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

### Stabilization of lazy compilation

After extensive validation, the [experiments.lazyCompilation](/config/experiments#experimentslazycompilation) 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](/config/experiments#experimentstoplevelawait) 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#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) to compile dynamically imported modules on demand, improving development server startup speed.
- Enabled [lazyBarrel](/config/experiments#experimentslazybarrel) to optimize the build performance of barrel files and reduce unnecessary module resolution.
- Enabled [inlineEnum](/config/experiments#experimentsinlineenum) to inline TypeScript enums, reducing the bundle size after compilation.
- Enabled [typeReexportsPresence](/config/experiments#experimentsinlineenum) 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/rstest/mockModules), 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
---


_June 26, 2025_

# Announcing Rspack 1.4

![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 out our [online example](https://stackblitz.com/~/github.com/rstackjs/rsbuild-stackblitz-example) directly, or learn about the StackBlitz usage guide in [this documentation](/guide/start/quick-start#preview-with-stackblitz).

<video
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-4-wasm-target.mp4"
  autoPlay
  muted
  loop
/>

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

<img
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-4-swc-benchmark.png"
  alt="SWC benchmark"
/>

> 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) 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:

<img
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-4-incremental-data.png"
  alt="incremental benchmark"
  width="760"
/>

If you need to revert to the previous behavior, you can set [experiments.incremental](/config/experiments#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/rspack/css-chunking-plugin) 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/rspack/css-chunking-plugin) 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/experiments#experimentslazycompilation) 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#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#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/):

<img
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-4-tracing.png"
  alt="tracing"
/>

> For more detailed usage, see the [Tracing documentation](/contribute/development/tracing).

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

<img
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-4-rsbuild-plugin-dev-tools-json.png"
  alt="rsbuild plugin devtools json"
  width="760"
/>

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

<img
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-4-rsbuild-monorepo-compile-scope.png"
  alt="rsbuild monorepo compile scope"
  width="600"
/>

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

<img
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-4-rslib-esm.png"
  alt="rslib esm"
  width="700"
/>

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

<img
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-4-rslib-iife.png"
  alt="rslib iife"
  width="700"
/>

> 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:

<img
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-4-rspress-preview.png"
  alt="rspress theme preview"
  width="800"
/>

### Rsdoctor MCP

Rsdoctor has introduced [@rsdoctor/mcp-server](https://rsdoctor.rs/guide/start/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.

<video
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-4-rsdoctor-mcp.mp4"
  autoPlay
  muted
  loop
/>

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

<img
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-4-rstest.png"
  alt="rstest"
  width="600"
/>

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

<img
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-4-next-rspack.png"
  alt="next-rspack"
  width="760"
/>

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

### Lazy compilation middleware

The lazy compilation middleware has changed its way of accessing the [lazyCompilation](/config/experiments#experimentslazycompilation) 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
---


_April 10, 2025_

# Rspack joins the Next.js ecosystem

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/tech/next) 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
---


_March 28, 2025_

# Announcing Rspack 1.3

![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-subtypes-changed)
  - [Upgrade SWC plugins](#upgrade-swc-plugins)

## New features

### Circular dependency detection

Rspack 1.3 introduces a built-in plugin [CircularDependencyRspackPlugin](/plugins/rspack/circular-dependency-rspack-plugin) 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#externalspresetsweb) or [externalsPresets.webAsync](/config/externals#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#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#experimentsbuildhttp) for more details.

### Lazy compilation improvements

In previous versions, when [lazy compilation](/guide/features/lazy-compilation) 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#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](/config/experiments#experimentsparallelcodesplitting) 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#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) 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.

<img
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-3-memory-improve-max-generations.png"
  width="760"
  alt="Max generations"
/>

## Rstack updates

<img
  src="https://assets.rspack.rs/rstack/rstack-overview.png"
  width="760"
  alt="Rstack"
/>

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



---
url: /blog/announcing-1-2.md
---


_January 21, 2025_

# Announcing Rspack 1.2

![Rspack 1.2](https://assets.rspack.rs/rspack/rspack-banner-v1-2.png)

> Posted by [@jerrykingxyz](https://github.com/jerrykingxyz), [@chenjiahan](https://github.com/chenjiahan), [@JSerFeng](https://github.com/JSerFeng), [@ahabhgk](https://github.com/ahabhgk)

---

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-v1-2)

## 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 [experiments.cache](/config/experiments#experimentscache) 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#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,
  },
};
```

> See [experiments.parallelCodeSplitting](/config/experiments#experimentsparallelcodesplitting) for more details.

### 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#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 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://github.com/nrwl/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://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/webpack/case-sensitive-plugin) 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
---


_November 7, 2024_

# Announcing Rspack 1.1

![Rspack 1.1](https://assets.rspack.rs/rspack/rspack-banner-v1-1.png)

> Posted by [@LingyuCoder](https://github.com/LingyuCoder), [@ahabhgk](https://github.com/ahabhgk), [@GiveMe-A-Name](https://github.com/GiveMe-A-Name), [@9aoy](https://github.com/9aoy), [@chenjiahan](https://github.com/chenjiahan)

---

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.

<img
  width="850"
  src="https://assets.rspack.rs/rspack/assets/rspack-1-1-perf-comparison.png"
  alt="Rspack v1.1 vs v1.0"
/>

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/experiments#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:

<img
  width="850"
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-1-new-incremental-compare.png"
  alt="10000 React Components with new incremental enabled"
/>

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/experiments#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/rspack/html-rspack-plugin) 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/rspack/html-rspack-plugin) 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.

<img
  width="850"
  src="https://assets.rspack.rs/rspack/assets/rspack-v1-1-config-intellisense.png"
  alt="configuration intellisense in IDE"
/>

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

<img
  width="650"
  src="https://assets.rspack.rs/rsbuild/assets/rsbuild-cli-shortcuts.png"
  alt="Rsbuild CLI shortcuts"
/>

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

<img
  src="https://assets.rspack.rs/rsbuild/assets/assets-report-page.png"
  alt="rsbuild-dev-server"
  width="600"
/>

### 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#outputhashfunction) now defaults to the faster `xxhash64`, and the [output.hashDigestLength](/config/output#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
---


_August 28, 2024_

# Announcing Rspack 1.0

![](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/experiments#experimentslazycompilation) 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](/guide/compatibility/plugin), 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/webpack/split-chunks-plugin#splitchunksplugin), [tree shaking](/guide/optimization/tree-shaking), [scope hoisting](/config/optimization#optimizationconcatenatemodules) and [mangle exports](/config/optimization#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](/). 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).

If you have never used Rspack before, please see [Quick Start](/guide/start/quick-start) 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#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](/config/experiments#experimentslayers) 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](/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/migration/rsbuild-0-x) 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) 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
---


import { PackageManagerTabs } from '@theme';

_June 29, 2024_

# Announcing Rspack 1.0 alpha

![](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#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/experiments#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/experiments#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#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
---


import { PackageManagerTabs } from '@theme';

_May 28, 2024_

# Announcing Rspack 0.7

![](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/experiments#experimentslazycompilation) 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/experiments#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/experiments#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://rsbuild.rs/community/releases/v0-7) to learn more.



---
url: /blog/announcing-0-6.md
---


import { PackageManagerTabs } from '@theme';

_April 10, 2024_

# Announcing Rspack 0.6

## 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/rspack/css-extract-rspack-plugin#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#moduleparsercssauto) and [`module.generator`](/config/module#modulegeneratorcssauto) 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/rspack/css-extract-rspack-plugin.html).

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#rulesparser) and [`rules[].generator`](/config/module-rules#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
---


import { PackageManagerTabs } from '@theme';

_January 09, 2024_

# Announcing Rspack 0.5

## Major feature updates

### Module Federation added to Rspack

Checkout [this blog](/blog/module-federation-added-to-rspack) 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#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) 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#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#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](/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](https://rspack.rs/blog/announcing-0.4#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.

<PackageManagerTabs command="install @swc/helpers" />

If you are using `@rspack/plugin-react-refresh`, now you need to install `react-refresh` as devDependencies of your project.

<PackageManagerTabs command="install 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
---


# Module Federation added to Rspack

> January 09, 2024

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

<div align="center">
  <img
    src="https://assets.rspack.rs/rspack/assets/rspack-federation-with-rspack.png"
    width="50%"
    height="50%"
    alt="Rspack with Infinity Gauntlet"
  />
</div>

## 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). 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
const { rspack } = require('@rspack/core');

new rspack.container.ModuleFederationPlugin({
  name: 'app1',
  filename: 'static/js/remoteEntry.js',
  exposes: {
    './Button': './src/components/button.js',
  },
  runtimePlugins: [require.resolve('./my-custom-plugin')]
  remotes: {
    app2: 'app2@http://localhost:3002/static/js/remoteEntry.js',
  },
  shared: {
    react: { singleton: true },
    'react-dom': { singleton: true },
  },
})
```

And For Webpack:

```js
const { ModuleFederationPlugin } = require('@module-federation/enhanced');

new ModuleFederationPlugin({
  name: 'app1',
  filename: 'static/js/remoteEntry.js',
  exposes: {
    './Button': './src/components/button.js',
  },
  runtimePlugins: [require.resolve('./my-custom-plugin')]
  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
---


_November 02, 2023_

# Announcing Rspack 0.4

## 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), and custom [rules[].type](/config/module-rules#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`
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
  experiments: {
    rspackFuture: {
      disableTransformByDefault: true,
    },
  },
};
```

2. [target](/config/target) 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"
+        }
        }
        type: 'javascript/auto',
      },
    ],
  }
};
```

3. Removed non-webpack compatible [rules[].type](/config/module-rules#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](/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 ReactRefreshPlugin 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 ReactRefreshPlugin()
  ],
};
```

Checkout [here](/guide/tech/react#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#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).

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/rspack/html-rspack-plugin):

```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/rspack/copy-rspack-plugin).

For the original `builtins.minifyOptions`, we provide [SwcJsMinimizerRspackPlugin](/plugins/rspack/swc-js-minimizer-rspack-plugin):

```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) for migration, or completed according to the CLI prompts after upgrading to v0.4.0.



---
url: /blog/announcing-0-3.md
---


_August 24, 2023_

# Announcing Rspack 0.3

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

### `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,
                },
              },
            },
          },
        },
        type: 'javascript/auto',
      },
    ],
  },
});
```

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/optimization/profile).

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


_June 02, 2023_

# Announcing Rspack 0.2

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

### Plugin hooks

New hooks for plugins have been added.

Compiler hooks:

1. [beforeCompile](/api/plugin-api/compiler-hooks#beforecompile)
2. [afterCompile](/api/plugin-api/compiler-hooks#aftercompile)

Compilation hooks:

1. [optimizeModules](/api/plugin-api/compilation-hooks#optimizemodules)
2. [optimizeChunkModule](/api/plugin-api/compilation-hooks#optimizechunkmodules)
3. [finishModules](/api/plugin-api/compilation-hooks#finishmodules)
4. [chunkAsset](/api/plugin-api/compilation-hooks#chunkasset)

NormalModuleFactory hooks:

1. [beforeResolve](/api/plugin-api/normal-module-factory-hooks#beforeresolve)
2. [afterResolve](/api/plugin-api/normal-module-factory-hooks#afterresolve)
3. [ResolveForScheme](/api/plugin-api/normal-module-factory-hooks#resolveforscheme)

ContextModuleFactory hooks:

1. [beforeResolve](/api/plugin-api/context-module-factory-hooks#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 {
  // …
  experiments: {
    outputModule: true,
  },
  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

- Enabled realContentHash by default in production

  Details: https://github.com/web-infra-dev/rspack/pull/3338

- Modified the Extensions of Resolve

  Details: 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

## 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/en/) 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](https://modernjs.dev/doc-tools/) - 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.

> Welcome to visit the [Modern.js code repository](https://github.com/web-infra-dev/modern.js) and experience the above content.

### 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/tech/vue).

### 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.html) 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.
- [@suxin2017](https://github.com/suxin2017), 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
---


_March 06, 2023_

# Announcing Rspack 0.1

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)
- GitHub Repo: [github.com/web-infra-dev/rspack](https://github.com/web-infra-dev/rspack)



---
url: /contribute/architecture/builtin-plugin.md
---

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

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

# Building

Please see [prerequisites](./prerequisites) 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
---

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

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

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

# 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
```

## 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/optimization/profile#use-rsdoctor)

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

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

### 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_web_worker_template`**: Web Worker template plugin
- **`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_browser`**: Browser environment support providing browser-side implementations
- **`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

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



---
url: /contribute/development/releasing.md
---

# 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 following binary artifacts for the target platforms are built:

- x86_64-unknown-linux-gnu
- aarch64-unknown-linux-gnu
- x86_64-unknown-linux-musl
- aarch64-unknown-linux-musl
- i686-pc-windows-msvc
- x86_64-pc-windows-msvc
- aarch64-pc-windows-msvc
- x86_64-apple-darwin
- aarch64-apple-darwin

### 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. Generate the [GitHub release note](https://github.com/web-infra-dev/rspack/releases), and add highlights information.

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

# 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/config/test/testNamePattern) 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.

{/* If there are no suitable types, please follow the guidelines for [adding new test types](./test-advanced). */}

### 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/processor/normal.ts#L35) |
| 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/processor/config.ts#L51) |
| 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/processor/hot.ts#L86) |
| 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/processor/watch.ts#L99) |
| 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/processor/stats.ts#L190) |
| 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/processor/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/processor/diagnostic.ts#L71) |
| 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/processor/hash.ts#L53) |
| 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/processor/simple.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/processor/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/processor/error.ts#L84) |
| 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/processor/hook.ts#L190) |
| 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/processor/treeshaking.ts#L19) |
| 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/processor/builtin.ts#L27) |
| 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
---

# 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) 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 too large rspack.pftrace 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/9be47217b5179186b0825ca79990ab2808aa1a0f/packages/rspack-cli/src/utils/profile.ts#L219-L224) for more information.

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`:

- `perfetto`: The default value, generates a rspack.pftrace file conforming to the [`perfetto proto`](https://perfetto.dev/docs/reference/synthetic-track-event) format, which can be exported to perfetto for complex performance analysis
- `logger`: Outputs logs directly to the terminal, suitable for simple log analysis or viewing compilation processes in CI environments

You can specify the layer through the `RSPACK_TRACE_LAYER` environment variable:

```sh
RSPACK_TRACE_LAYER=logger
# or
RSPACK_TRACE_LAYER=perfetto
```

## Tracing output

You can specify the output location for traces:

- The default output for the `logger` layer is `stdout`
- The default output for the `perfetto` layer is `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
RSPACK_TRACE_LAYER=perfetto RSPACK_TRACE_OUTPUT=./perfetto.pftrace rspack dev
```

## 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 and output to terminal
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
---

# 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) 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) section below to learn about it.
7. Run `pnpm run lint:js` and `pnpm run lint:rs` to check the code style.
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
---

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




---
url: /misc/branding/license.md
---

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



---
url: /misc/faq.md
---


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

## Does Rspack plan to support React Server Components?

Rspack team is working on supporting React Server Components. Relevant PR: [#12012](https://github.com/web-infra-dev/rspack/pull/12012).



---
url: /misc/glossary.md
---


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

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

## 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)
- [CSS](/guide/tech/css)
- [JSON](/guide/tech/json)
- [rules[].type](/config/module-rules#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)

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

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

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

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



---
url: /misc/planning/future.md
---

import { DeprecationTable } from '@components/DeprecationTable';

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

## Future default behavior (Rspack future)

Rspack provides some experimental features in [experiments.rspackFuture](/config/experiments#experimentsrspackfuture). These features will become the default behavior in the future, but they are currently not default and need to be explicitly enabled in the configuration file.

## Deprecation

<DeprecationTable />



---
url: /misc/planning/roadmap.md
---

# Roadmap

This document provides an overview of the latest plans and progress for Rspack and the Rstack toolchain. It will be continuously updated as new versions are released.

> Last updated: 2025-10

## Rspack 2.0

We are developing Rspack 2.0 and Rsbuild 2.0, focusing on API and internal architecture improvements, performance optimization, adoption of modern web standards, and a better developer experience.

Key areas include:

- **Streamlined outputs and APIs**: Redesigning output structure and webpack-specific APIs for better clarity and simplicity, while maintaining compatibility.
- **Improved ESM output**: Enhancing ESM support and providing an out-of-the-box experience through Rsbuild and Rslib.
- **Built-in RSC support**: Inspired by tools like Parcel, offering built-in support for React Server Components.
- **More stable persistent cache**: Improving usability and reliability of persistent cache, with plans to enable it by default in development mode.
- **Enable Native watcher**: Using native watcher to reduce rebuild latency and improve HMR performance.
- **Core architecture optimization**: Refining the internal data flow to reduce memory usage and improve performance and maintainability.
- **Migration to pure ESM packages**: Converting all npm packages to pure ESM format and dropping Node.js 18 support.
- And more...

The first preview release is planned for **February 2026**. We will carefully review every breaking change to ensure a smooth upgrade path.

> Join the discussion on breaking changes here: 👉 [discussions/9270](https://github.com/web-infra-dev/rspack/discussions/9270)

## Rstack toolchain

We are building a unified JavaScript toolchain centered around Rspack — [Rstack](/guide/start/ecosystem#rstack).

The main focus areas across Rstack tools include:

- Rsbuild: Developing 2.0 alongside Rspack, focusing on performance and developer experience.
- Rslib: Integrating Rspack's new ESM output, aiming for a 1.0 release once the APIs stabilize.
- Rsdoctor: Expanding AI Agent support via MCP and adding new features such as tree-shaking analysis.
- Rspress: Developing v2.0 with major architecture, UI, and feature improvements.
- Rstest: Enhancing testing capabilities with browser mode and VS Code extension. See the [Rstest Roadmap](https://github.com/web-infra-dev/rstest/issues/85) for details.

## Remote cache

Rspack's caching system is evolving from memory cache to persistent cache, and we are actively exploring remote cache (portable cache).

This effort aims to make build caches shareable across different machines and environments, helping teams reduce redundant builds and improve efficiency.

## Enhanced ESM support

We are improving Rspack's ESM output and providing a seamless library-building experience through Rslib. This enables developers to build npm packages with better static analysis and tree-shaking support.

In parallel, we're extending Rspack's ESM capabilities for web applications, enabling applications to run natively as ESM in modern browsers.

## Performance improvements

We are continuously optimizing internal implementations — exploring more efficient concurrency models, better caching strategies, lower-overhead plugin communication, and various micro-optimizations.

## Community collaboration

Rspack has helped us solve many performance and efficiency challenges in real-world projects. We hope it can bring similar value to the broader community. We welcome collaborations with framework and tooling teams interested in Rspack integration — feel free to reach out for support.

## Webpack compatibility

Webpack provides a rich and diverse API. Rspack takes a progressive approach to compatibility, prioritizing high-usage loaders and plugins based on community feedback to ensure a smooth migration experience.

## Extending Rspack with Rust

Currently, higher-level tools and frameworks can integrate Rspack through its [JavaScript API](/api/javascript-api/index), which offers good extensibility. However, Rust-to-JavaScript communication introduces some overhead and limits performance.

We are developing a Rust extension system for Rspack to eliminate cross-language overhead. For more details, see the [Rspack 1.5 blog](/blog/announcing-1-5#extending-rspack-with-rust).



---
url: /misc/team/core-team.md
---

import { RandomMemberList } from '@components/RandomMemberList.tsx';

# 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

<RandomMemberList />

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



---
url: /misc/team/emeriti.md
---

import { RandomContributorsList } from '@components/RandomMemberList.tsx';

# 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

<RandomContributorsList />



---
url: /misc/team/join-us.md
---

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