SPFx scaffold template includes deprecated @import of Fluent UI SCSS variables — should be removed and documented

[StfBauer]

Environment

Target SharePoint environment: SharePoint Online

SharePoint development model: SharePoint Framework

Developer environment: macOS / Windows

Browser / client: Not applicable — this is a build-time issue

Version details:

• SPFx: 1.23 (tilde form reproducible through generator 1.22.2)
• Generator: @microsoft/generator-sharepoint
• Node.js: 22.x
• sass-embedded: 1.85.1 (Dart Sass 1.85.1, via @rushstack/heft-sass-plugin@1.3.8 / @microsoft/spfx-web-build-rig@1.23.0)
• @fluentui/react: ^8.x

---

Bug Description

Every SPFx web part scaffolded by @microsoft/generator-sharepoint includes the following line in the generated .module.scss file (exact form varies by generator version):

/* SPFx generator ≤ 1.22.2 — tilde form (webpack-era convention) */
@import '~@fluentui/react/dist/sass/References.scss';

/* SPFx generator 1.23+ — pkg: form (current scaffold) */
@import 'pkg:@fluentui/react/dist/sass/References.scss';

Both forms should be removed from the scaffold template. There are four compounding problems, none of which are currently mentioned in the SPFx documentation.

---

Problem 1 — @import is deprecated in Dart Sass (since 1.80.0, removal in 3.0.0)

The Sass team officially deprecated the @import rule in Dart Sass 1.80.0 (October 17, 2024). It is scheduled for removal in Dart Sass 3.0.0, no sooner than October 2026.

SPFx 1.23 ships sass-embedded version 1.85.1 (Dart Sass 1.85.1) via @rushstack/heft-sass-plugin@1.3.8. Every SPFx project built today is already running on a Dart Sass version where @import is deprecated.

The SPFx Heft build rig (@microsoft/spfx-web-build-rig) suppresses this warning by silencing four deprecation codes in its default sass.json:

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

Every developer building an SPFx project today is using deprecated Sass syntax without any warning. When silenceDeprecations can no longer suppress these warnings in Dart Sass 3.0, all scaffolded projects will need migration.

---

Problem 2 — _References.scss itself is entirely written with deprecated Sass syntax

Even if a developer migrates their own @import to the modern @use syntax, the @fluentui/react@8.x SCSS library it points to is itself entirely built on deprecated patterns.

Across node_modules/@fluentui/react/dist/sass/:

• 62 @import statements across all SCSS files (_References.scss alone uses @import for 37 partials)
• ~200+ !default variable declarations that rely on @import's deprecated global scope (e.g. $ms-color-themePrimary: #... !default;)
• Zero @use or @forward statements — the library has never been migrated to the Sass module system

There is no clean migration path for consumers. Changing @import to @use in your own code will not work because the library itself uses @import-only patterns internally — the !default variable system depends on @import's global scope and breaks under @use namespacing.

The library would need a full rewrite by the Fluent UI team to support @use. Since @fluentui/react v8 is in maintenance mode, this is not going to happen. The entire dist/sass/ SCSS variable approach is a dead end.

---

Problem 3 — The ~ (tilde) prefix was never documented or announced as changed

Prior to generator 1.23 (SPFx 1.16 through 1.22.2), the scaffold generated:

@import '~@fluentui/react/dist/sass/References.scss';

The ~ prefix is a webpack sass-loader convention — not native Sass syntax. It was never valid in SPFx's build pipeline, which has always called the Sass compiler directly (first via gulp-core-build-sass, then via heft-sass-plugin) — never through webpack sass-loader.

Both toolchains implemented a custom resolver that silently accepted tilde imports. The current @rushstack/heft-sass-plugin rewrites them in a preprocessing step before Sass ever processes the file, via a regex in SassProcessor.ts:

// rewrites: @import '~@fluentui/react/...' → @import 'pkg:@fluentui/react/...'
const importTildeRegex = /^(\s*@(?:import|use|forward)\s*)('~(?:[^']+)'|"~(?:[^"]+)")/gm;

