sass-loader

sass-loader is the official webpack loader for compiling Sass and SCSS source files to CSS as part of a webpack build. It sits ahead of css-loader and style-loader (or webpack’s built-in css/auto module type) in the module pipeline, resolving Sass @use, @import, and @forward requests through webpack’s own module resolution so stylesheets can pull in packages from node_modules the same way JavaScript modules do.

The loader doesn’t bundle a Sass compiler itself - it detects and calls into whichever implementation is installed, preferring sass-embedded and falling back to sass (Dart Sass), and exposes options for source maps, prepended data, and custom Sass options so teams can match their existing Sass tooling exactly.

What You Get

• Webpack-native Sass compilation - runs Sass/SCSS files through Dart Sass or Sass Embedded and emits CSS webpack can pass on to css-loader or its built-in css/auto handling.
• Automatic implementation resolution - detects whichever of sass-embedded or sass is installed in the project and prefers the faster embedded binary when both are present.
• Webpack-aware @use/@import/@forward resolution - hands every Sass import to webpack’s resolver so resolve.alias, resolve.modules, and package exports conditions apply to stylesheets.
• Source map support - normalizes Sass-generated source maps to webpack’s expected format so browser devtools point back to the original .scss source.

Common Use Cases

• Compiling component stylesheets in a webpack app - a .scss file per component is compiled to CSS during the webpack build without a separate Sass CLI step.
• Consuming Sass-authored design systems from node_modules - @use “bootstrap” or a design-system package resolves through webpack’s own module resolution instead of relative Sass includes.
• Piping generated CSS into style-loader or mini-css-extract-plugin - sass-loader sits earliest in the loader chain, handing plain CSS off to whichever downstream loader injects or extracts styles.
• Passing per-build Sass variables via additionalData - injecting environment- or theme-specific SCSS variables at the top of every compiled file without editing source.

Under The Hood

Architecture sass-loader is a single-function webpack loader (src/index.js) wrapped by a large utilities module (src/utils.js, roughly 900 lines) that owns nearly every concern: resolving which Sass implementation to load (getSassImplementation), building the options object handed to the compiler (getSassOptions), constructing a webpack-aware Sass importer (getModernWebpackImporter) that bridges Sass’s import resolution to webpack’s own resolver via getWebpackResolver/startResolving, selecting between the modern and legacy compile APIs (getCompileFn), and post-processing output (source map normalization, BOM removal, error wrapping via errorFactory). The loader itself is a thin orchestrator: it fetches options via this.getOptions, awaits the implementation, options, and importer construction, calls the resolved compile function, and pushes results and dependencies back through webpack’s loader context (this.addDependency, callback). This function-per-concern shape inside one utils module, with no classes or DI container, is simple to trace, but it means anything that changes the webpack-Sass resolution bridge has to be understood as one unit rather than a swappable dependency.

Tech Stack The package ships as a single ESM source module built to both ESM and CJS output (dist/esm, dist/cjs) via Babel, plus a separate tsc pass that emits only .d.ts type declarations into types/ from JSDoc-annotated source - there is no TypeScript source, just typed JS. It has zero runtime dependencies in package.json; Sass itself (sass and/or sass-embedded), webpack, and optionally @rspack/core are all peerDependencies, kept genuinely optional via peerDependenciesMeta. Dev tooling is a modern JS toolchain: an ESLint 9 flat config extending eslint-config-webpack, Prettier, cspell for spell-checking, Husky and lint-staged for pre-commit hooks, and Changesets for versioned releases. Tests exercise real Sass compilation against Dart Sass, Sass Embedded, bootstrap-sass, Bootstrap 4/5, Foundation, and Material Components Web installed as devDependencies, run through webpack itself using memfs for an in-memory filesystem.

Code Quality Tests live under test/ as ten *.test.js suites (loader, resolver, options variants, source maps, CJS interop, validation) using Node’s built-in node:test runner with custom snapshot machinery rather than a third-party framework like Jest or Vitest - a deliberate choice that keeps sass-loader’s own test dependencies minimal. Coverage is collected via Node’s experimental test coverage flag and reported as lcov, and CI plus a dependency-review workflow gate merges. Options are validated at runtime via schema-utils against a JSON schema, so bad user options fail loudly at loader init rather than deep inside Sass compilation. Errors from the Sass compiler are wrapped through a dedicated error factory rather than surfaced raw, giving webpack a consistent error shape. Naming is consistent camelCase throughout, JSDoc typedefs stand in for TypeScript source types, and the flat ESLint config plus a dedicated spelling lint step keep style and docs quality enforced pre-commit.

What Makes It Unique sass-loader’s most distinctive technical choice is bridging Sass’s own @use/@import/@forward resolution into webpack’s module resolver rather than relying on Sass’s file-system-only load paths: its modern webpack importer constructs a custom Sass importer whose hooks call back into webpack’s resolver factory, so aliases, extra module directories, and even package.json exports/sass/style conditions apply uniformly to stylesheets and JavaScript. It also transparently supports two independent Sass implementations - Dart Sass and the newer, faster Sass Embedded - behind one option surface, auto-preferring the embedded binary without users needing to change loader config when they upgrade. Neither idea is unique to sass-loader in the abstract, but implementing webpack-resolver-backed Sass imports as a first-class, zero-config default is a meaningfully more sophisticated integration than a typical wrapper loader that just shells out to a CLI.