Sass Plugin#

Use Sass as the CSS preprocessor, implemented based on sass-loader.

Quick Start#

Install Plugin#

You can install the plugin using the following command:

npm add @rsbuild/plugin-sass -D

Register Plugin#

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

import { pluginSass } from '@rsbuild/plugin-sass';

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

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

Options#

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

sassLoaderOptions#

Modify the config of sass-loader.

• Type: Object | Function
• Default:

const defaultOptions = {
  api: 'modern-compiler',
  implementation: require.resolve('sass-embedded'),
  sourceMap: rsbuildConfig.output.sourceMap.css,
};

• Example:

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

pluginSass({
  sassLoaderOptions: {
    sourceMap: true,
  },
});

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

pluginSass({
  sassLoaderOptions(config) {
    config.additionalData = async (content, loaderContext) => {
      // ...
    };
  },
});

exclude#

• Type: RuleSetCondition
• Default: undefined

Exclude some .sass or .scss files, they will not be transformed by sass-loader.

For example:

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

Modifying Sass Version#

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

pluginSass({
  sassLoaderOptions: {
    implementation: require('sass'),
  },
});

pluginSass({
  sassLoaderOptions: {
    implementation: require.resolve('sass'),
  },
});

Rsbuild defaults to using the latest modern-compiler API. If you are using an older version of Sass, please set the api option of sass-loader to legacy to avoid exceptions caused by version mismatches.

pluginSass({
  sassLoaderOptions: {
    api: 'legacy',
    implementation: require.resolve('sass'),
  },
});