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

# Less plugin


[Source Code](https://github.com/web-infra-dev/rsbuild/tree/main/packages/plugin-less)

Use [Less](https://lesscss.org/) as the CSS preprocessor, implemented based on [less-loader](https://github.com/webpack/less-loader).

## Quick start

### Install plugin

Run the following command:


```sh [npm]
npm add @rsbuild/plugin-less -D
```

```sh [yarn]
yarn add @rsbuild/plugin-less -D
```

```sh [pnpm]
pnpm add @rsbuild/plugin-less -D
```

```sh [bun]
bun add @rsbuild/plugin-less -D
```

```sh [deno]
deno add npm:@rsbuild/plugin-less -D
```

### Register plugin

Register the plugin in Rsbuild config:

```ts title="rsbuild.config.ts"
import { pluginLess } from '@rsbuild/plugin-less';

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

After registration, you can import `*.less` or `*.module.less` files without additional config.

## Options

To customize the compilation behavior of Less, use the following options.

### lessLoaderOptions

You can modify the config of [less-loader](https://github.com/webpack/less-loader) via `lessLoaderOptions`.

- **Type:** `Object | Function`
- **Default:**

```js
const defaultOptions = {
  lessOptions: {
    javascriptEnabled: true,
    paths: [path.join(rootPath, 'node_modules')],
  },
  sourceMap: false, // Controlled by output.sourceMap
};
```

- **Example:**

If `lessLoaderOptions` is an object, it is merged with the default config through `Object.assign` in a shallow way. It should be noted that `lessOptions` is merged through deepMerge in a deep way.

```js
pluginLess({
  lessLoaderOptions: {
    lessOptions: {
      javascriptEnabled: false,
    },
  },
});
```

If `lessLoaderOptions` is a function, the default config is passed as the first parameter, which can be directly modified or returned as the final result.

```js
pluginLess({
  lessLoaderOptions(config) {
    config.lessOptions = {
      javascriptEnabled: false,
    };
  },
});
```

:::tip
The `lessLoaderOptions.lessOptions` config is passed to Less. See the [Less documentation](https://lesscss.org/usage/#less-options) for all available options.
:::

### include

- **Type:** [Rspack.RuleSetCondition](https://rspack.rs/config/module-rules#condition)
- **Default:** `/\.less$/`

Include some `.less` files, they will be transformed by `less-loader`. The value is the same as the [rules\[\].test](https://rspack.rs/config/module-rules#rulestest) option in Rspack.

For example:

```ts
pluginLess({
  include: /\.custom\.less$/,
});
```

### exclude

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

Exclude some `.less` files, they will not be transformed by `less-loader`.

For example:

```ts
pluginLess({
  exclude: /some-folder[\\/]foo\.less/,
});
```

### parallel

- **Type:** `boolean`
- **Default:** `false`
- **Version:** Added in v1.4.0

Whether to compile Less modules in parallel using worker threads. When enabled, Less modules are processed across multiple worker threads, reducing pressure on the main thread and improving overall build performance when compiling large numbers of Less modules.

```ts
pluginLess({
  parallel: true,
});
```

> This feature is based on Rspack's parallel loader. Options transferred to worker threads must comply with the [HTML structured clone algorithm](https://nodejs.org/api/worker_threads.html#portpostmessagevalue-transferlist). Otherwise, transmission will fail. For example, functions cannot be passed as options. See [Rspack - Rule.use.parallel](https://rspack.rs/config/module-rules#rulesuseparallel) for more details.

## Modifying Less version

In some scenarios, if you need to use a specific version of Less instead of the built-in Less v4 in Rsbuild, you can install the desired Less version in your project and set it up using the `implementation` option of the `less-loader`.

```js
pluginLess({
  lessLoaderOptions: {
    implementation: require('less'),
  },
});
```

## Practices

### Configure multiple Less plugins

By using the `include` and `exclude` options, you can register multiple Less plugins and specify different options for each plugin.

For example:

```ts
export default {
  plugins: [
    pluginLess({
      exclude: /\.another\.less$/,
    }),
    pluginLess({
      include: /\.another\.less$/,
      lessLoaderOptions: {
        // some custom options
      },
    }),
  ],
};
```

## FAQ

### Division in Less file does not work?

The built-in Less version for `@rsbuild/plugin-less` is v4. Compared to v3, there are some differences in the division syntax in Less v4:

```less
// Less v3
.math {
  width: 2px / 2; // 1px
  width: 2px ./ 2; // 1px
  width: (2px / 2); // 1px
}

// Less v4
.math {
  width: 2px / 2; // 2px / 2
  width: 2px ./ 2; // 1px
  width: (2px / 2); // 1px
}
```

The division syntax in Less can be modified through configuration. For more details, see [Less - Math](https://lesscss.org/usage/#less-options-math).