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

#Compatibility with webpack loaders

Rspack allows you to use most webpack loaders in the community. See awesome-rstack - 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.

#Writing loaders

Refer to Writing loaders to learn how to develop a loader.

#Example

#Using Less

You can use less-loader to transform the contents of the .less file accordingly.

export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          {
            loader: 'less-loader',
          },
        ],
        type: 'css',
      },
    ],
  },
};

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 match, with the loaders executed in right-to-left order.

For example, you can use less-loader to do the transformation between Less to CSS types and 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.

export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          {
            loader: 'postcss-loader',
          },
          {
            loader: 'less-loader',
          },
        ],
        type: 'css',
      },
    ],
  },
};

#Passing configuration items

You can use rules[].use to pass the relevant configuration to the loader, for example:

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:

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

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:

export default {
  module: {
    rules: [
      {
        test: /\.js$/,
        loader: './banner-loader.js',
      },
    ],
  },
};

For details, you can refer to loader-api

#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
• builtin:lightningcss-loader

#Parallel loader

Rspack supports running loaders in worker threads for parallel execution, which can better utilize multi-core CPUs and improve overall build performance.

To enable parallel execution for a loader, set the parallel option in rules[].use:

export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          {
            loader: 'less-loader',
            parallel: true,
            options: {},
          },
        ],
        type: 'css',
      },
    ],
  },
};

Setting parallel: true enables parallel execution with an automatically chosen number of worker threads.

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 the loader execution order while maximizing parallel efficiency.

For more details, see rules[].use.parallel.