Skip to content

SPFx 1.24: Upgrade Checklist, What Changed, and What to Test

Billy Peralta

Microsoft documentation checked 9 min read

Laptop screen showing code in a dark code editor

Mohammad Rahmani on Unsplash

Topics: SPFx, SharePoint Framework, SharePoint Development, React, Node.js, Microsoft 365 Copilot

SharePoint Framework (SPFx) 1.24 became generally available on October 28, 2026. Microsoft followed it with a maintenance release, 1.24.1, on November 2.

The headline change is React 18. For a lot of SharePoint solutions that means real code changes, not only new package numbers. Below is what changed, which upgrade path applies to your project, and what I’d test before anything reaches production.

The short answer

  • New projects: use the 1.24.1 generator, which Microsoft recommends, and Node.js 26 LTS.
  • Existing projects on SPFx 1.22 or 1.23 (Heft): upgrade SPFx and React together, then change how your code mounts React.
  • Projects still using the older Gulp toolchain: follow Microsoft’s Gulp-to-Heft migration guidance first, then tackle the React 18 upgrade separately.
  • Projects created with the 1.24.0 generator: check package.json for 1.24.0-rc.0 references and move them to stable packages.
  • Don’t upgrade by editing version numbers in package.json. Microsoft warns that this “will result in build failures”.

What changed in SPFx 1.24

React 18.3.1. New React-based SPFx solutions use React 18.3.1. SPFx 1.23 used React 17.0.1. Microsoft’s compatibility page says to use that exact version, because a mismatched React version “can cause silent runtime failures”.

Node.js 22, 24 and 26. SPFx 1.24 supports Node.js 22 (22.14.0 or later), 24 and 26. Microsoft recommends Node.js 26 LTS for a new development environment. If your team or build pipeline is on a supported Node.js 22 or 24 version, you don’t have to change it to adopt 1.24.

Copilot UX components are generally available. These were previewed as “SharePoint Copilot Apps”. They let a Copilot agent show interactive content, such as charts, forms and approvals, inside Microsoft 365 Copilot. More on the requirements below.

No new deprecations. The 1.24.0 release notes list no new deprecations, and one fixed issue: Sass imports from packages, a regression introduced in 1.22.

SharePoint Online only. SPFx 1.24 isn’t supported on SharePoint Server. On-premises versions only support much older SPFx releases.

Which 1.24 version to use

The 1.24.0 generator could create projects that pointed at release-candidate packages (1.24.0-rc.0) instead of the stable ones. SPFx 1.24.1 fixes that and includes dependency updates. Microsoft’s documentation recommends 1.24.1 for new projects.

As of November 19, 2026, npm lists version 1.24.2 of the generator under the latest tag. I couldn’t find corresponding Microsoft release notes at the time of writing.

Comparing the dependency templates in the published 1.24.1 and 1.24.2 generator packages shows that the SPFx package references move to 1.24.2, while the React, TypeScript and Heft version references remain unchanged. That comparison doesn’t establish what changed inside the SPFx packages themselves.

For this checklist, I’m sticking with 1.24.1, the version currently recommended in Microsoft’s documentation.

Pin the generator and the project’s SPFx release packages to the exact target version rather than relying on @latest. Don’t mix release-candidate and stable packages, and don’t assign the SPFx version number to unrelated dependencies such as React, TypeScript, Fluent UI or Heft.

npm install @microsoft/generator-sharepoint@1.24.1 --global

Pick your upgrade path

Projects still using the Gulp toolchain

SPFx 1.22 replaced the gulp-based build toolchain with one based on Heft. If your project still has a gulpfile, do that migration first, using Microsoft’s guide to moving from the gulp toolchain to Heft. I covered that change in my SPFx 1.22 upgrade checklist.

Doing the toolchain move and the React 18 move as separate steps makes problems much easier to trace.

Projects on SPFx 1.22 or 1.23 (Heft)

These projects already use Heft, so the work is mostly about React:

  1. Build the current version and keep the package, so you can compare behaviour and roll back.
  2. Generate a fresh project with the target 1.24 generator in an empty folder, and compare its package.json, tsconfig.json, eslint.config.js and config files with yours. Don’t generate over your existing project.
  3. Update the existing SPFx release packages to the same exact target version, pin react and react-dom to 18.3.1, and use compatible React 18 type definitions. Review dependency overrides and resolutions that still reference React 17 or older type definitions. Align the build dependencies with the generated comparison project.
  4. Change how the solution mounts React (next section).
  5. Run a clean install and a production build, then test in every place the solution runs.

Microsoft’s React 18 upgrade guide for SPFx 1.24 walks through each step. If you want a list of the changes your specific project needs, the CLI for Microsoft 365 can produce a report without changing any files:

npx -p @pnp/cli-microsoft365@latest m365 spfx project upgrade --toVersion 1.24.1 --output md

Read the report and apply the changes by hand, keeping your own code and configuration.

Projects created with the 1.24.0 generator

Look in package.json for 1.24.0-rc.0. If you find any, update the SPFx runtime, build, plugin and lint packages to the same stable version, compare with a project generated by the newer generator, and then run npm install and npm run build. The 1.24.1 release notes list the steps.

The React 18 code change

Most existing function components, class components and hooks can stay as they are. What changes is how the web part puts React on the page and removes it.

SPFx 1.23 web parts typically use ReactDom.render and ReactDom.unmountComponentAtNode. With the React 18 root API, create one root per DOM container, reuse it for subsequent renders, and unmount it when that container is disposed.

The following abbreviated example is adapted from Microsoft’s migration guidance. It illustrates the lifecycle pattern rather than a complete, independently tested web part. Keep your existing component imports, properties, initialization, theme handling and other cleanup logic.

