#Sass plugin

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

#Quick start

#Install plugin

Run the following command:

npm add @rsbuild/plugin-sass -D

yarn add @rsbuild/plugin-sass -D

pnpm add @rsbuild/plugin-sass -D

bun add @rsbuild/plugin-sass -D

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

#Register plugin

Register the plugin in Rsbuild config:

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

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

After registration, you can import *.scss, *.sass, *.module.scss, or *.module.sass files without additional config.

#Options

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

#sassLoaderOptions

Modify the config of sass-loader.

• Type: Object | Function

• Default: Uses sass-embedded with the modern compiler API and suppresses dependency and import deprecation warnings.

• 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) => {
      // ...
    };
  },
});

#include

• Type: Rspack.RuleSetCondition
• Default: /\.s(?:a|c)ss$/

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

For example:

pluginSass({
  include: /\.custom\.scss$/,
});

#exclude

• Type: Rspack.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/,
});

#rewriteUrls

• Type: boolean
• Default: true
• Version: >= 1.2.0

Whether to use resolve-url-loader to rewrite URLs.

When enabled, resolve-url-loader allows you to write relative URLs in your Sass files that are correctly resolved from the current Sass file's location, rather than being relative to the Sass entry file (e.g. main.scss).

If you set this option to false, the build performance will be improved, but Rsbuild will use the native URL resolution of Sass, which means all URLs must be relative to the Sass entry file.

pluginSass({
  rewriteUrls: false,
});

#Practices

#Modify Sass implementation

Dart Sass is available through sass and sass-embedded. The older node-sass implementation has reached end of life.

Rsbuild uses the sass-embedded version included with the plugin by default. This package provides a JavaScript API for the native Dart Sass executable.

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

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

#Select Sass API

Rsbuild uses the modern-compiler JavaScript API by default.

If a custom importer or function still depends on Sass's legacy JavaScript API, temporarily set sass-loader's api option to legacy:

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

This option changes the JavaScript integration API. It does not restore removed Sass language features.

#Ignore Sass deprecation warnings

Sass uses warning logs to highlight deprecated patterns that will be removed in future major releases. We recommend updating your code according to these warnings. If you do not want to see them, you can ignore the warnings by using the silenceDeprecations option in Sass.

For example, @import has been deprecated in Sass. If you use this syntax, Sass will output the following prompt:

Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.

More info and automated migrator: https://sass-lang.com/d/import

 0 | @import './b.scss';

@rsbuild/plugin-sass adds the following configuration by default to silence the @import warning, if you need to silence other deprecated warnings, you can use the same method.

pluginSass({
  sassLoaderOptions: {
    sassOptions: {
      silenceDeprecations: ['import'],
    },
  },
});

For more information, see Sass Deprecations.

#Configure multiple Sass plugins

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

For example:

export default {
  plugins: [
    pluginSass({
      exclude: /\.another\.scss$/,
    }),
    pluginSass({
      include: /\.another\.scss$/,
      sassLoaderOptions: {
        // some custom options
      },
    }),
  ],
};