How to Update SPFx Version (Complete Step-by-Step Guide)

If you’ve been working with SharePoint Framework for a while, you already know that keeping your SPFx version current isn’t just a “nice to have.” It keeps your solutions compatible with the latest SharePoint Online changes, patches security issues, and unlocks new features. But the upgrade process can feel a bit overwhelming if you’re staring at it for the first time, or even the fifth time.

In this tutorial, I’m going to walk you through everything: how to check which SPFx version you’re on, the different ways to upgrade your SPFx project, and what to watch out for so you don’t get stuck halfway through.

Latest SPFx Compatibility Matrix

Before upgrading, verify that your development environment supports the target SPFx version.

Component	Latest Supported Version
SPFx	1.23.2
Node.js (LTS)	v22
TypeScript	2.9 – 5.8
React	17.0.1

Always review the official Microsoft release notes before upgrading to identify any breaking changes introduced between versions.

What Does Updating an SPFx Version Actually Mean?

This is where a lot of developers get confused. When you say “update SPFx version,” you could mean a few different things:

• Updating the global Yeoman generator (@microsoft/generator-sharepoint) = This updates the SharePoint Framework project generator used when creating new projects.
• Updating the SPFx npm packages inside an existing project. Examples:
  • @microsoft/sp-core-library
  • @microsoft/sp-webpart-base
  • @microsoft/sp-property-pane
  • @microsoft/sp-component-base)
• Updating the SPFx framework version your project targets — which is the full project upgrade process

Most of the time, people mean the third one; they have an older project (say, built on SPFx 1.14) and want to move it to SPFx 1.20 or the latest version. That’s the main focus of this guide. I’ll also cover the other two.

Where Are Version Numbers Stored in an SPFx Project?

Before you touch anything, it helps to know where version numbers live. There are three places:

