Less Plugin#

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

Quick Start#

Install Plugin#

You can install the plugin using the following command:

npm add @rsbuild/plugin-less -D

Register Plugin#

You can register the plugin in the rsbuild.config.ts file:

import { pluginLess } from '@rsbuild/plugin-less';

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

After registering the plugin, you can import *.less or *.module.less files into the code without adding other configs.

Options#

If you need to customize the compilation behavior of Less, you can use the following configs.

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')],
  },
  implementation: require.resolve('less'),
  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: 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 rule.test option in Rspack.

For example:

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

exclude#

• Type: RuleSetCondition
• Default: undefined

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

For example:

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

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 doesn't 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.