Every SharePoint Framework project depends on a very specific set of tools:
Node.js, TypeScript, React, and Gulp.
The SPFx build system is tightly version-locked, meaning that if one part is out of sync, your project might not even compile.
Knowing which combinations are supported helps you avoid endless troubleshooting.
This article provides a clear compatibility table from the earliest versions of SPFx up to SPFx 1.21.1, which now officially supports Node.js 22 LTS.
It also shows where to check for future updates as Microsoft continues to release new framework versions.
The Complete Compatibility Reference for SharePoint Framework (SPFx) and Node.js
Understanding Which Versions Work Together — from SPFx 1.0 to 1.21.1 and Beyond
1. Introduction
Every SharePoint Framework project depends on a very specific set of tools:
Node.js, TypeScript, React, and Gulp.
The SPFx build system is tightly version-locked, meaning that if one part is out of sync, your project might not even compile.
Knowing which combinations are supported helps you avoid endless troubleshooting.
This article provides a clear compatibility table from the earliest versions of SPFx up to SPFx 1.21.1, which now officially supports Node.js 22 LTS.
It also shows where to check for future updates as Microsoft continues to release new framework versions.
2. Why Compatibility Matters
SPFx is not a generic web framework — it integrates directly into the SharePoint build environment.
Because of that, Microsoft releases new SPFx versions only after testing them with specific Node.js LTS versions.
If you upgrade Node before SPFx supports it, you’ll see errors like:
Error: Your dev environment is running NodeJS version v22.20.0 which does not meet the requirements for running this tool.
Understanding the supported matrix below allows you to plan upgrades safely.
3. SPFx Compatibility Table (as of October 2025)
| SPFx Version | Release Year | Supported Node.js Versions | Recommended TypeScript | React Version | Gulp CLI | Notes |
|---|---|---|---|---|---|---|
| 1.1 – 1.3 | 2017 | 6.x – 8.x | 2.2 | 15.x | 3.x | Early classic web parts |
| 1.4 – 1.7 | 2018 | 8.x – 10.x | 2.4 – 2.9 | 15–16 | 3.x | Added support for modern pages |
| 1.8 – 1.10 | 2019 | 10.x – 12.x | 3.3 – 3.7 | 16.8 | 3.9 | React Hooks start working |
| 1.11 – 1.13 | 2020 | 10.x – 12.x | 3.9 – 4.1 | 16.13 | 4.0 | Introduced Node 12 support |
| 1.14 – 1.16 | 2021 | 14.x – 16.x | 4.3 | 17.0 | 4.0 | Added support for Node 16 |
| 1.17 – 1.19 | 2022–2023 | 16.x – 18.x | 4.5 – 4.8 | 17.0 | 4.0 | Transition period to modern stack |
| 1.20 | Early 2024 | 18.x – 20.x | 5.0 | 18.2 | 4.0.2 | First release compatible with React 18 |
| 1.21.1 | Mid 2025 | 18.17.1 – 22.x (LTS) | 5.4.5 | 18.2.0 | 2.3.0+ | Official Node 22 LTS support |
| (Future 1.22+) | Expected 2026 | 22.x+ | 5.5+ | 18–19 | 2.3+ | To be announced by Microsoft |
Key Observations
- SPFx versions older than 1.11 are no longer supported for SharePoint Online.
- Node.js 22 LTS is officially supported only from SPFx 1.21.1 onward.
- The safest long-term baseline today is SPFx 1.21.1 + Node 22 LTS + TypeScript 5.4.
- Microsoft typically releases one major SPFx version per year, aligned with the current Node LTS.
4. Where to Verify New Versions
You can check the official Microsoft Learn pages for new SPFx releases:
- SPFx setup guide (always updated):
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-development-environment - SPFx release notes index:
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/release-notes - Individual version notes (examples):
These pages include:
- Supported Node.js version ranges
- TypeScript version used internally
- Changes to React or Fluent UI
- Deprecations or breaking changes
Microsoft usually announces new releases first in the SharePoint Developer Blog.
5. Graphical Understanding (if converted to chart)
If you imagine this as a timeline graph:
- Horizontal axis: Year of SPFx release
- Vertical markers: Supported Node versions
- The graph rises from Node 6 (2017) → Node 12 (2020) → Node 16 (2021) → Node 18 (2023) → Node 22 (2025)
Each SPFx release roughly aligns with one Node LTS cycle, maintaining a 1–2 version overlap for transition stability.
6. How to Stay Updated Automatically
You can run these commands periodically to check for new SPFx versions:
npm view @microsoft/sp-build-web version
npm view @microsoft/sp-core-library version
or to upgrade your global generator:
npm install -g @microsoft/generator-sharepoint@latest
To check your local SPFx version inside a project:
npm list @microsoft/sp-build-web
This ensures you always know when Microsoft publishes a new compatible stack.
7. Recommended Maintenance Strategy
| Action | Frequency | Purpose |
|---|---|---|
| Check SPFx release notes | Every 3–4 months | Track new official builds |
Run npm outdated | Monthly | Detect old dependencies |
| Upgrade Node LTS | When new SPFx supports it | Avoid breaking compatibility |
| Clean and rebuild | After every upgrade | Ensure dependency consistency |
Keep backup of working package.json | Always | Allows rollback if new version breaks |
8. Final Thoughts
Staying current with SPFx means staying aligned with Microsoft’s Node.js roadmap.
Unlike most front-end frameworks, SPFx requires strict version discipline — but the reward is a stable, secure, and future-proof environment for your web parts and extensions.
As of 2025, the recommended baseline for all new projects is:
- SPFx: 1.21.1
- Node: 22 LTS
- TypeScript: 5.4.5
- React: 18.2
- Gulp CLI: 2.3
Check Microsoft Learn regularly to confirm when SPFx 1.22+ is released and update accordingly.
edvaldo b. guimarães filho 