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/,
});

Custom Sass#

Sass Implementation#

Sass provides several implementations, including sass, sass-embedded, and node-sass.

Rsbuild uses the latest sass-embedded implementation by default. sass-embedded is a JavaScript wrapper around the native Dart Sass executable, providing a consistent API and optimal performance.

If you need to use a different Sass implementation instead of the built-in sass-embedded included in Rsbuild, you can install the preferred Sass implementation in your project and specify it using the sass-loader's implementation option.

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

Sass API#

Rsbuild uses the latest modern-compiler API by default. If you rely on the legacy API of Sass, you can set the api option of the sass-loader to legacy to maintain compatibility with some deprecated Sass syntax.

pluginSass({
  sassLoaderOptions: {
    api: 'legacy',
  },
});