SharePoint Framework (SPFx) Quick Start (Updated 2022)

SharePoint Framework

Almost 2 years ago, I wrote a post on how to setup up your SPFx developer environment because, at that time, I found the available documentation to be very “challenging” to understand. Since then, the official documentation has gotten much better and if you want a walk-through that explains everything, follow the link in the next paragraph.

BLAH BLAH BLAH! Just take me to the code!

Even though this post is more wordy than I like, 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 good, but covers a lot of stuff that you might not need. If my guide doesn’t work for you, I would recommend that you go back to 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” installation from Microsoft with three tools that I use on a daily basis and feel are critical for developers that will be building many SPFx projects over long periods of time.

Tool #1. Node Version Manager (NVM)

The primary tool that I consider mandatory is Node Version Manager, which allows multiple versions of NodeJS to be installed on the device at one time. I don’t know of many SPFx developers that are not using a version of this program. Normally, to switch the version of NodeJS involves manually removing multiple frameworks as well as NodeJS and then starting over with a new version of everything. NVM allows for the user to quickly swap between versions with one command. Because of how NVM manages NodeJS, it actually swaps out the entire NodeJs environment that was configured with the previous version. To clarify, when you install a new version of NodeJS with NVM, you just get NodeJS and NPM. You will need to install all of the other packages you need for work. When you “use” a different version, you will find that version just as you configured it before.

There are two versions of NVM available, depending on your OS. The original NVM was written for Linux and MacOS. A developer named Corey Butler created a version of NVM that runs on Windows. The links for both versions are found in the “code” section below.

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 and all of the remote container options for development use Linux as the OS.
  3. Speed

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: the Windows file system is slow and the antivirus scanner was scanning each file in the npm install. Using WSL as my OS and file storage system decreased those installation times down to a couple of minutes!

The Linux version of NVM has a couple of other advantages over the Windows version of NVM, like aliases and dynamic versioning.

</rant about Linux vs Windows>

Tool #2. PNPM

If you have ever worked with NodeJS, you are familiar with the default Node Package Manager (NPM). NPM is used to install and update all of your project’s dependencies. As your projects grow in complexity, the number of files managed can be huge. As of this writing, a very basic SPFx project uses over 40K files to run the developer environment and the project itself. To do this, NPM installs those files in the project folder structure for every project. This is a lot of unneeded overhead that PNPM helps manage. I won’t get into the details of how PNPM does this, but effectively, every time a new package is downloaded by PNPM, it caches it in a common area of the hard drive and uses links to attach the package to the project. If a package is subsequently requested by a different project, PNPM just creates another link and doesn’t download the package again. The result is a much faster installation process as the number of projects grows and a much smaller footprint on the hard drive. The PNPM commands are nearly identical to NPM, so the learning curve is very small.

I do have to caveat this recommendation with a caution. While I use try to use PNPM on all new projects I build, occasionally there are references in SPFx that cause errors when PNPM is used to install all of the dependencies. If this happens, you can try to add the –shamefully-hoist flag to the “pnpm install” command. Sometimes this fixes it. The other caution is that if you make use of sample solutions from PnP, (and you should be doing this!) those projects already have a package-lock.json file, which means they were developed with npm vs. pnpm. There are ways to work around this, but sometime it’s just easier to use npm and remember to clean out the project, or at least the node_modules folder, when you are done.

Tool #3. CLI for Microsoft 365

While I have used PowerShell for years to manage Microsoft 365 and specifically PnP.PowerShell, this is a separate installation on your machine. Depending on the security requirements in your tenant, getting PowerShell set up tp 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. It’s capabilities are very similar to PowerShell, but it has a couple of things the PowerShell doesn’t. If you ever need to update an existing solution to a newer version of SPFx, the CLI ofr M365 has a command that will give you step by step instructions. I don’t know of any other tool that does that.

On to the code

  1. Determine the version of NodeJS to install. You should always install the latest version supported by the latest version of SPFx
  2. Install NVM using the appropriate link for your OS and follow the instructions to install NVM

  3. Run the following commands from your favorite command line prompt

    To do this Run this command
    Ensure nvm is installed nvm version
    List installed versions of NodeJS (Linux) nvm ls
    List installed versions of NodeJS (Windows) nvm list
    Install specific version of NodeJS nvm install 14.18.3
    Use specific version of NodeJS (Windows) nvm use 14.18.3

  4. Install our global tools.
    NOTE: As much as I love PNPM, I run into issues when I use it to install global packages. So, as a rule, I use NPM for global installs and PNPM for project installs.

    To do this Run this command
    Install Yeoman npm i -g yo
    Install Gulp npm i -g gulp-cli
    Install SPFx generator npm i -g @microsoft/generator-sharepoint
    Install pnpm npm i -g pnpm
    Install cli-m365 npm i -g @pnp/cli-microsoft365

    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 yo gulp-cli @microsoft/generator-sharepoint pnpm @pnp/cli-microsoft365

  5. Create a folder for your new SPFx project

    To do this Run this command
    Navigate to location where you create projects e.g., cd ~/..Code
    Create folder for new project mkdir firstproject
    Navigate to new project folder cd firstproject

  6. Create the project. I will not walk through all of the options to complete when you run the yo command below. There are plenty of articles out there that help with this. If this is your first project in SPFx, just accept all of the defaults to get you started on a simple Hello World webpart.

    To do this Run this command
    Create SPFx project1 yo @microsoft/sharepoint --skip-install
    Start VS Code with project code .
    Install project dependencies2 pnpm i --shamefully-hoist
    Install Developer Certificate3 gulp trust-dev-cert
    Run project gulp serve –nobrowser

    1 Because we want to use PNPM, we’ll use the –skip-install flag. We’ll manually install our packages in a minute. This also lets me start working in the code while dependencies are being installed.
    2 If you get errors when running the PNPM command, you can try the --sharefully-hoist flag. If you continue to have issues, use “npm install” instead.
    3 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 localhost server which delivers your code to SharePoint Online! If you need to set up an environment for a 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.