Unmet peer dependency: @rushstack/heft@^0.71.1 required by heft-sass-plugin but 1.1.2 is installed

[nick-pape]

Summary

rush update reports an unmet peer dependency for @rushstack/heft in the build infrastructure. @rushstack/heft-sass-plugin@0.15.24 (bundled in @microsoft/spfx-web-build-rig@1.22.2) requires @rushstack/heft@^0.71.1, but the build rig actually ships with @rushstack/heft@1.1.2.

Root Cause

The dependency chain is:

1. Example projects use @microsoft/spfx-web-build-rig@1.22.2 as their build rig
2. The build rig depends on @rushstack/heft-sass-plugin@0.15.24
3. @rushstack/heft-sass-plugin@0.15.24 declares peerDependencies: { "@rushstack/heft": "^0.71.1" }
4. The build rig also depends on @rushstack/heft@1.1.2 (via @microsoft/spfx-heft-plugins@1.22.2)
5. heft@1.1.2 does not satisfy the ^0.71.1 range (semver ^0.71.1 means >=0.71.1 <0.72.0, and 1.1.2 is outside this range)

Affected Examples

This affects ace-data-visualization (and potentially any project using @microsoft/spfx-web-build-rig with sass support):

../../examples/ace-data-visualization
├─┬ @microsoft/spfx-web-build-rig 1.22.2
│ └─┬ @rushstack/heft-sass-plugin 0.15.24
│   └── ✕ unmet peer @rushstack/heft@^0.71.1: found 1.1.2 in @microsoft/spfx-web-build-rig

Notes

This is a packaging issue within @microsoft/spfx-web-build-rig@1.22.2. The heft-sass-plugin was published with a peer dependency constraint targeting the pre-1.0 heft, but the build rig bundles the post-1.0 version. The heft-sass-plugin's peer dependency likely needs updating to include >=0.71.1 || ^1.0.0 (or similar).

The workaround is to suppress this via globalPeerDependencyRules in pnpm-config.json.