import * as React from 'react';
import { createRoot, type Root } from 'react-dom/client';

// Inside your web part class:
private _root: Root | undefined;

public render(): void {
  const element = React.createElement(HelloWorld, {
    description: this.properties.description
  });

  if (!this._root) {
    this._root = createRoot(this.domElement);
  }
  this._root.render(element);
}

protected onDispose(): void {
  this._root?.unmount();
  this._root = undefined;
}

A few things to watch:

  • Look beyond the main web part. Extensions, custom property pane controls, dialogs and field customizers mount React too. A field customizer needs a separate root for each cell.
  • Legacy rendering can still work. React 18 retains ReactDom.render with a deprecation warning and React 17-compatible rendering behaviour. A successful build alone doesn’t prove that the migration to the new root API is complete.
  • children must be declared. React 18 type definitions no longer add children to component props automatically. Add it to the props interface where a component accepts child content.
  • Updates are batched more often. With createRoot, React 18 also batches state updates from promises, timers and native events. When a new state value depends on the previous value, use the functional form of the state setter.
  • Check third-party controls. Charts, editors, UI libraries and test tools all need versions that support React 18.

What to test before you ship

A successful local build isn’t the finish line. Before an upgraded package goes to production:

  • Clean install and production build: npm ci, then npm run build, with the updated lock file committed.
  • Dependency check: run npm ls react react-dom @types/react @types/react-dom and investigate unexpected versions or peer dependency conflicts. Keep your direct React dependencies aligned with Microsoft’s compatibility reference. Don’t blindly override transitive dependencies or hide conflicts with --force or --legacy-peer-deps.
  • Solution version: increase solution.version in config/package-solution.json, and keep the existing solution and component IDs.
  • Every host: test the deployed package on SharePoint pages and in Teams, Viva Connections or Copilot if the solution runs there. Local previews don’t prove the host integration works.
  • Behaviour: first load, data loading, forms, property pane changes, theme changes, and several copies of the web part on one page.
  • Clean removal: removing and re-adding the web part doesn’t leave errors or duplicate content behind.
  • Browser console: no legacy-render, duplicate-root or invalid-hook-call warnings.
  • Permissions: if the upgraded package requests new API permissions, an administrator has to approve them on the API access page in the SharePoint admin center before they work.
  • npm audit: 1.24.1 addresses some reported vulnerabilities, but Microsoft says it “doesn’t guarantee an empty npm audit report”. Review each finding against how your project uses the package.
  • Rollback: retain the previous source revision, dependency lock file and known-good deployment package. Confirm your rollback procedure before releasing, including whether the previous code needs to be rebuilt and packaged with a higher solution version. Don’t assume uploading an older package will automatically reverse every change.

Test in a development tenant or a test site collection first, not on a production intranet page.

Copilot UX components: requirements and limits

If you’re thinking about building Copilot UX components, check these before you plan the work:

  • Licensing: every user, including developers and testers, needs the Microsoft 365 Copilot add-on licence on top of their E3, E5 or E7 licence. The base licence alone isn’t enough.
  • No usage charges for the components themselves, but APIs or services your component calls can have their own costs.
  • Where they work: Microsoft 365 Copilot and Copilot in Teams, in the browser and desktop apps. iOS and Android, including Teams mobile, aren’t supported yet.
  • Teams solutions: combining Copilot UX components and SPFx Teams features in one solution causes a mismatch in the automatic Sync to Teams step. A manually created Teams package works around it.
  • Context limit: text context sent to Copilot with createCopilotTextContent is limited to 10 KB. Anything larger blocks the message instead of being cut short.

Upgrade now, or wait?

Upgrade soon if:

  • you’re starting a new solution,
  • you need React 18 for a library or component you plan to use,
  • you want to build Copilot UX components, or
  • the solution is already in active development and has a test cycle coming up.

It’s reasonable to wait if:

  • the solution is stable, rarely changes, and works today,
  • it uses third-party React controls that don’t support React 18 yet, or
  • nobody has time to test it properly in every place it runs.

Moving to SPFx 1.24 isn’t mandatory, and a stable solution doesn’t have to move this month. Plan the upgrade into your next change to that solution, so it gets tested properly rather than rushed.

Sources and what I checked

The facts in this post come from Microsoft’s 1.24.0 and 1.24.1 release notes, the compatibility reference and the React 18 upgrade guide, checked on November 19, 2026. I also compared the dependency templates in the published 1.24.1 and 1.24.2 generator packages.

This is a documentation-based upgrade checklist, not a hands-on migration report. I haven’t scaffolded or compiled an SPFx 1.24 project, executed the sample commands, or validated the solution in a Microsoft 365 tenant for this article. Test the guidance against your own project’s dependencies, configuration and target hosts before deploying.

For where SPFx is heading next, see my SPFx roadmap for 2026. If you’d rather have help with an upgrade, or with a new SPFx solution, see SPFx development.

Need a production-ready SPFx solution?

I build SharePoint Framework web parts, extensions, dashboards, and integrations using React, TypeScript, PnPjs, and Microsoft Graph.

16+ years experience Microsoft certified Government & enterprise

Free SharePoint planning resource

Solving the technical issue is only part of the Microsoft 365 problem.

Use the checklist to review the governance, permission, ownership, and support decisions that often determine whether a SharePoint solution succeeds long term.

Download the Checklist

Billy Peralta

SharePoint architect & Microsoft 365 consultant • 16+ years of experience

If you have questions about your SharePoint environment, feel free to reach out.

LinkedIn GitHub

Continue Reading

View all posts