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

# Loader

Rspack 内置了对 JavaScript、CSS、JSON、静态资源等模块类型的支持。

Loader 是一种模块转换器，它将各种类型的模块转换为 Rspack 支持的类型。通过使用不同类型的 loader，你可以扩展 Rspack 来处理额外的模块类型，例如 JSX、Markdown、Sass、Less 等。

当 Rspack 打包一个模块时，先通过 loader 对模块进行预处理，将它们转换为 Rspack 支持的模块类型，然后再根据 [rules\[\].type](https://rspack.rs/zh/config/module-rules.md#rulestype) 对模块进行后置处理。

## webpack loader 兼容

Rspack 允许你使用社区中绝大多数的 webpack loaders。查看 [awesome-rstack - Rspack loaders](https://github.com/rstackjs/awesome-rstack?tab=readme-ov-file#rspack-loaders) 发现社区提供的 loaders。

如果你发现有 Rspack 不支持的 loader，欢迎通过 [GitHub Issues](https://github.com/web-infra-dev/rspack/issues) 与我们交流。

## 编写 Loader

参考 [编写 Loader](https://rspack.rs/zh/api/loader-api/writing-loaders.md) 了解如何开发一个 Loader。

## 示例

### 使用 Less

你可以使用 [less-loader](https://github.com/webpack/less-loader) 对 `.less` 文件的内容做相应的转换：

```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) 可以将 Less 文件转换为 Rspack 支持的 CSS 模块类型，因此你可以设置 type 为 `'css'` 以指示 Rspack 使用原生支持的 CSS 策略进行后处理。

### 使用多个 Loader

你可以对特定的 [Rule](https://rspack.rs/zh/config/module-rules.md#rule) 匹配项使用多个 loader 进行链式处理，loader 的执行顺序为**从右往左**。

例如，你可以使用 [less-loader](https://github.com/webpack/less-loader) 完成 Less 到 CSS 类型之间的转换，并对转换后的源码使用 [postcss-loader](https://github.com/webpack/postcss-loader) 进行二次转换，并最终交给 Rspack 的 CSS 后处理器，完成进一步处理：

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

### 传递配置项

你可以使用 [rules\[\].use](https://rspack.rs/zh/config/module-rules.md#rulesuse) 给 loader 传递相关配置，例如：

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

### 使用自定义 Loader

你可以在 Rspack 中使用自定义 loader，下面我们会编写一个简单的 banner-loader 作为示例。

banner-loader 的作用是在每个模块的头部添加一个 banner 注释，例如添加一段 License 信息：

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

在项目的根目录新建一个 `banner-loader.js` 的文件，内容如下：

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

Loader 的第一个入参为文件的内容，我们可以在这里对文件内容进行处理，然后返回处理后的内容。编写完后，我们需要将这个 loader 使用 CommonJS 风格进行导出。

上述示例中，我们会在所有匹配的文件的头部添加一个 banner 注释，如果我们希望将这个行为匹配所有以 `js` 结尾的文件，我们可以这样配置：

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

更多关于 Loader API 的信息，请参考 [loader-api](https://rspack.rs/zh/api/loader-api/index.md)

### 使用内置 Loader

内置 Loader 在不损失 JS Loader 的可组合性的同时，提供了比 JS Loader 更优的性能。一些内置的 Loader 包括：

- [builtin:swc-loader](https://rspack.rs/zh/guide/features/builtin-swc-loader.md)
- [builtin:lightningcss-loader](https://rspack.rs/zh/guide/features/builtin-lightningcss-loader.md)

## 并行 Loader \{#parallel-loader}

Rspack 支持将 loader 放入 worker threads 中并行执行，可以更好地利用多核 CPU，提升构建性能。

要为 loader 启用并行执行，请在 [rules\[\].use](https://rspack.rs/zh/config/module-rules.md#rulesuse) 中设置 `parallel` 选项：

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

设置 `parallel: true` 会启用并行执行，并由 Rspack 自动选择合适的线程数量。

当同一条 Rule 下多个 loader 都开启了 `parallel` 选项，Rspack 会在同一个 worker 中按顺序依次运行这些 loader，直到遇到未启用 parallel 的 loader 或 Rust 实现的 builtin loader。这样可以在保证 loader 顺序的前提下最大化并行效率。

:::tip

- 启用并行执行时，`options` 必须是对象。即使 loader 不需要配置项，也必须显式设置 `options: {}`，省略 `options` 会导致配置错误。
- loader 的选项需要满足 [HTML structured clone algorithm](https://nodejs.org/api/worker_threads.html#portpostmessagevalue-transferlist)，否则会发送失败。
- 在 worker 模式下，`LoaderContext._compilation`、`LoaderContext._compiler`、`LoaderContext._module` 上的大多数方法不被支持。

:::

更多细节请参考 [rules\[\].use.parallel](https://rspack.rs/zh/config/module-rules.md#rulesuseparallel)。