Start your SharePoint with SPFX

SPFx (SharePoint Framework) is Microsoft’s current framework for building client-side web parts and extensions with TypeScript and React. The basic shape of getting started hasn’t changed, but two real pieces of the toolchain have — the build tooling and the way you test locally — and a lot of “getting started” guides still show the old versions. This post covers the current setup and flags exactly where it’s changed.

In this post: Setting up your environment · Scaffolding a new project · Gulp vs. Heft: which commands you’ll actually use · Testing: the workbench is being retired · The OpenSSL error that isn’t your code · Packaging and deploying · Related reading

Setting up your environment

Node.js version matters more than it used to — SPFx pins to specific Node major versions per release, and installing whatever Node happens to be current is a common source of scaffolding failures that have nothing to do with your actual code. As of the current SPFx release (1.21+), Node.js 22 LTS is the supported version; earlier SPFx releases (1.18-1.20) expect Node 18 LTS instead. Check the SharePoint Framework compatibility reference before installing Node, not after hitting a cryptic Yeoman error.

npm install -g yo @microsoft/generator-sharepoint@latest

Worth flagging directly since it shows up in a lot of older guides: installing gulp globally alongside Yeoman used to be a required step. It no longer is for a project scaffolded with the current generator — see the Heft section below for why.

Scaffolding a new project

From an empty project folder:

yo @microsoft/sharepoint

The prompts ask for a solution name, target (SharePoint Online, or SharePoint Online plus Teams/Outlook/Office), component type (web part, extension, or adaptive card), and framework (React, plain TypeScript, or no framework). The choices here set the shape of everything generated afterward — worth deciding deliberately rather than accepting defaults, since changing framework choice later means re-scaffolding, not reconfiguring.

SPFx 1.22 replaced its gulp-based build tooling with Heft — a project scaffolded today runs on different commands than a “gulp build / gulp serve” guide from even a year or two ago.

Gulp vs. Heft: which commands you’ll actually use

This is the biggest real change to getting-started SPFx guidance in a while, worth being explicit about rather than quietly correcting: starting with SPFx 1.22, the gulp-based build toolchain was replaced with Heft, Microsoft’s own task orchestrator. A project scaffolded with the current generator uses Heft commands, not gulp ones — older projects (or anything scaffolded before 1.22) still run on the gulp toolchain and keep working as-is, so this isn’t retroactive, but it does mean a guide showing gulp serve is describing the previous generation of tooling.

gulp serve is now heft start — runs the local dev server.
gulp build and gulp bundle are combined into a single heft build.
The --ship flag is now --production for a production build.
gulp package-solution --ship stays largely the same — packaging wasn’t part of what moved to Heft.

If you’re following an older tutorial and a gulp command fails outright rather than just warning, checking whether the project was scaffolded on 1.22+ is worth doing before assuming the tutorial itself is wrong — it might just predate this change.

Testing: the workbench is being retired

A second real change, easy to miss if you learned SPFx a while back: the local workbench — a standalone test page bundled with the toolchain — was removed from SPFx entirely after version 1.12.1 and hasn’t shipped with any current release. What most guides mean by “the workbench” since then is actually the hosted workbench, a page on your own SharePoint tenant (/_layouts/15/workbench.aspx) that loads your locally-running dev server’s bundle over the network — started the same way, with heft start (or gulp serve on older toolchains).

That hosted workbench is itself now being phased out: Microsoft deprecated it starting May 13, 2026, with full retirement scheduled for December 1, 2026. The replacement is the SharePoint Framework Debug Toolbar, which tests a web part directly on an actual modern page rather than an isolated workbench page — a more accurate test environment in exchange for a slightly different workflow. Worth switching to deliberately before the December retirement date, rather than discovering the workbench has simply stopped working.

The OpenSSL error that isn’t your code

Worth knowing before spending an hour debugging a web part that has nothing wrong with it: an older SPFx project built on a newer Node.js version (17+) commonly fails to start with ERR_OSSL_EVP_UNSUPPORTED. It’s not a bug in the project — it’s Node’s bundled OpenSSL 3.0 rejecting a cryptographic algorithm the older build tooling still tries to use by default, one that OpenSSL no longer allows without being told to. Two real fixes, not equally good: run the dev server with the legacy provider flag as a quick unblock (node --openssl-legacy-provider ./node_modules/.bin/gulp serve), or — the actual fix rather than a workaround — upgrade the project’s SPFx and `@microsoft/*` package versions to match a current Node LTS release rather than pinning Node down to satisfy old tooling indefinitely.

Packaging and deploying

Once the web part works against the hosted workbench or Debug Toolbar, building a deployable package is still a two-step gulp-style command on older toolchains, or the Heft equivalent on newer ones:

# Heft-based (1.22+)
heft build --production
gulp package-solution --ship

# Gulp-based (pre-1.22)
gulp bundle --ship
gulp package-solution --ship

Either path produces a .sppkg file under sharepoint/solution/. Upload it to the tenant’s App Catalog, approve any requested permissions, and deploy — from there it’s available to add to sites the same way any other web part is. A solution that includes SPFx components will prompt for API permission approval in the admin center on first deployment if it calls Microsoft Graph or another external API; that approval step is easy to miss and is the most common reason a freshly-deployed web part shows a permissions error the first time someone loads it.

SharePoint Online Modern Script Editor and Its Consequences — why SPFx replaced script injection as the supported customization path in the first place.
Are SPFx Solutions Still Ideal and Safe? — the longer-term case for building this way.

The framework itself hasn’t changed as much as the tooling around it has — checking which toolchain and test method a given guide assumes is worth doing before copying commands that might quietly be a generation or two out of date.