This rewrite is entirely silent. There is no documentation anywhere — not in the migrate gulp → heft guide, not in the Configure Sass docs, not in the heft-sass-plugin CHANGELOG — that ever told developers to update ~@fluentui/... to pkg:@fluentui/.... Projects that upgraded from older SPFx versions continued to compile only because of this undocumented silent rewrite. Developers who hand-wrote or copied tilde imports from old documentation still have them in production today with no idea they are depending on a silent workaround.

---

Problem 4 — No forward-compatible SCSS path exists

@fluentui/react v8 is in maintenance mode. Fluent UI v9 (@fluentui/react-components) uses CSS-in-JS via @griffel/react and provides no dist/sass/ folder. Note: Fluent UI v9 is not currently supported in SPFx (SPFx is on React 17; v9 requires React 18+). However, when React 18 support eventually arrives in SPFx, any project relying on @fluentui/react SCSS variables will have no migration path.

The runtime alternative — CSS Custom Properties (var(--bodyText), var(--themePrimary), etc.) — is already available in all SPFx projects today through SharePoint's theme injection system and requires no SCSS import whatsoever.

---

Steps to Reproduce

1. Scaffold a new SPFx web part with yo @microsoft/sharepoint (generator 1.23 / SPFx 1.23)
2. Open the generated src/webparts/<name>/components/<Name>.module.scss
3. Observe @import 'pkg:@fluentui/react/dist/sass/References.scss'; on line 1
4. Run npm run build — it succeeds with no warnings
5. Open node_modules/@microsoft/spfx-web-build-rig/profiles/default/config/sass.json — observe "silenceDeprecations": ["mixed-decls", "import", "global-builtin", "color-functions"]
6. Open node_modules/@fluentui/react/dist/sass/_References.scss — observe it contains 37 @import statements and zero @use/@forward

---

Expected Behavior

• The scaffold template should not include @import 'pkg:@fluentui/react/dist/sass/References.scss'; — or any tilde equivalent — by default
• If the import is intentionally included, the documentation should explain: (a) that @import is deprecated in the current bundled Dart Sass version, (b) that the rig is silencing this deprecation, and (c) that there is no migration path to @use because the library itself is not compatible
• The migrate gulp → heft guide should document the silent ~ → pkg: rewrite so existing projects know to proactively update their imports
• The Using Fluent UI in SharePoint Framework docs should mark the SCSS variable approach as deprecated and recommend CSS Custom Properties as the forward-compatible alternative

---

Related Issues

• sp-dev-docs#8945 — New scaffolded projects contain phantom dependencies (pnpm)
• sp-dev-docs#8939 — Can't find stylesheet to import
• sp-dev-docs#8916 — SASS multi-issue in SPFx
• microsoft/fluentui#34043 — Missing dist folder breaks builds
• Sass @import is Deprecated — Official Sass deprecation announcement (Oct 17, 2024)
• rushstack SassProcessor.ts — tilde rewrite source

[Ashlesha-MSFT]

we were able to reproduce this on our end.

Repro confirmed - Node.js 22.20.0 · @microsoft/generator-sharepoint@1.23.0-rc.1

All four problems outlined in the description are verified:

1. @import 'pkg:@fluentui/react/dist/sass/References.scss' is present in every freshly scaffolded web part
2. The bundled Dart Sass (1.85.1) deprecates @import, but the rig's silenceDeprecations: ["import", ...] hides all warnings — developers see nothing
3. @fluentui/react@8.x dist/sass has 73 @import statements, 201 !default declarations, and zero @use/@forward — no migration path to the Sass module system exists
4. SassProcessor.js silently rewrites legacy ~@fluentui/... tilde imports to pkg:@fluentui/... with no documentation

We are tracking this internally and will raise it with the engineering team via our internal ADO backlog. We'll update this issue once triage is complete and next steps are determined.

Thanks again for the thorough investigation and related issue links — very helpful for scoping the fix.