SPFx 1.23.2: upgrading is not changing a number

SharePoint Framework 1.23.2 shipped on 30 June 2026 as a minor bump: it fixes npm vulnerabilities and a few reported issues. It looks like a routine update, the kind you do without thinking. It is not.

The clue is in the previous version. 1.23.1 was published and then pulled from npm for regressions. In a mature framework, a version yanked out of circulation is a warning: the risk of upgrading SPFx is almost never in the SharePoint runtime, it is in the build. This article is about what changed, what broke, and what is still going to break, with the code showing how it was, how it is, and how it will be.

What breaks is not SharePoint, it is the build

An SPFx web part runs in the browser, inside a SharePoint page, and that part has been stable for years. What Microsoft is moving, and hard, is the build chain: the tooling that compiles the TypeScript, processes the Sass and packages the .sppkg. Upgrading the SPFx packages and migrating the build process are two related things, but not the same one, and it is the second that breaks builds.

Hence rule number one: an SPFx upgrade is not mechanical. You do not change the number in package.json and expect it to compile, Microsoft itself warns that doing so gives build failures. What follows are the four places where this bites, and what to do at each one.

Gulp is on the way out

The structural change is the end of Gulp. Up to 1.21, Gulp orchestrated everything. From 1.22, new projects moved to Heft, which still uses webpack underneath but driven by it; the gulpfile.js stopped being compatible and config.json disappeared. In 1.23, an existing project can still stay on Gulp. In 1.24, Gulp becomes officially unsupported.

# WAS (SPFx 1.21 and earlier): Gulp orchestrated the whole build.
gulp bundle --ship
gulp package-solution --ship

# IS (SPFx 1.22-1.23): Heft orchestrates webpack. gulpfile.js and config.json
# are gone; the commands are plain npm scripts.
npm run build
npm run package

# WILL BE (SPFx 1.24): the Gulp toolchain is officially unsupported, and the
# Yeoman generator gives way to the new SPFx CLI.
npm install -g @microsoft/spfx-cli

At the same time, Yeoman is being replaced by the new @microsoft/spfx-cli, still pre-release, with general availability planned for 1.25, in September. In other words: touching the packages and migrating the build are separate projects. You upgrade to 1.23.2 first, and plan the Heft migration on its own, with tests.

Sass changed without warning

The regression that costs the most to catch in 1.23 is in Sass, and Microsoft classifies it as undocumented (issue #10854). Imports that worked in 1.22 stop resolving: the ~ prefix, bare specifiers, and importIncludePaths stop working. A project with serious Sass compiles on 1.22 and fails on 1.23 with not a line of code changed.

// WAS (worked in SPFx 1.22): the webpack tilde and importIncludePaths.
@use "~@scope/package/styles";

@use "sass:meta";
.card { @include meta.load-css("~@scope/package/styles"); }

// IS (SPFx 1.23, issue #10854): the tilde and bare specifiers stop resolving,
// and importIncludePaths is gone. Import npm packages with the pkg: scheme.
@use "pkg:@scope/package/styles";

@use "sass:meta";
.card { @include meta.load-css("pkg:@scope/package/styles"); }

The path is the pkg: scheme to import npm packages, and reviewing every meta.load-css(). There is more in the same batch: SCSS source maps pointed at intermediate CSS instead of the original .scss (#10831), and plain .scss files generated CSS Module types even though webpack treated them as global (#10832). 1.23.2 marks these as fixed, but some issues are still open on the tracker: test before assuming it is resolved in your scenario.

npm audit fix --force does more harm than good

1.23.2 fixed the critical and high vulnerabilities, and a few moderate ones remain in external dependencies. The instinctive reaction, running npm audit fix --force, is the wrong one, and Microsoft explicitly says not to do it: it rewrites transitive packages Microsoft tested and gives you a build that no longer reproduces.

# WAS (the footgun Microsoft tells you not to pull): rewrites the transitive
# packages Microsoft tested, and leaves you a build that no longer reproduces.
npm audit fix --force

# IS (look before you touch): most vulnerable packages are build-time only, and
# node_modules never ships inside the .sppkg.
npm audit --omit=dev
npm ls the-flagged-package
npm explain the-flagged-package

The distinction that matters: most vulnerable dependencies are part of the build environment, and node_modules never ships inside the .sppkg. A vulnerability in a local tool is not a vulnerability in production on SharePoint. Before touching anything, check whether the dependency is development-only, whether it ends up in the final bundle, and who brought it in.

Pin versions, not @latest

The 1.23.1 lesson is this: in a pipeline, @latest is a time bomb. Had the build caught 1.23.1 on the wrong day, it would have installed a version Microsoft ended up pulling. You pin exact versions, and you install React exactly as the matrix says, with --save-exact, because a wrong React version fails silently, with no build error.

# The 1.23.1 lesson: it was delisted from npm for regressions. In a pipeline,
# @latest is a time bomb. Pin exact versions.
npm install react@17.0.1 react-dom@17.0.1 --save-exact
# SPFx 1.23.2 matrix: Node v22, TypeScript up to 5.8, React 17.0.1. Not 18 yet.

The 1.23.2 matrix is clear: Node v22, TypeScript up to 5.8, React 17.0.1. SPFx does not do React 18 yet, it is still on the roadmap. Pinning is not bureaucracy: it is what separates a build that reproduces from one that shifts under your feet between a machine and the pipeline.

And 1.24?

1.24 is in preview, in beta since 8 July 2026, and it brings the feature that shows where SPFx is going: SharePoint Copilot Apps. They are SPFx components, with the same packaging and the same tooling, but they render inside the Microsoft 365 Copilot canvas instead of a SharePoint page. A Copilot component extends BaseCopilotComponent, not BaseClientSideWebPart, and a single .sppkg can hold both.

It is a real preview, and Microsoft owns it: it only renders in the Copilot canvas, it is not distributed through the Store, and the name itself may change before the final version. It is for the lab, in a development tenant, not for production. The signal that matters is the direction: SPFx stops being only about SharePoint and becomes the way to put your own interface inside Copilot.

What is left

1.23.2 is the right version for new projects in production, but you do not treat it as a swap of a number. The SharePoint runtime holds; what breaks is the build chain, the Sass imports, the Gulp customizations that die in 1.24, and features whose server-side rollout is not finished yet. Upgrading SPFx is a build migration disguised as a bump. Pin the versions, test the build, and do the Heft migration with a plan, not with an npm install.