Many SPFx developers reach a point where older projects (for example, 1.16 or 1.19) stop building after upgrading Node.js or installing new tools.
This happens because every SPFx release supports only specific Node and TypeScript versions.

The good news is that Microsoft now officially supports Node 22 LTS starting with SPFx 1.21.x, making this the perfect time to modernize older codebases.

This article shows you exactly how to perform that upgrade safely — no guessing, no broken builds.

How to Safely Upgrade an Existing SPFx Project to Node 22 LTS

A Complete Step-by-Step Modernization Guide (SPFx 1.21.x)

1. Introduction

Many SPFx developers reach a point where older projects (for example, 1.16 or 1.19) stop building after upgrading Node.js or installing new tools.
This happens because every SPFx release supports only specific Node and TypeScript versions.

The good news is that Microsoft now officially supports Node 22 LTS starting with SPFx 1.21.x, making this the perfect time to modernize older codebases.

This article shows you exactly how to perform that upgrade safely — no guessing, no broken builds.

2. Prerequisites

Before starting the upgrade:

• Confirm that you have Node.js 22 LTS installed.
• Install NVM (Node Version Manager) if you plan to switch between Node versions.
• Back up your existing project folder or clone it to a safe branch.

Then verify your environment:

node -v
npm -v
gulp -v

You should see Node 22.x, npm 10.x, and Gulp CLI 2.x or newer.

3. Step 1 — Identify Your Current SPFx Version

Open your package.json and find one of these lines:

"@microsoft/sp-core-library": "1.16.1"

Whatever version appears there is your current SPFx baseline.

If you see 1.17, 1.18, or 1.19, your project still uses a pre–Node 22 stack.
You’ll upgrade all of these packages together.

4. Step 2 — Clean the Environment

Old dependency caches often cause version conflicts during an upgrade.
Start by deleting all previous artifacts:

rd /s /q node_modules
del package-lock.json
npm cache clean --force

This removes every trace of old modules, ensuring a clean rebuild.

5. Step 3 — Update the Core SPFx Packages

Now upgrade all Microsoft SPFx packages to the latest supported release (1.21.x).
Run these commands inside your project folder:

npm install @microsoft/sp-core-library@latest --save
npm install @microsoft/sp-webpart-base@latest --save
npm install @microsoft/sp-property-pane@latest --save
npm install @microsoft/sp-lodash-subset@latest --save
npm install @microsoft/sp-office-ui-fabric-core@latest --save
npm install @microsoft/sp-component-base@latest --save
npm install @microsoft/sp-http@latest --save

Then the build and tooling libraries:

npm install @microsoft/sp-build-web@latest --save-dev
npm install @microsoft/sp-module-interfaces@latest --save-dev
npm install @microsoft/eslint-config-spfx@latest --save-dev
npm install @microsoft/eslint-plugin-spfx@latest --save-dev

This aligns your project with the SPFx 1.21 toolchain.

6. Step 4 — Upgrade the Compiler and TypeScript

SPFx 1.21 requires the Rush compiler and TypeScript 5.4.x.
Install both:

npm install @microsoft/rush-stack-compiler-5.4 --save-dev
npm install typescript@5.4.5 --save-dev

If your project used an older Rush compiler (like 4.7), remove it first.

7. Step 5 — Update React and Fluent UI

SPFx 1.21 ships with React 18 and Fluent UI 9.
Older React 17 code will still compile but may throw type conflicts.

Update both React packages and their type definitions:

npm install react@18.2.0 react-dom@18.2.0 --save
npm install @types/react@18.2.15 @types/react-dom@18.2.7 --save-dev
npm install @fluentui/react@^9.45.0 --save

If your project still references office-ui-fabric-react, consider migrating those imports gradually to @fluentui/react.

8. Step 6 — Update Gulp and ESLint

SPFx uses Gulp to manage builds.
Older Gulp versions may not work under Node 22.

Upgrade Gulp and its CLI:

npm install gulp@4.0.2 gulp-cli@2.3.0 --save-dev

Also refresh ESLint:

npm install eslint@8.57.0 eslint-plugin-react-hooks@4.6.0 --save-dev
npm install @rushstack/eslint-config@2.6.1 --save-dev

9. Step 7 — Update the engines Section in package.json

Make sure your file specifies the correct Node range:

"engines": {
  "node": ">=18.17.1 <23.0.0",
  "npm": ">=8.0.0"
}

This guarantees that collaborators running Node 23 or lower than 18.17 get a warning.

10. Step 8 — Reinstall Everything Fresh

Now reinstall all packages from scratch:

npm install

Then rebuild:

gulp clean
gulp build
gulp serve

If everything compiles without errors, your project is now running fully under Node 22 LTS and SPFx 1.21.x.

11. Step 9 — Verify React Compatibility

Check that the version of React in your local development workbench matches your web part build.
Open the console in your browser while running:

gulp serve

You should see React 18 loaded without warnings about version mismatches.

If you still see React 17 references, run:

npm dedupe

to remove duplicate React installations.

12. Step 10 — Optional Cleanup and Optimizations

You can now remove deprecated libraries or update optional ones like react-slick, slick-carousel, or others to newer versions.

Always confirm that external libraries work under React 18.
If not, reinstall their latest versions.

13. Step 11 — Package and Deploy

Once everything builds cleanly, you can package and deploy to SharePoint:

gulp bundle --ship
gulp package-solution --ship

Upload the generated .sppkg file to your App Catalog as usual.

14. Step 12 — Confirm in SharePoint Online

Finally, deploy the app and verify that:

• The web part loads correctly in the Workbench and a site page.
• The property pane opens normally.
• No TypeScript or runtime errors appear in the browser console.

If it passes all three, your upgrade is complete.

15. Key Takeaways

16. Reference

Official documentation:
Set up your SharePoint Framework development environment
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-development-environment

17. Final Thoughts

Upgrading SPFx doesn’t have to be painful.
The key is to treat it as a controlled migration — clean first, update versions in one step, rebuild, and test.

Following this structured process ensures:

• Zero dependency drift
• Predictable builds
• Full Node 22 LTS compatibility
• Long-term stability for future Microsoft releases

Once your solution is running on SPFx 1.21.x, you’ll be ready for everything that comes next.