In every SharePoint Framework (SPFx) project, the file package.json defines how the entire environment works — which Node.js version is required, which SPFx libraries are installed, how React is integrated, and how Gulp builds your code.

As Microsoft continuously updates SPFx and moves toward Node 22 LTS, it’s essential to keep this file aligned with the latest standards.
In this article, you’ll learn what each part of a clean and modern package.json means, and how to maintain full compatibility with SPFx 1.21.1 and Node 22 LTS.

Keeping SharePoint Framework Up to Date with Node 22 LTS

Understanding and Modernizing Your package.json File (SPFx 1.21.1)

1. Introduction

In every SharePoint Framework (SPFx) project, the file package.json defines how the entire environment works — which Node.js version is required, which SPFx libraries are installed, how React is integrated, and how Gulp builds your code.

As Microsoft continuously updates SPFx and moves toward Node 22 LTS, it’s essential to keep this file aligned with the latest standards.
In this article, you’ll learn what each part of a clean and modern package.json means, and how to maintain full compatibility with SPFx 1.21.1 and Node 22 LTS.

2. The Modern package.json Example

Here’s the complete structure you should use for new SPFx 1.21.1 projects or when modernizing older ones.

{
  "name": "my-spfx-project",
  "version": "1.21.1",
  "private": true,
  "engines": {
    "node": ">=18.17.1 <23.0.0",
    "npm": ">=8.0.0"
  },
  "main": "lib/index.js",
  "scripts": {
    "build": "gulp bundle",
    "clean": "gulp clean",
    "test": "gulp test"
  },
  "dependencies": {
    "@fluentui/react": "^9.45.0",
    "@microsoft/sp-component-base": "1.21.1",
    "@microsoft/sp-core-library": "1.21.1",
    "@microsoft/sp-lodash-subset": "1.21.1",
    "@microsoft/sp-office-ui-fabric-core": "1.21.1",
    "@microsoft/sp-property-pane": "1.21.1",
    "@microsoft/sp-webpart-base": "1.21.1",
    "react": "18.2.0",
    "react-dom": "18.2.0",
    "tslib": "2.6.2"
  },
  "devDependencies": {
    "@microsoft/eslint-config-spfx": "1.21.1",
    "@microsoft/eslint-plugin-spfx": "1.21.1",
    "@microsoft/rush-stack-compiler-5.4": "0.2.0",
    "@microsoft/sp-build-web": "1.21.1",
    "@microsoft/sp-module-interfaces": "1.21.1",
    "@rushstack/eslint-config": "2.6.1",
    "@types/react": "18.2.15",
    "@types/react-dom": "18.2.7",
    "@types/webpack-env": "1.18.0",
    "ajv": "^8.12.0",
    "eslint": "8.57.0",
    "eslint-plugin-react-hooks": "4.6.0",
    "gulp": "4.0.2",
    "gulp-cli": "^2.3.0",
    "typescript": "5.4.5"
  }
}

3. Line-by-Line Explanation

"name": "my-spfx-project"

This is the internal name of your project.
It helps identify the package in npm and Gulp logs but has no effect on the deployed SharePoint solution.

"version": "1.21.1"

This defines your project’s version number.
Keeping it aligned with your SPFx version (1.21.1) helps you know which framework release it was built for.

"private": true"

Marks the project as private so npm will never attempt to publish it publicly.
All SPFx projects should remain private since they’re intended for organizational environments.

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

Specifies the allowed Node.js and npm versions.
SPFx 1.21.1 supports Node versions from 18.17.1 up to but not including 23, making it compatible with Node 22 LTS.
If someone tries to build with Node 23 or older than 18.17, npm will display a warning or error.

"main": "lib/index.js"

This tells Node.js where the compiled entry file is located.
SPFx compiles your TypeScript from src to lib, and lib/index.js becomes the starting point for the generated bundle.

"scripts" section

Defines short npm commands to run Gulp tasks easily.

You can execute them via:

npm run build
npm run clean
npm run test

"dependencies" section

These packages are needed at runtime inside your web part.

@fluentui/react

The latest Fluent UI React library (version 9).
Used to create components that follow Microsoft’s modern design system.

@microsoft/sp-* packages

Core libraries that define how SPFx works internally:

All are pinned to 1.21.1, ensuring that they are internally consistent and compatible with Node 22.

react and react-dom

SPFx 1.21 uses React 18.2.0 by default.
Both must match exactly; mixing React 17 and 18 will cause type conflicts.

tslib

Contains small runtime helpers used by TypeScript’s compiled code (async/await, spread, etc.).
Must stay close to your TypeScript version.

"devDependencies" section

These are tools needed only during development or build time, not for the deployed bundle.

@microsoft/sp-build-web

The main SPFx build pipeline (includes Webpack, Gulp, and TypeScript integration).

@microsoft/sp-module-interfaces

Contains manifest and configuration type definitions for SPFx components.

@microsoft/rush-stack-compiler-5.4

The compiler stack that wraps TypeScript.
Each major SPFx version requires a specific Rush compiler version that matches its internal TypeScript version (here, 5.4).

@microsoft/eslint-config-spfx and @microsoft/eslint-plugin-spfx

These provide Microsoft’s official linting configuration for SPFx code quality.

@rushstack/eslint-config

Adds TypeScript and React-specific linting rules.

@types/react and @types/react-dom

TypeScript type definitions for React and ReactDOM.

@types/webpack-env

Type definitions for Webpack globals used in SPFx (like __webpack_public_path__).

ajv

JSON schema validator used by SPFx internally and sometimes in project validation scripts.

eslint and eslint-plugin-react-hooks

The main ESLint linter and an extension that validates correct React hook usage.

gulp and gulp-cli

The task runner responsible for SPFx build steps.
Gulp 4 and Gulp CLI 2.3+ are fully compatible with Node 22.

typescript

The TypeScript compiler.
SPFx 1.21 requires TypeScript 5.4.5, which supports Node 22 LTS.

4. Why Version Alignment Is Critical

Most SPFx compilation errors — such as
“Type ‘SPHttpClient’ is not assignable to type ‘SPHttpClient’” or
“private property ‘_digestCache’ mismatch” —
are caused by mixed package versions.

If one SPFx library is from 1.19 and another from 1.21, their internal private classes differ, breaking compatibility.
Keeping all SPFx packages at the same version (1.21.1 in this example) ensures they share the same internal structure.

5. Cleaning and Rebuilding After Updating

After changing any dependencies, always do a full clean install:

rd /s /q node_modules
del package-lock.json
npm cache clean --force
npm install
gulp clean
gulp build
gulp serve

This guarantees your build uses only the new, consistent dependencies.

6. Benefits of the Modern Setup

• Full support for Node 22 LTS
• Modern React 18 runtime
• Latest Fluent UI 9 components
• Stable TypeScript 5.4 compiler
• Unified SPFx library versions
• Reliable build pipeline with Gulp 4 and ESLint 8+

This configuration will remain valid until Microsoft releases the next major SPFx milestone, ensuring long-term compatibility.

7. Reference

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