docusaurus-plugin-sass

docusaurus-plugin-sass wires sass-loader into a Docusaurus site’s webpack build so global stylesheets and CSS Modules can be authored in Sass or SCSS instead of plain CSS. It is registered like any other Docusaurus plugin — added to the plugins array in docusaurus.config.js — and requires no further configuration beyond installing sass alongside it.

The plugin handles both plain .scss/.sass files (used for global styles, e.g. via customCss in @docusaurus/preset-classic) and .module.scss/.module.sass files (compiled as CSS Modules with content-hashed class names in production and readable names in development), while automatically toggling source maps based on NODE_ENV. A bundled .d.ts file adds TypeScript declarations for importing Sass/SCSS modules.

What You Get

• A single-line addition to docusaurus.config.js’s plugins array that enables Sass/SCSS across the whole site
• Support for both global stylesheets (via customCss) and scoped CSS Modules (*.module.scss/*.module.sass)
• Automatic dev/production behavior — readable class names and source maps in development, hashed class names and no source maps in production
• TypeScript module declarations (docusaurus-plugin-sass.d.ts) so .scss/.sass imports type-check out of the box
• Compatibility with Docusaurus Faster (the Rust-based build pipeline) as well as the classic webpack build

Common Use Cases

• Migrating an existing Docusaurus site’s custom theme CSS to Sass for variables, nesting, and mixins
• Scoping component-level styles with Sass CSS Modules inside custom React components used in a Docusaurus site
• Sharing Sass variables/mixins across a documentation site’s theme without duplicating plain CSS
• Passing custom sass-loader options (e.g. additional include paths) through the plugin’s options object

Under The Hood

Architecture The plugin exports a single factory function (module.exports = function(_, {id, ...options})) that returns a Docusaurus plugin object exposing a name and a configureWebpack hook. That hook receives Docusaurus’s isServer flag and its utils (specifically getStyleLoaders), and returns a webpack module rule targeting .sass/.scss files with a oneOf branch: files matching *.module.s[ca]ss get CSS Modules treatment (hashed class names in production, readable ones in development, exportOnlyLocals mirroring isServer) layered on top of Docusaurus’s own style-loader stack, while all other Sass/SCSS files skip module treatment. Both branches terminate in sass-loader, with sourceMap toggled by NODE_ENV. There is no server-side or client-side runtime code — the entire plugin is a build-time webpack configuration shim.

Tech Stack The only runtime dependency is sass-loader (^16.0.2); @docusaurus/core (^2.0.0-beta || ^3.0.0-alpha) and sass (^1.30.0, i.e. Dart Sass) are peer dependencies supplied by the consuming project. The package ships as plain CommonJS with no build step, plus a hand-written .d.ts for TypeScript module declarations. CI is two GitHub Actions workflows (test.yml for running tests, npm-publish.yml for release automation on tag push).

Code Quality A single test file (test/docusaurus-plugin-sass.test.js) uses Node’s built-in node:test/node:assert with t.mock.fn to stub Docusaurus’s getStyleLoaders utility, covering both the module and plain branches across development and production NODE_ENV, and the exportOnlyLocals toggle for server vs. client builds. There is no external test framework, no linter configuration in the repo, and the implementation itself is plain JavaScript (typed only at the consumer-facing .d.ts boundary). Error handling is minimal by design — the plugin is declarative webpack config, not runtime logic with failure paths to guard.

API Design Integration is a single entry in the plugins array, matching the exact convention every other Docusaurus plugin uses, so there is effectively zero learning curve for anyone already working in the Docusaurus ecosystem. Options passed to the plugin flow straight through to sass-loader with no additional wrapping, and CSS Modules activate purely by filename convention (.module.scss), mirroring Create React App’s convention. TypeScript support is a one-line addition to tsconfig.json’s types array. The tradeoff for that minimal surface is that it does exactly one thing — there is no configuration for excluding paths, custom rule ordering, or non-webpack builds beyond the noted Docusaurus Faster compatibility.