[Documentation / DX Bug] spfx-web-build-rig silences Sass deprecation warnings globally — masking required migration work from developers

Target SharePoint environment

SharePoint Online

What SharePoint development model, framework, SDK or API is this about?

💥 SharePoint Framework

Developer environment

Windows, macOS, Linux

What browser(s) / client(s) have you tested

• not applicable

Additional environment details

• SPFx version: 1.23.0
• Node.js version: v22.x (only supported LTS for SPFx)
• @microsoft/spfx-web-build-rig: 1.23.0
• @rushstack/heft-sass-plugin: 1.3.8
• sass-embedded: 1.85.1
• @rushstack/heft: 1.2.17

Describe the bug / error

While upgrading an SPFx project from the gulp-based toolchain to Heft, I discovered that four Sass deprecation warnings are silenced by default at the rig level, with no documentation or build-time notice to the developer. The suppression applies globally — covering not just Microsoft's own dependencies but also developer-authored SCSS and any npm packages that import Sass files.

This creates a false sense of security: a project can compile cleanly with zero warnings while containing Sass code that will break when upstream Sass removes the deprecated features.

---

What I found

1. The rig silences four deprecation codes by default

node_modules/@microsoft/spfx-web-build-rig/profiles/default/config/sass.json:

"silenceDeprecations": ["mixed-decls", "import", "global-builtin", "color-functions"]

These map to active Sass deprecations — all four are currently on the removal path:

Code	What it suppresses	Deprecated since
import	@import rules	Sass 1.80.0
global-builtin	Global built-in functions (darken(), mix(), etc.)	Sass 1.80.0
color-functions	Global color functions instead of sass:color	Sass 1.79.0
mixed-decls	Declarations between or after nested rules	Sass 1.77.7

2. The suppression is inherited and cannot be removed by the project

Because Heft's config-file system uses append inheritance for arrays by default, a project's local config/sass.json can only add more codes to silence — it cannot remove the four codes the rig already sets. There is no documented way to opt out.

3. The suppression is global — it affects npm packages too

silenceDeprecations is passed directly to the Sass compiler as a global flag (silenceDeprecation in the protobuf request). This means the four codes are suppressed for all compiled code:

• Developer-authored .scss files
• SCSS imported from npm packages (e.g. component libraries, design systems)

The Sass API provides a separate quietDeps flag specifically for suppressing warnings from imported dependencies while keeping user-code warnings visible.

The heft-sass-plugin schema defines an ignoreDeprecationsInDependencies option that appears to address exactly this — and the rig's own sass.json even includes it as a commented-out example:

// "ignoreDeprecationsInDependencies": true,

However, tracing through all compiled plugin source files (SassPlugin.js, SassProcessor.js), the option is never read and never wired up to the Sass compiler's quietDeps flag. Setting ignoreDeprecationsInDependencies: true in a project's sass.json has no effect whatsoever.

This was confirmed by tracing the code path in SassProcessor.js → sass-embedded/dist/lib/src/compiler/utils.js:

// sass-embedded/dist/lib/src/compiler/utils.js
quietDeps: !!options?.quietDeps,              // always false — ignoreDeprecationsInDependencies is never forwarded here
silenceDeprecation: getDeprecationIds(options?.silenceDeprecations ?? []),  // receives the 4 rig codes globally

So there are effectively two separate issues: the global suppression itself, and an unimplemented option that gives the false impression a targeted fix is available.

Steps to reproduce

1. Create or migrate an SPFx project to use the Heft toolchain with @microsoft/spfx-web-build-rig
2. Keep or write .scss files that use @import, global color functions (darken(), mix(), lighten(), etc.), or global built-ins
3. Run heft build or heft test
4. Observe: build completes with zero Sass deprecation warnings
5. Inspect node_modules/@microsoft/spfx-web-build-rig/profiles/default/config/sass.json — the warnings are suppressed at rig level, not because the code is compliant

To confirm the suppression scope:
6. Set ignoreDeprecationsInDependencies: true in your local config/sass.json
7. Observe: no change in behavior — the option is defined in the schema but never implemented in the plugin

Expected behavior

Developers should receive Sass deprecation warnings for code they own and control — both their own authored SCSS and SCSS from third-party npm packages. The current behavior silences warnings globally, including for the highest-priority deprecation (@import) which has a confirmed removal commitment from the Sass team.

At minimum, the migration guide and the rig documentation should clearly state:

1. Which deprecation codes are silenced by default and why
2. That the suppression covers npm package dependencies too — not just Microsoft's internal code
3. That ignoreDeprecationsInDependencies in the schema is currently unimplemented
4. A migration checklist for each suppressed code (replacing @import with @use/@forward, migrating to sass:color, etc.)

This is especially impactful for developers migrating from the legacy gulp toolchain, who have never seen these warnings (older Sass predated most of these deprecations) and have no reason to know they need to act.

---

Suggested fixes (for engineering consideration)

Two separate issues need addressing:

1. Wire up ignoreDeprecationsInDependencies — the option is already defined in the plugin schema and referenced in the rig's config comments, but is never forwarded to the Sass compiler's quietDeps flag. Implementing this would immediately give developers a way to separate dependency noise from their own code's warnings.

2. Reconsider the rig's global silenceDeprecations — once ignoreDeprecationsInDependencies works, the rig could switch to using that instead of globally silencing specific codes. This would keep noise from Microsoft's own transitioning packages suppressed while restoring visibility into warnings from developer-authored SCSS and third-party npm packages.

Sass also provides a user-authored deprecation status precisely for this use case — the infrastructure already exists to make this distinction at the compiler level.