Setup WSL2 for SPFx development

The latest feature update to Windows 10 is packed with great updates. And there is one that I was particularly waiting for: WSL2. It allows you to run Linux on Windows and take advantage of its incredibly fast performance for SharePoint Framework (SPFx) solutions.

(The performance of SPFx development was something that I always wished could be improved. I even looked at using pnpm in the past with previous versions of SPFx to try to speed things up. In case you are still using SPFx 1.6.0 or 1.7.0, you can read more here and here)

In this blog post I will give you a step-by-step guide to help you configure WSL2 for SPFx development. If you spot that something is missing, please provide feedback.

Windows version 2004

Ensure you are running Windows version 2004 or later. You can have a later version if you are part of the Windows Insider Programme. Version 2004 was released on the 27th of May and I was lucky to get it really quick

windows update

Windows Terminal

You don’t have to install it, but it’s a great tool and you definitely should. It is also super easy to customise and make it look the way you always wanted a terminal to look like. And it’s now in version 1, so you can expect a stable experience.
You can easily install Windows Terminal from the Microsoft Store.

Install WSL2

Follow the setup process as provided in the official documentation and ensure you set version 2 as the default at the end.

https://docs.microsoft.com/en-us/windows/wsl/install-win10

Note: if you find any errors, open the link provided with the error as it will guide you through the solution.
At the end, it should look similar to this:

wsl list

Make it a pretty prompt

This step is only relevant if you have installed Windows Terminal as suggested. If you haven’t, go and get it!

Follow the instructions on the following link as it contains the steps to customise PowerShell and WSL

https://www.hanselman.com/blog/HowToMakeAPrettyPromptInWindowsTerminalWithPowerlineNerdFontsCascadiaCodeWSLAndOhmyposh.aspx

After you have done this, open Ubuntu on Windows Terminal to confirm it has the expected look. Mine just looks like this.

pretty windows terminal

The next steps will be completed within Ubuntu/WSL so don’t close the terminal.

Install NVM (Node Version Manager)

We will use NVM to install and manage multiple versions of node.js. NVM makes the process of switching between node versions really simple.

Full instructions to install are available here: https://github.com/nvm-sh/nvm

Install nodejs using NVM

We will install version LTS v10.x of node.js as this is the highest supported version for SPFx development. You can find a great blog post here with the supported versions for each SPFx version.

We will use version 10.20.1, so simply run:

nvm install 10.20.1
nvm use 10.20.1

Now run nvm list, and you should see something similar to this

Install compiler tools

This is required for generating the dev certificate with gulp trust-dev-cert later on! Don’t skip it!

sudo apt-get install build-essential

Setup SPFx dev environment

We are simply going to install the required global packages for SPFx development. Keep an eye on performance as SPFx packages should install on WSL2 a bit faster than on Windows.

npm install -g yo gulp
npm install -g @microsoft/generator-sharepoint

Trust SPFx dev certificate

In this step, we are going to create a certificate in Linux and install it on Windows . This is to allow your browser (on Windows) to trust SPFx localhost from Linux.

Create a sample SPFx project and install node modules with npm install.
Next run gulp trust-dev-cert to create the dev certificate

We now need to ensure that Windows can trust the certificate generated in Linux. Otherwise, you will see an unsafe page warning in the browser and face problems loading your solution.

In Linux, go to the directory where the certificate is created

cd /home/{username}/.gcb-serve-data/

Now we are going to install the certificate on Windows. There must be lots of ways to do this, but I found this one to be the simplest.
Open the folder using folder explorer from Windows. Yes, you can use Windows explorer to open WSL directories. How cool is that!

explorer.exe .

Double-click on the gcb-serve.cer certificate file and click on the Install Certificate... button at the bottom.

Select Current User and then the second option to select the store. Select Trusted Root Certification Authorities and finish the process.

install certificate

You can now run the task gulp serve and serve the files from your localhost on Linux to your browser on Windows! Give it a try to ensure all was setup correctly.

First time Git setup

We need to set some things up to ensure that Git plays nicely.
Open the GitHub website settings page and check the no-reply email for your account

It should be something with the following format: {ID}+{username}@users.noreply.github.com

Now set the following configurations (using your display name and no-reply email)

# Setup you identity to be used on commits 
git config --global user.name "John Doe"
git config --global user.email {ID}+{username}@users.noreply.github.com

# Additional settings when working with both Linux and Windows
git config --global core.filemode false
git config --global core.autocrlf true

Run git config --list to validate the settings

git config

Azure DevOps

This step is only required if you will also use Azure DevOps repositories. If that is not the case, jump to the next step.

In order to clone Git repositories from Azure DevOps, we are going to use SSH (not HTTPS). This will be done by sharing an SSH key between Windows and WSL.

Follow the steps under “Sharing an existing SSH key between Windows and WSL” from this great blog post: https://peteoshea.co.uk/setup-git-in-wsl/

The last command gives you the public key that you import into Azure DevOps so copy it to the clipboard.

Head to your DevOps portal, and select SSH public keys from the user settings menu.

Azure DevOps SSH keys

Add a new key by giving it a meaningful name and paste the public key string previously retrieved.

At this point all the configurations are done and you can clone a repository in WSL by using the SSH string provided.

clone repository

In WSL, simply do:

git clone {your-SSH-string-here}

The first time you clone a project you will see a warning like the below:

The authenticity of host ‘vs-ssh.visualstudio.com (XX.XX.XXX.XX)’ can’t be established.
RSA key fingerprint is SHA256:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.
Are you sure you want to continue connecting (yes/no/[fingerprint])?
Please type ‘yes’, ‘no’ or the fingerprint:

You can simply type ‘yes‘ to continue and add the host to the list of known hosts.

Using VS Code

Ensure you have VS Code installed on Windows and using the Remote – WSL extension.
In Linux/WSL2, go to the root directory of your SPFx solution and open code in the current directory

code .

This will open the solution remotely from WSL2 in VS Code. I suggest you always open the solution in VS Code this way to ensure that you always get the code from WSL. The Remote – WSL extension at the bottom right corner should look similar to this.

Next, go to the extensions tab and install the extensions that are missing in WSL. They will have an install button next to it.

Some extensions may request additional configurations once installed. Check VS Code notifications for new messages and follow any suggested steps as appropriate.

Play with it!

Everything should now be configured and WSL2 is ready for your SPFx solutions. You can now install any additional tools you may like and start playing with it.

As you can see from the following image, performance can be significantly better.
npm install is also noticeable faster. It only took about 25 seconds to install the packages of an SPFx solution with no JavaScript framework in WSL2.

WSL2 SPFx

2 thoughts on “Setup WSL2 for SPFx development

  1. Great article. Really informative.
    Little correction needed. Under “Using VS Code” section you wrote Remove-WSL extension instead of Remote-WSL.

Leave a Reply