• ./config/package-solution.json: This is the most important one. It determines whether SharePoint sees your deployment as an upgrade. The version here is what shows up in the App Catalog.
• ./src/[component]/*.manifest.json: Each web part or extension has its own version here.
• ./package.json: Contains all npm dependencies, including SPFx packages.

The one that actually matters for SharePoint upgrades is package-solution.json. The others are informational.

Step 0: Check Your Current SPFx Version

Before upgrading anything, figure out what you’re starting from. Open package.json in your project root and look for the @microsoft/sp-core-library or @microsoft/generator-sharepoint version. That tells you your current SPFx version.

You can also run this command in your project folder:

npm ls @microsoft/sp-core-library --depth=0

To check your globally installed Yeoman generator version:

npm ls @microsoft/generator-sharepoint -g --depth=0

To see if any packages are outdated in your project:

npm outdated

This gives you a clean table showing your current version, the version package.json expected, and the latest available version. Look for anything starting with @microsoft/sp- — Those are your SPFx packages.

Method 1: Using CLI for Microsoft 365 (The Recommended Way for Most Projects)

This is the go-to method for most upgrades, especially when you’re moving one or two versions up. The CLI analyzes your project and generates a detailed upgrade report telling you exactly what to change; it doesn’t make any changes itself, which I actually like. You stay in control.

Step 1: Install CLI for Microsoft 365

The easiest and safest way to upgrade an existing project is with CLI for Microsoft 365.

npm install -g @pnp/cli-microsoft365

Verify it is installed:

m365 --version

Step 2: Run a Health Check (Optional but Useful)

Before upgrading, run the SPFx doctor command to see if your environment is in good shape:

m365 spfx doctor --output text

This checks your:

• Node.js compatibility
• SPFx version
• Package consistency
• Tooling configuration
• Project health

Fix any issues before proceeding.

Step 3: Generate the Upgrade Report

Navigate to your project folder and run:

m365 spfx project upgrade --output md > upgrade-report.md

This creates a upgrade-report.md file in your project directory. Open it in VS Code and use the Markdown preview (Ctrl+Shift+V) to read it properly.

If you want to upgrade to a specific version instead of the latest:

m365 spfx project upgrade --toVersion 1.23.0 --output md > upgrade-report.md

Step 4: Read the Upgrade Report Carefully

The report has two main sections:

• Findings: Each change is explained in detail, with context for why it’s needed
• Summary: A consolidated list of all commands to run

Don’t just scroll to the summary and run everything blindly. Read the findings first, especially if you’re jumping multiple versions. There may be breaking changes in your code that the CLI can’t fix automatically.

Step 5: Apply the Changes

The report will typically tell you to:

1. Update package.json: Change version numbers for SPFx packages
2. Update config files: Things like tsconfig.json, .yo-rc.json
3. Run specific npm install commands: To install new package versions

Run the commands from the Summary section one by one. A typical example looks like:

npm install @microsoft/sp-core-library@1.23.2 --save 
npm install @microsoft/sp-webpart-base@1.23.2 --save 
npm install @microsoft/sp-component-base@1.23.2 --save

Step 6: Clean Existing Dependencies and Reinstall Packages

After updating all SPFx package versions, it’s a good idea to start with a clean dependency installation. This helps prevent version conflicts and eliminates issues caused by cached packages.

Delete node_modules:

rm -rf node_modules

Delete package lock:

rm package-lock.json

Install fresh dependencies:

npm install

This ensures your project is using the correct dependency versions required by the target SPFx release.

Step 7: Validate and Build the Upgraded Project

Once all package updates have been applied and dependencies have been reinstalled, verify that the project builds successfully.

Run a clean build:

heft build

If you want Heft to continuously monitor file changes during development:

heft build --watch

For local development and testing:

heft start

At this stage, you may encounter TypeScript errors, deprecated API warnings, or package compatibility issues. These are common when upgrading across multiple SPFx versions and should be resolved before moving forward.

If the build completes successfully, you’re ready to package and deploy the solution.

Method 2: Create a New SPFx Project and Migrate Your Solution

For large version jumps, creating a new project is often the safest and cleanest approach.

For example, if you’re upgrading from:

• SPFx 1.8
• SPFx 1.10
• SPFx 1.12
• SPFx 1.14

to SPFx 1.23.2, manually applying every upgrade step can become difficult and time-consuming.

Instead, create a fresh SPFx project using the latest tooling and migrate your existing code into it.

This approach allows you to start with modern project configurations while preserving your business logic and SharePoint identifiers.

Step 1: Grab Component Names and IDs from the Old Project

Open .yo-rc.json in the root of your old project. It looks like this:

{
  "@microsoft/generator-sharepoint": {
    "version": "1.14.0",
    "libraryName": "my-awesome-solution",
    "libraryId": "fba2bd20-1cc4-4091-bbee-c9d915109f99",
    "solutionName": "my-awesome-solution"
  }
}

Note down the libraryName, libraryId, and solutionName. You’ll need these.

Also, open each component’s manifest file at ./src/webparts/[name]/[Name]WebPart.manifest.json:

{
  "id": "976f874b-e076-45d2-8dbc-b9e871da0e7e",
  "alias": "HelloWorldWebPart"
}

Save these IDs. They are critical because SharePoint uses them to identify existing deployed components.

Step 2: Create a New Project with the Latest SPFx Version

Make sure you have the latest Yeoman generator installed (more on this below) and scaffold a new project:

yo @microsoft/sharepoint

Use the same:

• Solution name
• Component names
• Project structure (where possible)

This reduces migration effort and helps maintain consistency.

Step 3: Move Your Existing Business Logic

Copy only the application code from the old project:

• TypeScript files (.ts)
• React components (.tsx)
• SCSS files
• Services
• Utilities
• Custom helper classes

Avoid copying configuration files such as:

• package.json
• tsconfig.json
• rush.json
• config files

Use the newly generated project’s configuration instead.

Step 4: Match the Solution ID and Component IDs

This is the critical step. Open ./config/package-solution.json in the new project and replace the id value with the one from your old project:

{
  "solution": {
    "name": "my-awesome-solution-client-side-solution",
    "id": "fba2bd20-1cc4-4091-bbee-c9d915109f99",
    "version": "2.0.0.0"
  }
}

Next, update each component manifest file and restore the original component IDs.

This ensures SharePoint recognizes the deployment as an upgrade rather than a brand-new solution.

Step 5: Increment the Package Solution Version

Update the solution version in:

config/package-solution.json

For example:

1.0.0.0 → 2.0.0.0

This signals SharePoint that a newer version of the solution is available.

Step 6: Test the New Project Thoroughly

Validate the migrated project before deploying.

Build the project:

heft build

Start the local development environment:

heft start

Verify:

• Web parts load correctly
• Extensions function as expected
• Property panes work properly
• React components render without errors
• API integrations continue to function

Once validation is complete, deploy the package to a development tenant or Site Collection App Catalog for final testing.

Method 3: Update the Global SPFx Yeoman Generator

If your goal is to create new SPFx projects using the latest version, update the global generator.

Check for updates:

npm outdated -g

Update the generator:

npm install -g @microsoft/generator-sharepoint

Verify the installed version:

npm ls @microsoft/generator-sharepoint -g --depth=0

Remember that different SPFx versions support different Node.js versions.

For SPFx 1.22.2, use:

Node.js v22 LTS

If you work with multiple SPFx versions, consider using NVM (Node Version Manager):

nvm use 22

Method 4: Using SPFx Toolkit VS Code Extension

If you prefer a more visual approach, the SPFx Toolkit extension for VS Code has a built-in upgrade feature. Just:

1. Open your project in VS Code
2. Click on the SPFx Toolkit panel in the activity bar
3. Go to Actions → Upgrade Project SPFx Version

The toolkit uses CLI for Microsoft 365 behind the scenes while providing a more user-friendly interface.

What Happens When You Deploy an Upgraded SPFx Solution?

Understanding SharePoint upgrade behavior helps avoid deployment confusion.

When a new .sppkg package is uploaded to the App Catalog:

• SharePoint deploys the latest solution package.
• Existing components continue using the updated assets.
• New features become available after the solution upgrade process.

If the version number in package-solution.json has increased, SharePoint displays an upgrade option.

The upgrade process reactivates the solution’s SharePoint features and registers any newly introduced components.

This is especially important when:

• Adding new web parts
• Adding extensions
• Introducing new feature elements

For code-only changes, simply deploying the updated package is often sufficient.

Best Practices Before Upgrading SPFx

Before starting any upgrade:

• Create a dedicated Git branch.
• Back up your project.
• Review Microsoft release notes.
• Upgrade incrementally whenever possible.
• Test in a development tenant first.
• Validate deployments using a Site Collection App Catalog.
• Keep all SPFx packages aligned to the same version.
• Reinstall dependencies after major upgrades.
• Consider creating a fresh project for large version jumps.

Quick Reference: Which Upgrade Method Should You Use?

Situation	Best Method
Small version jump (1-2 versions)	CLI for Microsoft 365 upgrade report
Large version jump (3+ versions)	Create a New Project and Migrate
Just want to scaffold new projects	Update Global Generator
Prefer a visual UI	SPFx Toolkit for VS Code
Working on multiple SPFx versions	Use NVM + isolated folders per version

Common SPFx Upgrade Issues and How to Fix Them

Final Thoughts

I hope you found this article helpful! For most SPFx projects, the Microsoft 365 upgrade report CLI provides the fastest path to the latest release. However, when upgrading across several major versions, creating a fresh SPFx 1.22.2 project and migrating your solution often produces a cleaner, more maintainable result.

Whichever approach you choose, thoroughly test your solution, validate dependencies, and review release notes before deploying to production.

Also, you may like:

• Set Up Your SharePoint Framework (SPFx) Development Environment using Heft Toolchain
• Migrate from Gulp based to Heft based Toolchain in SharePoint Framework (SPFx)
• SPFx Drag and Drop File Upload: Single & Multiple Files