Build Your First SPFx Web Part with the Current Heft Toolchain

The SharePoint Framework, or SPFx, is Microsoft's supported client-side extensibility model for SharePoint Online. It can produce web parts, extensions and components that also surface in selected Microsoft 365 hosts.

For a new production project, use the exact Node.js and toolchain versions in Microsoft's current SPFx compatibility table. At the time of this review, SPFx 1.23.2 supports Node.js 22, uses React 17.0.1 and uses the Heft toolchain for new projects. Do not copy a random global toolchain from an older tutorial.

Fact-checked against Microsoft Learn on 24 August 2026. Microsoft is also developing a new SPFx CLI, but its documentation is marked pre-release. This guide therefore uses Microsoft's production setup path with Yeoman and Heft.

What you need

A supported Node.js 22 release listed in the SPFx compatibility table.
npm, supplied with Node.js.
A code editor such as Visual Studio Code.
A SharePoint Online test tenant or approved development site.
Permission to use the tenant app catalogue if you will deploy the package.

Use a Node version manager if you maintain older SPFx projects. SharePoint Server projects can require older SPFx and Node combinations than SharePoint Online.

1. Install the production toolchain

Microsoft's current environment guide installs Heft, Yeoman and the SharePoint generator globally:

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

Confirm the commands are available:

node --version
npm --version
heft --version
yo --version

Do not assume “latest Node” means “supported by SPFx”. Check the compatibility page before upgrading a build agent or developer workstation.

2. Scaffold a web part

Create an empty folder, change into it and run the generator:

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

For a first project, select SharePoint Online, a web part, and the minimal or no-framework option unless you specifically need React. Names and prompts can change between generator releases, so read what the generator displays rather than copying keystrokes blindly.

The generated project pins its own dependencies in package.json. Commit both package.json and the lock file, but not node_modules.

3. Trust the local development certificate

SPFx local endpoints use HTTPS. Microsoft's setup guide requires trusting the development certificate once on a workstation. Use the command generated for the current project and follow your organisation's workstation policy.

Never ignore a browser certificate warning as a permanent development setup. If certificate trust fails on a managed device, ask the endpoint administrator rather than weakening browser security.

4. Run and debug the web part

For a current Heft project, start the development server with:

heft start

Microsoft says this starts local HTTPS endpoints and builds the project for debugging. The hosted SharePoint workbench is deprecated and is scheduled for retirement on 1 December 2026. Use the SPFx Debug Toolbar path for durable debugging instead of designing a workflow around the retiring hosted workbench.

Test with non-sensitive data on a development site. Local JavaScript still runs in a SharePoint page context and must be treated as application code, not harmless page decoration.

5. Build and package for deployment

Use the scripts and Heft commands supplied by the generated project. Before packaging, inspect config/package-solution.json, especially the solution name, version, features and tenant-wide deployment setting.

A typical release process is:

Restore from the committed lock file on a clean build agent.
Run linting, tests and the production bundle/package commands defined by the project.
Review the generated .sppkg package.
Upload it to a test app catalogue.
Deploy it to a test site and verify the actual page behaviour.
Promote the reviewed package through your change process.

Uploading an .sppkg file is not proof that a web part works. Test the page, API calls, permissions, browser console, responsive layout and error states.

Permissions are separate from deployment

An SPFx package can request Microsoft Graph or other API permissions. A tenant administrator must review and approve those requests separately. Do not request broad scopes because they make development convenient.

Also check:

whether the component reads more SharePoint content than the current user expects;
whether secrets have been incorrectly embedded in browser code;
whether third-party npm packages are maintained and licensed appropriately;
whether telemetry and external network calls are documented;
who owns upgrades when SPFx, Node or dependencies change.

Client-side code cannot safely hold a confidential client secret. Put secret-bearing operations behind an appropriately secured service.

Existing gulp projects are not automatically broken

New SPFx projects moved to Heft from SPFx 1.22. Microsoft documents a transition path for existing gulp projects, with limited ongoing fixes and a future support boundary. Do not convert a working production solution during an unrelated feature change. Inventory custom build tasks, create a branch, and test the migration independently.

Build something the tenant can support

Join the SharePoint & Teams Admins Space for practical SharePoint development and administration decisions.