SharePoint Framework (SPFx) Quick Start (Gulp toolchain for SPFx v1.21.0 and earlier)

It’s been a while since I posted, but with SPFx v1.22.0 due out in the next couple of weeks, I decided to make a final update to this article on how to get started with SPFx using the Gulp toolchain. In case you haven’t heard, v1.22.0 will no longer use Gulp as it is being replaced with Heft. The main reason for this change is that the Gulp toolchain has been very difficult to keep up-to-date, and the internal engineering teams at Microsoft switched to Heft a while back. Since they are actively maintaining Heft for their own use, we will now benefit from that work.

Expect a companion post soon on getting started with SPFx using the Heft toolchain.

Since I last updated this article, I have changed some of the tools I use to manage my SPFx development environments. The main change is that I have switched from NVM (Node Version Manager) to FNM (Fast Node Manager). I’ll explain why in the FNM section below, but the bottom line is that NVM works just fine. If you are using NVM and are happy, stick with it. If you are looking for something new, give FNM a try.

The other change is that I no longer use PNPM as my default package manager. While I managed to overcome many of the issues with PNPM and SPFx, PNPM changes frequently and many of those changes require me to update my whole toolchain. If you want to use PNPM, I recommend reading my previous articles on the Quick Start guide.

OK, let’s get to it.

TL;DR Just take me to the code!

This is the Quick Start guide I use when I am setting up a new computer to work with SPFx. Microsoft has a very detailed guide for SPFx setup at Set up your SharePoint Framework development environment. The Microsoft guide is comprehensive, but it covers a lot of stuff that you might not need. If my guide doesn’t work for you, I recommend checking out the official documentation. When working with SPFx, there are lots of additional tools that can be installed to enhance your development experience. For this Quick Start, I wanted to keep those tools to a minimum. I deviate from the “stock” Microsoft installation with two tools that I use daily and consider critical for developers building many SPFx projects over time.

Tool #1. Fast Node Manager (FNM)

The primary tool that I consider an absolute necessity is an app that allows multiple versions of NodeJS to be installed on your device at the same time.

Normally, switching NodeJS versions involves manually removing multiple frameworks as well as NodeJS itself, then starting over with a new version of everything. Version managers allow you to quickly swap between versions with one command. Because of how a version manager works, it actually swaps out the entire NodeJS environment. To clarify: when you install a new version of NodeJS with FNM, it installs both NodeJS and NPM. You will need to install all of the other packages you need for your work. However, when you swap to (i.e., “use”) a previously installed version, you will find that version exactly as you configured it before.

I don’t know of many SPFx developers who aren’t using a NodeJS version manager. While the most popular app for this is Node Version Manager (NVM), there are several alternatives, each with their own pros and cons. I have chosen FNM for several reasons:

1. Speed - FNM is written in Rust, which is a compiled language. NVM is written in Bash script, which is interpreted at runtime. This makes FNM much faster than NVM.
2. Cross Platform - FNM works the same on Windows, MacOS, and Linux. NVM has two different versions, one for Linux/MacOS and another for Windows. While they work similarly, there are differences in commands and features.
3. Simplicity - FNM has a smaller set of commands and features, which makes it easier to learn and use. NVM has more features, but I find that I don’t need most of them.
4. Active Development - FNM is actively developed and maintained, with new features and bug fixes being released regularly. NVM is still maintained, but updates are less frequent.

SIDE NOTE

Over time, I have switched my primary dev environment from Windows to Linux. I have three reasons for this:

1. Speed
2. Windows Subsystem for Linux (WSL) is easy to set up and use. All of the remote container options for development use Linux as the OS. In fact, WSL is just a container running Linux on Windows.
3. Speed!!! See below for more details

When I was using Windows as my dev environment, it would sometimes take over 10 minutes to do the initial “npm install” on a new project. It was horrible and I didn’t have the option to get a better machine since it was provided by my employer. Once I started playing with WSL, I learned that the slowness issue was caused by two things:

1. The Windows file system is slow
2. My antivirus scanner was scanning each file downloaded as part of the npm install, over 65,000 files for a React webpart! Using WSL as my OS and file storage system decreased those installation times down to under 2 minutes!

</rant about Linux vs Windows>

Tool #2. CLI for Microsoft 365

While I have used PowerShell (specifically PnP.PowerShell) for years to manage Microsoft 365, that requires a separate installation on your machine. Depending on the security requirements in your tenant, getting PowerShell set up to work in M365 can sometimes be challenging.

The CLI for M365 tool is a command line interface that works in any terminal environment and installs the same way all of your other Node packages do via npm. Its capabilities are very similar to PowerShell, but it has a couple of features that PowerShell doesn’t. It have tools to evaluate your environment and project for issues. If you ever need to upgrade an existing solution to a newer version of SPFx, the CLI for M365 has a command that gives you step-by-step instructions. I don’t know of any other tool that does that.

I don’t alway install this tool when setting up a new SPFx environment, but often come back later to install it as needed. If you want to learn more about the CLI for M365 tool, check out the official documentation at CLI for Microsoft 365.

On to the code

Now that we have discussed the tools I use, let’s get to the code. The following steps will get you set up with a basic SPFx development environment using Gulp as the toolchain. This guide assumes that you are building solutions for SharePoint Online (Microsoft 365).

If you are building solutions for SharePoint Server (on-premises), you will need to modify the NodeJS version and SPFx version to match your target environment. For more information on which versions to use, refer to the series of blog posts on this topic by Andrew Connell. Definitive Guides for developer to SharePoint Framework for SharePoint Server on-premises

1. Install FNM using the link below and follow the instructions for your OS to install FNM: https://github.com/Schniz/fnm?tab=readme-ov-file#installation

2. Determine the version of NodeJS to install. You should always install the latest NodeJS version supported by your targeted version of SPFx.

   • To determine this, visit SharePoint Framework Platform & Toolchain Compatibility Reference
   • For this guide, I am building a solution for SPFx v1.21.1, which is the last version to use the Gulp toolchain. Based on the NodeJS versions available as of this writing, I’ll use NodeJS v22.21.1.

3. Run the following commands from your favorite command line prompt to install NodeJS and get it ready for the next steps.

4. Install the global tools. NOTE: the -g flag installs the packages globally so they are available in any folder on your device.

NOTE 2: All of the above tools can be installed with one command. I like separating them to make it easy to troubleshoot if there are issues. If you would prefer to install them all at once, use the following:

npm i -g gulp-cli yo @microsoft/generator-sharepoint @pnp/cli-microsoft365

5. Create a folder for your new SPFx project

6. Create the project. I won’t walk through all of the options available for the “yo @microsoft/sharepoint” command below - there are plenty of articles out there that cover this. If this is your first SPFx project, just accept all of the defaults to quickly get started with a simple Hello World web part.

¹ Because you need to connect SharePoint Online with your localhost server, you need to install the developer certificate included with SPFx. This is accomplished with the “gulp trust-dev-cert” command. This only has to be run once on each device you are setting up. If you are running in WSL or any other remote container, you will have to manually download the certificate and install it on your host machine. I have another post that explains this. Developer Certificate changes

Well, that should get you started! The “gulp serve –nobrowser” command starts up the server on your local machine, which makes your code available to SharePoint Online! If you need to set up a new environment for a different version of SPFx, start at step 3 above and quickly build your new environment.

Please leave comments below if you find errors or issues with my approach. I’d love to learn from you.