The SharePoint Framework (SPFx) evolves with each release, introducing updated dependencies on Node.js (LTS versions), TypeScript, and React.
To maintain compatibility and avoid environment issues, developers should always align their Node.js version and global toolchain with the specific SPFx version they intend to use.

🧠 SharePoint Framework (SPFx) Compatibility and Installation Guide

The SharePoint Framework (SPFx) evolves with each release, introducing updated dependencies on Node.js (LTS versions), TypeScript, and React.
To maintain compatibility and avoid environment issues, developers should always align their Node.js version and global toolchain with the specific SPFx version they intend to use.

This guide provides the exact commands to install each compatible setup using nvm (Node Version Manager).

⚙️ How Global Packages Work with nvm

Each Node.js version managed by nvm has its own global package space.
When you install packages globally with npm -g, they are stored inside the current Node version’s directory — meaning:

• ✅ You can safely install yo, gulp-cli, and @microsoft/generator-sharepoint globally for each Node version.
• 🔄 When switching Node versions with nvm use, the corresponding global packages will automatically switch.

So yes — even with -g, you can install each SPFx toolchain version independently per Node version.

🧩 Installation Pattern

Use the following general pattern for each version:

nvm install <NodeVersion>
nvm use <NodeVersion>
npm install -g gulp-cli yo @microsoft/generator-sharepoint@<SPFxVersion>

Then scaffold your project:

yo @microsoft/sharepoint

🚀 Ready-to-Use Installation Commands by SPFx Version

🟢 SPFx 1.21.1 (Node 22, TypeScript 5.3, React 17)

nvm install 22
nvm use 22
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.21.1

🟢 SPFx 1.21.0

nvm install 22
nvm use 22
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.21.0

🟢 SPFx 1.20.0

nvm install 18
nvm use 18
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.20.0

🟢 SPFx 1.19.0

nvm install 18
nvm use 18
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.19.0

🟢 SPFx 1.18.2

nvm install 18
nvm use 18
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.18.2

🟢 SPFx 1.18.1

nvm install 18
nvm use 18
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.18.1

🟢 SPFx 1.17.4

nvm install 16.13
nvm use 16.13
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.17.4

🟢 SPFx 1.16.1

nvm install 16.13
nvm use 16.13
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.16.1

🟢 SPFx 1.15.2

nvm install 16
nvm use 16
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.15.2

🟢 SPFx 1.14.0

nvm install 14
nvm use 14
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.14.0

🟢 SPFx 1.13.0

nvm install 14
nvm use 14
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.13.0

🟢 SPFx 1.12.1

nvm install 12
nvm use 12
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.12.1

🟢 SPFx 1.11.0

nvm install 10
nvm use 10
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.11.0

🟢 SPFx 1.8.2

nvm install 10
nvm use 10
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.8.2

🟢 SPFx 1.7.1

nvm install 8
nvm use 8
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.7.1

🟢 SPFx 1.4.1

nvm install 8
nvm use 8
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.4.1

🟢 SPFx 1.1.0

nvm install 6
nvm use 6
npm install -g gulp-cli yo @microsoft/generator-sharepoint@1.1.0

📊 SPFx Compatibility Summary

🔗 Reference

Microsoft official compatibility table:
SharePoint Framework (SPFx) Compatibility