Complete SPFx Development Environment Setup Guide (2025)

Setting up an SPFx development environment sounds straightforward until you hit Node version conflicts, toolchain mismatches, or a debug session that refuses to load. This guide covers everything you need to go from a clean machine to a web part running live on a real SharePoint page in 2025 — including the major toolchain shift that landed with SPFx v1.22.

Important: SPFx v1.22 replaced the long-standing gulp-based toolchain with a new Heft-based toolchain. If you are still on SPFx v1.0–v1.21.1 (including any SharePoint Server on-premises version), follow the legacy gulp setup guide instead. This article covers the modern Heft toolchain for SPFx v1.22+.

🧰 Prerequisites

• A Windows 10/11, macOS, or Linux machine
• Admin or sudo access to install global packages
• A Microsoft 365 tenant (developer tenant is fine — sign up at developer.microsoft.com)
• Visual Studio Code

📦 Step 1 — Install Node.js v22 LTS

SPFx v1.22.x requires Node.js v22 LTS (codename Jod). Using an older version like Node 18 will not work with the latest generator. Wrong Node version is the #1 cause of SPFx build failures.

Use a Node version manager to switch cleanly between versions:

Install and use Node 22 (nvm example):

nvm install 22
nvm use 22
node --version   # Should output v22.x.x

📦 Step 2 — Install the SPFx Toolchain

SPFx v1.22+ uses Heft as the build tool, replacing gulp entirely. Install all three required tools in one command:

npm install @rushstack/heft yo @microsoft/generator-sharepoint --global

Or individually:

# Heft — the new SPFx build engine (replaces gulp)
npm install @rushstack/heft --global

# Yeoman — project scaffolding
npm install yo --global

# SPFx Yeoman generator
npm install @microsoft/generator-sharepoint --global

What is Heft? Heft is a config-driven toolchain from the RushStack project that orchestrates TypeScript, ESLint, Jest, and Webpack. Think of it as a modern, opinionated replacement for Gulp — with better monorepo support and faster incremental builds.

🧩 Step 3 — Scaffold Your First SPFx Project

mkdir my-first-webpart
cd my-first-webpart
yo @microsoft/sharepoint

Answer the prompts:

? What is your solution name? my-first-webpart
? Which type of client-side component to create? WebPart
? What is your Web part name? HelloWorld
? Which template would you like to use? React

The generator installs all npm dependencies automatically. This takes 2–5 minutes on first run.

🧩 Step 4 — Understand the Project Structure

my-first-webpart/
├── config/
│   ├── config.json              # Bundle and entry point configuration
│   ├── package-solution.json    # Solution metadata (ID, version, deployment)
│   └── serve.json               # Serve configuration
├── src/
│   └── webparts/
│       └── helloWorld/
│           ├── HelloWorldWebPart.ts     # Web part entry point and property pane
│           ├── components/
│           │   ├── HelloWorld.tsx        # React component
│           │   └── HelloWorld.module.scss
│           └── loc/
│               └── en-us.js             # Localization strings
├── heft.json                    # Heft toolchain config (replaces gulpfile.js)
├── package.json
└── tsconfig.json

🖥️ Step 5 — Trust the Dev Certificate

The SPFx local server runs on HTTPS with a self-signed certificate. Trust it once per machine:

# Run from inside your project folder after npm install
heft trust-dev-cert

This replaces the old gulp trust-dev-cert from the gulp toolchain.

🚀 Step 6 — Start the Dev Server

npm run serve

This starts a local HTTPS server on https://localhost:4321 and watches your source files for changes. You will see output like:

[heft] Starting local server on port 4321...
[heft] Watching for changes...

The local workbench (localhost:4321/temp/workbench.html) was removed in SPFx v1.13 and no longer works. Skip it entirely — debug directly on a real SharePoint page instead.

🔍 Step 7 — Debug on a Real SharePoint Page

This is the recommended approach and far more reliable than any workbench. Navigate to any modern SharePoint page on your tenant and append the debug query string to the URL:

https://yourtenant.sharepoint.com/sites/yoursite/SitePages/YourPage.aspx?debugManifestsFile=https://localhost:4321/temp/build/manifests.js

For example:

https://tealdroid.sharepoint.com/sites/blog/SitePages/Test.aspx?debugManifestsFile=https://localhost:4321/temp/build/manifests.js

SharePoint will show a yellow banner — click Load debug scripts to confirm. Your locally served web part code is now running live on the page. Edit your source files and npm run serve will rebuild — refresh the page to see changes instantly.

Path changed in SPFx v1.21: The manifest path was updated from /temp/manifests.js to /temp/build/manifests.js. If you are on an older project and the debug URL is not working, this is the first thing to check.

Why debug on a real page instead of the workbench?

• You get real SharePoint context, real permissions, real data
• Web parts that use this.context.pageContext or Graph API behave exactly as they will in production
• No more "works in workbench, breaks in production" surprises

Add the web part to the page

Once debug scripts are loaded, enter Edit mode on the page, click + to add a web part, and your locally served web part will appear in the picker alongside any deployed ones.

⚠️ Troubleshooting — Debug URL Not Working

Some tenants have recently reported the debugManifestsFile query string not triggering the "Load debug scripts" banner. If this happens:

1. Allow custom scripts on the site

In SharePoint Admin Center → Active Sites → select your site → Settings → ensure Custom script is allowed.

2. Accept the localhost certificate in the browser

Open https://localhost:4321/temp/build/manifests.js directly in your browser tab first. Accept the SSL warning, then go back to your SharePoint page and append the debug query string.

3. Check browser Local Network Access (Chromium 142+)

Starting with Chromium 142, Edge and Chrome enforce new local network access restrictions. If the manifests silently fail to load, check the browser console for net::ERR_BLOCKED_BY_PRIVATE_NETWORK_ACCESS errors. The fix is to ensure your dev cert is trusted and the browser has granted localhost access.

⚙️ Build for Production

npm run build
npm run bundle -- --ship
npm run package-solution -- --ship

Upload the generated .sppkg from the sharepoint/solution/ folder to your App Catalog and deploy.

🔍 Quick Troubleshooting Reference

✅ Summary

• SPFx v1.22+ uses Heft, not gulp — install @rushstack/heft globally, not gulp-cli
• Node.js v22 LTS is the required version for SPFx v1.22+
• Install all three tools in one line: npm install @rushstack/heft yo @microsoft/generator-sharepoint --global
• Use heft trust-dev-cert to trust the SSL certificate
• Debug on a real SharePoint page using ?debugManifestsFile=https://localhost:4321/temp/build/manifests.js — the workbench was removed in SPFx v1.13
• The manifest path changed to /temp/build/manifests.js in SPFx v1.21 — update any bookmarks or scripts

Happy coding!