#Less plugin

Use Less as the CSS preprocessor, implemented based on less-loader.

#Quick start

#Install plugin

Run the following command:

npm add @rsbuild/plugin-less -D

yarn add @rsbuild/plugin-less -D

pnpm add @rsbuild/plugin-less -D

bun add @rsbuild/plugin-less -D

deno add npm:@rsbuild/plugin-less -D

#Register plugin

Register the plugin in Rsbuild config:

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

• Type: Object | Function
• Default:

const defaultOptions = {
  lessOptions: {
    javascriptEnabled: true,
    paths: [path.join(rootPath, 'node_modules')],
  },
  sourceMap: rsbuildConfig.output.sourceMap.css,
};

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

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.

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

#include

• Type: Rspack.RuleSetCondition
• Default: /\.less$/
• Version: >= 1.1.0

Include some .less files, they will be transformed by less-loader. The value is the same as the rules[].test option in Rspack.

For example:

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

#exclude

• Type: Rspack.RuleSetCondition
• Default: undefined

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

For example:

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.

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. Otherwise, transmission will fail. For example, functions cannot be passed as options. See Rspack - Rule.use.parallel 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.

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:

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