SharePoint Framework (SPFx) Quick Start

SharePoint Framework

For the several years now, I have concentrated on helping developers to get started coding in the SharePoint Framework (SPFx). My primary message has always been that, “despite it being a complete departure from previous coding approaches in the SharePoint, it’s not as difficult as it seems and you should just give it a try.” I am updating that presentation to include recent changes to SPFx as I prepare for upcoming engagements at North American Collaboration Summit (NACS) and ShareCloud Summit and will post it on this site when available.

BLAH BLAH BLAH! Just take me to the code!

In the meantime, I wanted to document 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 two tools that I feel are critical for developers that will be building SPFx projects over long periods of time.

Node Version Manager (NVM) for Windows

The one additional tool that I consider mandatory is Node Version Manager, which allows multiple versions of NodeJS to be installed on the device at one time. 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 toolchain that was configured with that 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 swap to a different version, you will find that version just as you configure it before. I plan to have a future post on some tricks with NVM that allow you to have multiple environments with the “same” version of NodeJS.

There are two NVM programs available. The original NVM was written for Linux and MacOS and is found here, but will not run on Windows. Up to this point, I have used Windows as my primary OS, so this is the version I use. Since the Windows version was written to be a clone of the original, my understanding that operating both is nearly identical after installation.

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 different project. This is a lot of unneeded overhead that PNPM helps manage. I won’t get into the detail of how PNPM does this, but effectively, every time a new package is downloaded by PNPM, it stores 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 the 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.

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 link appropriate 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 nvm list available
    Install specific version of NodeJS nvm install 10.18.1
    Use specific version of NodeJS nvm use 10.18.1

  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
    Install SPFx generator npm i -g @microsoft/generator-sharepoint
    Install pnpm npm i -g pnpm

    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 @microsoft/generator-sharepoint pnpm

  5. Create folder for your new SPFx project

    To do this Run this command
    Navigate to location where you create projects e.g., cd C:/_Code
    Create folder for new project md 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

    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 Windows has a small issue with how PNPM organizes the node_modules folder, so the way to ensure everything works is to us the --sharefully-hoist flag
    3 To use the local workbench without a privacy error, 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.

Well, that should get you started! The last command starts the interactive debugger and should open a browser that displays the local workbench that allows you to see live updates in your code. The local workbench is fine for designing your webpart, but once you need to connect your webpart to SharePoint, you’ll need to move up to the hosted workbench. Good luck building SPFx projects–we have only begun!

Since my blog does not support comments as of the writing of this post, p Please leave comments below if you find errors or issues with my approach. I’d love to learn from you.