Webpack has built-in CSS support, so no extra loaders are required to process the CSS generated by sass-loader - just enable experiments.css and set the module type to css/auto.
If you prefer the loader-based setup, install style-loader and css-loader via npm i style-loader css-loader and chain them with sass-loader instead.
sass-loader requires you to install either Dart Sass or Sass Embedded on your own (more documentation can be found below).
This allows you to control the versions of all your dependencies and to choose which Sass implementation to use.
Use the sass-loader with the built-in CSS support of webpack (the css/auto module type) to let webpack handle the generated CSS - it extracts styles into a separate file and injects them into the document.
Alternatively, you can chain the sass-loader with the css-loader and the style-loader to immediately apply all styles to the DOM, or with the mini-css-extract-plugin to extract it into a separate file.
Then add the loader to your webpack configuration. For example:
app.js
import "./style.scss";
style.scss
$body-color: red;body { color: $body-color;}
webpack.config.js
module.exports = { module: { rules: [ { test: /\.s[ac]ss$/i, // Lets webpack handle the generated CSS using its built-in CSS support, // `css/auto` also enables CSS modules for `*.module.scss` files type: "css/auto", use: [ // Compiles Sass to CSS "sass-loader", ], }, ], }, experiments: { // Enables the built-in CSS support of webpack css: true, },};
Finally run webpack via your preferred method (e.g., via CLI or an npm script).
[!NOTE]
All examples below use the built-in CSS support of webpack.
If you use css-loader and style-loader (or mini-css-extract-plugin) instead, remove the type and experiments options and put them before the sass-loader in the use array:
The sass-loader uses Sass's custom importer feature to pass every @use, @import and @forward request to the webpack resolving engine, so your webpack resolve configuration applies to stylesheets, and you can load Sass modules from node_modules:
@use "bootstrap";
How a request is resolved
For @use "theme" inside src/app.scss, the loader asks webpack for the following and takes the first hit:
the partial src/_theme.sass, src/_theme.scss, src/_theme.css
src/theme.sass, src/theme.scss, src/theme.css
theme as written, so aliases and package requests resolve
Directories resolve through their _index/index file. For @import only, the import-only files _theme.import.scss and theme.import.scss are tried before everything else.
Relative requests win over module ones, so @use "theme" behaves like @use "./theme" when both could match. Keeping both _theme.scss and theme.scss in one directory is ambiguous and Sass reports an error for it, so the order within a directory rarely matters.
What your resolve configuration controls
alias - applied to every request, and tried before node_modules
@use "@styles/theme" as *; // resolved by `resolve.alias`@use "abstracts" as *; // resolved by `resolve.modules` to `src/abstracts/_index.scss`
Some options are fixed to match Sass's own algorithm and can't be changed through resolve: the extensions are .sass, .scss and .css (so resolve.extensions doesn't apply here), mainFiles prefer _index/index, mainFields prefer sass and style over main, and conditionNames prefer the sass and styleexport conditions. Your own mainFields and conditionNames are kept after those.
Packages
A package request resolves through the sass and style conditions of its exports field, falling back to the sass, style and main fields. The pkg: URL scheme is supported as well:
@use "pkg:bootstrap";
When webpack can't resolve a request
The importer hands the request back to Sass, which then applies its own resolution - sassOptions.loadPaths, the SASS_PATH environment variable and any custom importer you configured.
Plain CSS files
Sass compiles @import "theme.css" to a plain CSS @import, so the loader leaves it in the output untouched - whatever handles the CSS afterwards (the built-in CSS support of webpack, css-loader, or the browser) decides what happens with it. @use "theme.css" includes the file's content instead, and is resolved like any other request:
@import "theme.css"; // stays `@import "theme.css";` in the output@use "theme.css"; // inlines the content of the file
The ~ prefix
Using ~ is deprecated and should be removed from your code, but we still support it for historical reasons.
Why can you remove it? The loader will first try to resolve @use as a relative path. If it cannot be resolved, then the loader will try to resolve it inside node_modules.
Prepending module paths with a ~ tells webpack to search through node_modules.
@use "~bootstrap";
It's important to prepend the path with only ~, because ~/ resolves to the home directory.
Webpack needs to distinguish between bootstrap and ~bootstrap because CSS and Sass files have no special syntax for importing relative files.
Writing @use "style.scss" is the same as @use "./style.scss";
Problems with url(...)
Since Sass implementations don't provide url rewriting, all linked assets must be relative to the output.
If webpack handles the generated CSS (i.e. the built-in CSS support or the css-loader), all URLs must be relative to the entry-file (e.g. main.scss).
If you're just generating CSS without letting webpack handle it, URLs must be relative to your web root.
You might be surprised by this first issue, as it is natural to expect relative references to be resolved against the .sass/.scss file in which they are specified (like in regular .css files).
Thankfully there are two solutions to this problem:
Add the missing URL rewriting using the resolve-url-loader. Place it before sass-loader in the loader chain.
Library authors usually provide a variable to modify the asset path. bootstrap-sass for example, has an $icon-font-path.
The special implementation option determines which implementation of Sass to use.
By default, the loader resolves the implementation based on your dependencies.
Just add the desired implementation to your package.json (sass or sass-embedded package) and install dependencies.
Example where the sass-loader uses the sass (dart-sass) implementation:
The charset option is true by default for dart-sass. We strongly discourage setting this to false because webpack doesn't support files other than utf-8.
[!NOTE]
The syntax option is scss for the scss extension, indented for the sass extension, and css for the css extension.
[!NOTE]
Options such as data and url are unavailable and will be ignored.
ℹ We strongly discourage changing the sourceMap option because sass-loader sets it automatically when the sourceMap option is true.
Please consult their respective documentation before using them:
Prepends Sass/SCSS code before the actual entry file.
In this case, the sass-loader will not override the data option but just prepend the entry's content.
This is especially useful when some of your Sass variables depend on the environment:
This can improve performance in some cases, though use it with caution because aliases and @import at-rules starting with ~ will not work.
You can pass your own importer to solve this (see Sass importer documentation).
Default: "auto" for sass (dart-sass) and sass-embedded
Allows you to switch between the modern and modern-compiler APIs. You can find more information here. The modern-compiler option enables the modern API with support for Shared Resources.
When "auto" is used, the loader picks "modern-compiler" whenever the implementation exposes initAsyncCompiler (i.e. recent versions of sass and sass-embedded) and falls back to "modern" otherwise. Combined with sass-embedded, this yields the best build performance out of the box.
[!NOTE]
Using modern-compiler and sass-embedded together significantly improves performance and decreases build time. They are now selected automatically by the default "auto" API.
[!NOTE]
The legacy Sass JS API is no longer supported. If you were using api: "legacy", please migrate to the modern API. See the Sass JS API docs to learn how to migrate.
We welcome all contributions!
If you're new here, please take a moment to review our contributing guidelines before submitting issues or pull requests.