Getting started with SharePoint Framework (SPFx)

With SharePoint Framework (SPFx) you build your own web parts and extensions for SharePoint Online, Teams and Viva Connections. It is the official, Microsoft-supported model: your code runs in the page, with the user’s permissions. This guide sets up a development environment and creates a first web part.

What changed: Heft instead of gulp

Since SPFx 1.22, a new project builds with Heft (from Microsoft’s Rush Stack) instead of gulp. Older tutorials using gulp serve and gulp bundle apply to projects on 1.21 or older. In a new project you run everything through the npm scripts in package.json.

Node.js: exactly the right version

Each SPFx version supports one Node range. Current versions require Node 22 (22.14 or later, not 23 or 24). Use a version manager so older projects keep their own Node. On Windows that is nvm-windows:

winget install --id CoreyButler.NVMforWindows --source winget
nvm install 22
nvm use 22
node -v

Installing the tools

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

Creating a project

md mijn-webpart
cd mijn-webpart
yo @microsoft/sharepoint

The generator asks for the solution name, the type (web part, extension or library) and the framework. “React” is the most common choice; “No framework” suits something very small.

Testing locally and building

# Start the local dev server (runs: heft start --clean)
npm run start

# Production build and .sppkg package (runs: heft test --clean --production && heft package-solution --production)
npm run build

Test in your own tenant’s hosted workbench: https://<tenant>.sharepoint.com/_layouts/15/workbench.aspx. The package then lands in sharepoint/solution/ and you upload it to the App Catalog.

PnP controls

The PnP community provides ready-made components, such as a people picker, a file picker and a taxonomy field. Pick the version that matches your SPFx version; the package documentation says which.

npm install @pnp/spfx-controls-react @pnp/spfx-property-controls --save

Known issues

• npm ERR! unsupported engine or EBADENGINE: wrong Node version. Check node -v and the engines field in package.json.
• An old project still uses gulp: keep it on its own Node version, or upgrade it step by step with m365 spfx project upgrade (see CLI for Microsoft 365).
• Web part does not appear after upload: the app was not deployed or not added to the site. Check the App Catalog and the site contents.