|
1 | 1 | # @rushstack/heft-sass-plugin |
2 | 2 |
|
3 | | -This is a Heft plugin for using sass-embedded during the "build" stage. |
4 | | -If `sass-embedded` is not supported on your platform, you can override the dependency via npm alias to use the `sass` package instead. |
| 3 | +A [Heft](https://heft.rushstack.io/) plugin that compiles SCSS/Sass files during the build phase. It uses [`sass-embedded`](https://www.npmjs.com/package/sass-embedded) under the hood and produces: |
| 4 | + |
| 5 | +- **TypeScript type definitions** (`.d.ts`) for CSS modules, giving you typed access to class names and `:export` values |
| 6 | +- **Compiled CSS files** (optional) in one or more output folders |
| 7 | +- **JavaScript shims** (optional) that re-export the CSS for consumption in CommonJS or ESM environments |
| 8 | + |
| 9 | +> If `sass-embedded` is not supported on your platform, you can substitute it with the [`sass`](https://www.npmjs.com/package/sass) package using an npm alias. |
5 | 10 |
|
6 | 11 | ## Links |
7 | 12 |
|
8 | | -- [CHANGELOG.md]( |
9 | | - https://github.com/microsoft/rushstack/blob/main/heft-plugins/heft-sass-plugin/CHANGELOG.md) - Find |
10 | | - out what's new in the latest version |
| 13 | +- [CHANGELOG.md](https://github.com/microsoft/rushstack/blob/main/heft-plugins/heft-sass-plugin/CHANGELOG.md) - Find out what's new in the latest version |
11 | 14 |
|
12 | 15 | Heft is part of the [Rush Stack](https://rushstack.io/) family of projects. |
| 16 | + |
| 17 | +--- |
| 18 | + |
| 19 | +## Setup |
| 20 | + |
| 21 | +### 1. Add the plugin to your project |
| 22 | + |
| 23 | +In your project's `package.json`: |
| 24 | + |
| 25 | +```json |
| 26 | +{ |
| 27 | + "devDependencies": { |
| 28 | + "@rushstack/heft": "...", |
| 29 | + "@rushstack/heft-sass-plugin": "..." |
| 30 | + } |
| 31 | +} |
| 32 | +``` |
| 33 | + |
| 34 | +### 2. Register the plugin in `config/heft.json` |
| 35 | + |
| 36 | +The `sass` task must run before `typescript` so that the generated `.d.ts` files are available when TypeScript compiles your project. |
| 37 | + |
| 38 | +```json |
| 39 | +{ |
| 40 | + "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json", |
| 41 | + "phasesByName": { |
| 42 | + "build": { |
| 43 | + "tasksByName": { |
| 44 | + "sass": { |
| 45 | + "taskPlugin": { |
| 46 | + "pluginPackage": "@rushstack/heft-sass-plugin" |
| 47 | + } |
| 48 | + }, |
| 49 | + |
| 50 | + "typescript": { |
| 51 | + "taskDependencies": ["sass"], |
| 52 | + "taskPlugin": { |
| 53 | + "pluginPackage": "@rushstack/heft-typescript-plugin" |
| 54 | + } |
| 55 | + } |
| 56 | + } |
| 57 | + } |
| 58 | + } |
| 59 | +} |
| 60 | +``` |
| 61 | + |
| 62 | +### 3. Create `config/sass.json` |
| 63 | + |
| 64 | +A minimal config uses all defaults: |
| 65 | + |
| 66 | +```json |
| 67 | +{ |
| 68 | + "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft-sass-plugin.schema.json" |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +A more complete setup that emits CSS and shims for both ESM and CommonJS: |
| 73 | + |
| 74 | +```json |
| 75 | +{ |
| 76 | + "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft-sass-plugin.schema.json", |
| 77 | + "cssOutputFolders": [ |
| 78 | + { "folder": "lib-esm", "shimModuleFormat": "esnext" }, |
| 79 | + { "folder": "lib-commonjs", "shimModuleFormat": "commonjs" } |
| 80 | + ], |
| 81 | + "fileExtensions": [".module.scss", ".module.sass"], |
| 82 | + "nonModuleFileExtensions": [".global.scss", ".global.sass"], |
| 83 | + "silenceDeprecations": ["mixed-decls", "import", "global-builtin", "color-functions"] |
| 84 | +} |
| 85 | +``` |
| 86 | + |
| 87 | +### 4. Add generated files to `tsconfig.json` |
| 88 | + |
| 89 | +Point TypeScript at the generated type definitions by including the `generatedTsFolder` in your `tsconfig.json`: |
| 90 | + |
| 91 | +```json |
| 92 | +{ |
| 93 | + "compilerOptions": { |
| 94 | + "paths": {} |
| 95 | + }, |
| 96 | + "include": ["src", "temp/sass-ts"] |
| 97 | +} |
| 98 | +``` |
| 99 | + |
| 100 | +## CSS Modules vs. global stylesheets |
| 101 | + |
| 102 | +The plugin distinguishes between two kinds of files based on their extension: |
| 103 | + |
| 104 | +**CSS modules** (extensions listed in `fileExtensions`, default: `.sass`, `.scss`, `.css`): |
| 105 | +- Processed with [`postcss-modules`](https://www.npmjs.com/package/postcss-modules) |
| 106 | +- Class names and `:export` values become properties in a generated TypeScript interface |
| 107 | +- The generated `.d.ts` exports a typed `styles` object as its default export |
| 108 | + |
| 109 | +**Global stylesheets** (extensions listed in `nonModuleFileExtensions`, default: `.global.sass`, `.global.scss`, `.global.css`): |
| 110 | +- Compiled to plain CSS with no module scoping |
| 111 | +- The generated `.d.ts` is a side-effect-only module (`export {}`) |
| 112 | +- Useful for resets, themes, and base styles |
| 113 | + |
| 114 | +**Partials** (filenames starting with `_`): |
| 115 | +- Never compiled to output files; they are only meant to be `@use`d or `@forward`ed by other files |
| 116 | + |
| 117 | +### Example: CSS module |
| 118 | + |
| 119 | +```scss |
| 120 | +// src/Button.module.scss |
| 121 | +.root { |
| 122 | + background: blue; |
| 123 | +} |
| 124 | +.label { |
| 125 | + font-size: 14px; |
| 126 | +} |
| 127 | +:export { |
| 128 | + brandColor: #0078d4; |
| 129 | +} |
| 130 | +``` |
| 131 | + |
| 132 | +Generated `temp/sass-ts/Button.module.scss.d.ts`: |
| 133 | + |
| 134 | +```typescript |
| 135 | +interface IStyles { |
| 136 | + root: string; |
| 137 | + label: string; |
| 138 | + brandColor: string; |
| 139 | +} |
| 140 | +declare const styles: IStyles; |
| 141 | +export default styles; |
| 142 | +``` |
| 143 | + |
| 144 | +In your TypeScript source: |
| 145 | + |
| 146 | +```typescript |
| 147 | +import styles from './Button.module.scss'; |
| 148 | +// styles.root, styles.label, styles.brandColor are all typed strings |
| 149 | +``` |
| 150 | + |
| 151 | +## Configuration reference |
| 152 | + |
| 153 | +All options are set in `config/sass.json`. Every option is optional. |
| 154 | + |
| 155 | +| Option | Default | Description | |
| 156 | +|---|---|---| |
| 157 | +| `srcFolder` | `"src/"` | Root directory that is scanned for SCSS files | |
| 158 | +| `generatedTsFolder` | `"temp/sass-ts/"` | Output directory for generated `.d.ts` files | |
| 159 | +| `secondaryGeneratedTsFolders` | `[]` | Additional directories to also write `.d.ts` files to (e.g. `"lib-esm"` when publishing typings alongside compiled output) | |
| 160 | +| `exportAsDefault` | `true` | When `true`, wraps exports in a typed default interface. When `false`, generates individual named exports (`export const className: string`). Note: `false` is incompatible with `cssOutputFolders`. | |
| 161 | +| `cssOutputFolders` | _(none)_ | Folders where compiled `.css` files are written. Each entry is either a plain folder path string, or an object with `folder` and optional `shimModuleFormat` (see below). | |
| 162 | +| `fileExtensions` | `[".sass", ".scss", ".css"]` | File extensions to treat as CSS modules | |
| 163 | +| `nonModuleFileExtensions` | `[".global.sass", ".global.scss", ".global.css"]` | File extensions to treat as global (non-module) stylesheets | |
| 164 | +| `excludeFiles` | `[]` | Paths relative to `srcFolder` to skip entirely | |
| 165 | +| `doNotTrimOriginalFileExtension` | `false` | When `true`, preserves the original extension in the CSS output filename. E.g. `styles.scss` → `styles.scss.css` instead of `styles.css`. Useful when downstream tooling needs to distinguish the source format. | |
| 166 | +| `preserveIcssExports` | `false` | When `true`, keeps the `:export { }` block in the emitted CSS. This is needed when a webpack loader (e.g. `css-loader`'s `icssParser`) must extract `:export` values at bundle time. Has no effect on the generated `.d.ts`. | |
| 167 | +| `silenceDeprecations` | `[]` | List of Sass deprecation codes to suppress (e.g. `"mixed-decls"`, `"import"`, `"global-builtin"`, `"color-functions"`) | |
| 168 | +| `ignoreDeprecationsInDependencies` | `false` | Suppresses deprecation warnings that originate from `node_modules` dependencies | |
| 169 | +| `extends` | _(none)_ | Path to another `sass.json` config file to inherit settings from | |
| 170 | + |
| 171 | +### CSS output folders and JS shims |
| 172 | + |
| 173 | +Each entry in `cssOutputFolders` can be a plain string (folder path only) or an object: |
| 174 | + |
| 175 | +```json |
| 176 | +{ |
| 177 | + "folder": "lib-esm", |
| 178 | + "shimModuleFormat": "esnext" |
| 179 | +} |
| 180 | +``` |
| 181 | + |
| 182 | +When `shimModuleFormat` is set, the plugin writes a `.js` shim alongside each `.css` file. For a CSS module, the shim re-exports the CSS: |
| 183 | + |
| 184 | +```js |
| 185 | +// ESM shim (shimModuleFormat: "esnext") |
| 186 | +export { default } from "./Button.module.css"; |
| 187 | + |
| 188 | +// CommonJS shim (shimModuleFormat: "commonjs") |
| 189 | +module.exports = require("./Button.module.css"); |
| 190 | +module.exports.default = module.exports; |
| 191 | +``` |
| 192 | + |
| 193 | +For a global stylesheet, the shim is a side-effect-only import: |
| 194 | + |
| 195 | +```js |
| 196 | +// ESM shim |
| 197 | +import "./global.global.css"; |
| 198 | +export {}; |
| 199 | + |
| 200 | +// CommonJS shim |
| 201 | +require("./global.global.css"); |
| 202 | +``` |
| 203 | + |
| 204 | +## Sass import resolution |
| 205 | + |
| 206 | +The plugin supports the modern `pkg:` protocol for importing from npm packages: |
| 207 | + |
| 208 | +```scss |
| 209 | +@use "pkg:@fluentui/react/dist/sass/variables"; |
| 210 | +``` |
| 211 | + |
| 212 | +The legacy `~` prefix is automatically converted to `pkg:` for compatibility with older stylesheets: |
| 213 | + |
| 214 | +```scss |
| 215 | +// These are equivalent: |
| 216 | +@use "~@fluentui/react/dist/sass/variables"; |
| 217 | +@use "pkg:@fluentui/react/dist/sass/variables"; |
| 218 | +``` |
| 219 | + |
| 220 | +## Incremental builds |
| 221 | + |
| 222 | +The plugin tracks inter-file dependencies (via `@use`, `@forward`, and `@import`) and only recompiles files that changed or whose dependencies changed. This makes `heft build --watch` fast even in large projects. |
| 223 | + |
| 224 | +## Plugin accessor API |
| 225 | + |
| 226 | +Other Heft plugins can hook into the Sass compilation pipeline via the `ISassPluginAccessor` interface: |
| 227 | + |
| 228 | +```typescript |
| 229 | +import { ISassPluginAccessor } from '@rushstack/heft-sass-plugin'; |
| 230 | + |
| 231 | +// In your plugin's apply() method: |
| 232 | +const sassAccessor = session.requestAccessToPlugin<ISassPluginAccessor>( |
| 233 | + '@rushstack/heft-sass-plugin', |
| 234 | + 'sass-plugin', |
| 235 | + '@rushstack/heft-sass-plugin' |
| 236 | +); |
| 237 | + |
| 238 | +sassAccessor.hooks.postProcessCss.tapPromise('my-plugin', async (css, filePath) => { |
| 239 | + // Transform CSS after Sass compilation but before it is written to cssOutputFolders |
| 240 | + return transformedCss; |
| 241 | +}); |
| 242 | +``` |
| 243 | + |
| 244 | +The `postProcessCss` hook is an `AsyncSeriesWaterfallHook` that passes the compiled CSS string and source file path through each tap in sequence. |
0 commit comments