SharePoint Framework (SPFx) Quick Start (Heft toolchain for SPFx v1.22.0 and later)
With the release of SPFx v1.22.0, Microsoft has moved the default build toolchain from Gulp to Heft. This article provides a quick start guide to setting up a new SPFx development environment using Heft as the toolchain. If you are new to SPFx or just want to set up a new environment, this guide will walk you through the necessary steps.
The official documentation for setting up a SharePoint Framework development environment using Heft can be found at Set up your SharePoint Framework development environment. While that documentation is thorough and comprehensive, covering a lot of background and details. This guide provides a streamlined approach to get you up and running quickly. If you have any questions, I recommend referring back to the official documentation.
TL;DR Just take me to the code!
Recommended Tools
Before we get into the code, I want to highlight three tools that I consider essential for any SPFx developer.
Tool #1. FNM (Fast Node Manager)
Node.js can only have one version active at a time on a device. This can be problematic when working with SPFx, as different versions of SPFx require different versions of Node.js because each SPFx version is built against specific Node.js versions. Rather than manually uninstalling and reinstalling different versions of Node.js, a version manager can be used to easily switch between different versions. Node Version Manager (NVM) has been the go-to tool for this task for years and is still a valid choice. One of the downsides to NVM is that it only works on the Linux and MacOS operating systems. There is a separate app, NVM-for-Windows, that replicates many of the NVM capabilities for Windows users, but there are command differences. Neither NVM nor NVM-for-Windows are actively maintained.
Several months ago, I was looking for a cross-platform version manager and found several recommendations for FNM (Fast Node Manager). FNM is known for its speed and efficiency, making it a great choice for managing Node.js versions. It is my recommendation for SPFx developers looking for a modern, fast, cross-platform Node.js version manager. One feature I use often is the ability to create aliases for different Node.js versions. This allows me to quickly switch between versions with simple commands like fnm use spfx-1.22.0 or fnm use spfx-spo.
You can find more information about FNM and how to install it at the FNM GitHub repository. Most installations can be accomplished with a single command.
Tool #2. CLI for Microsoft 365
While not strictly required, the CLI for Microsoft 365 is a powerful tool that can simplify many tasks when working with SPFx. The CLI provides a set of commands that can be used to manage SharePoint sites, lists, libraries, and more. It also includes commands for working with SPFx projects, such as creating new projects, adding web parts, and deploying solutions. The CLI is cross-platform and can be installed using npm. You can find more information about the CLI for Microsoft 365 and how to install it at CLI for Microsoft 365 documentation.
Additionally, there is a VS Code extension available that provides an integrated experience for using the CLI within VS Code. You can find more information about the extension at CLI for Microsoft 365 VS Code Extension.
Tool #3. SharePoint Framework Toolkit
This is another tool that is not required, but makes working with SPFx projects much easier and in some cases, replaces the command line approach. The SharePoint Framework Toolkit is a set of tools that are available via a VS Code extension. Install it from the VS Code marketplace. You can find more information about the SharePoint Framework Toolkit as well as how to install and use it at SharePoint Framework Toolkit GitHub repository.
Step-by-step guide
Install FNM Using the link appropriate for your OS and follow the instructions to install FNM
a. Linux/MacOS: FNM Installation Guide
b. Windows: FNM Installation GuideDetermine the version of Node.js to install. You should normally install the latest version supported by the version of SPFx you are about to install
a. To determine this, visit SharePoint Framework Platform & Toolchain Compatibility Reference
b. For this guide, I am using Node.js v22.21.0 for SPFx v1.22.0To set up your environment, run the following commands from your favorite command line prompt
Command Description fnm --versionEnsure fnm is installed fnm install 22.21.0Install specific version of Node.js fnm alias spfx-1.22.0 22.21.0(Optional) Create an alias for this version of Node.js fnm use 22.21.0orfnm use spfx-1.22.0Use specific version of Node.js Install the global tools for SPFx development
Command Description npm i -g yoInstall Yeoman npm i -g @microsoft/generator-sharepointInstall the latest version of the SPFx generator. Use @next or @x.x.x for other versions npm i -g @rushstack/heft(recommended) Allows all Heft commands to be called directly (vs. npm run command) npm i -g @pnp/cli-microsoft365(optional) Install CLI for Microsoft 365 Create a new folder for your SPFx project and use the following commands within that folder to create the project
Command Description mkdir project-folderCreate folder for new project (use mdon Windows)cd project-folderNavigate to new project folder yo @microsoft/sharepointCreate SPFx project code .Start VS Code with project heft trust-dev-cert(once) Install Developer Certificate to run in SharePoint heft startRun project
TL;DR; Just the code
Still too many commands? Here is the complete code block to set up your SPFx development environment once you have FNM installed and know the version of Node.js you want to use:
fnm install 22.21.0
fnm use 22.21.0
npm i -g yo @microsoft/generator-sharepoint @rushstack/heft
mkdir project-folder
cd project-folder
yo @microsoft/sharepoint
code .
heft trust-dev-cert
heft start
As always, please let me know if you find any errors in this guide or have suggestions for improvement.