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,
  sassOptions: {
    quietDeps: true,
    silenceDeprecations: api === 'legacy' ? ['legacy-js-api'] : undefined,
  },
};

• 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: RuleSetCondition
• Default: /\.s(?:a|c)ss$/
• Version: >= 1.1.0

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

For example:

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

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

Practices#

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

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

Ignore Sass Deprecation Warnings#

Sass uses warning logs to notify you of deprecated usages that will be removed in future major releases of Sass. It is recommended to make changes as suggested by the logs. If you do not want to see these logs, you can ignore these 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:

You can suppress the @import warning with the following configuration:

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