Office Apps and Services MVP,
Enterprise Architect 🟡🟡🟡
thoughts on Architecture, Automation, Development and Technical Leadership
M365 Azure SPfx PowerShell DevOps keep it simple. keep it honest. keep it real.

⚜️ Episode III of V - Setup your SPFx development in WSL2 ... with PnPWsl2 !

Third of a five-part journey is out !

The second episode, was around WSL2 (Windows Subsystem for Linux), THE tool you definitely need to have in your toolbox .

In this next one, we will dive into what in what is about to become indispensable to support your WSL2 journey …

A bit of background history

As you notice from my previous posts, I’m a PowerShell addict and huge a WSL2 fan.

I love command line tools, although most of them don’t have autocompletion, making us revisit command syntax help over and over again…

WSL rocks! but … it really doesn’t have a streamlined approached to manage WSL2 instances effortlessly - from automated backups and checkpoints, to seamlessly injecting new bits into instances, so we need to do it all manually, and that’s a bit of a nag.

Part of my work is to lead technical teams, and I wanted to make it easier for them to get started with WSL2 …

… and SharePoint Framework development environments
… and PowerShell
… and Azure Devops
… and Python
… and …

…well, you get the idea💡!

As mentioned before, WSL 2 uses virtualization technology to run a Linux kernel inside a lightweight utility VM, with awesome performance.

So it’s .. a virtual machine, a container and a subsystem, all at the same time.

What the software is really missing is the process to enhance even more the experience and that’s where PnPWsl2 comes in.

When I started building it, was very rough and crude around the edges, but it has evolved a lot and now it’s a must-have tool for WSL2.

So … let’s dive into it.

What exactly is, PnPWsl2 ?

PnP WSL2 is a PowerShell Module providing cmdlets designed to simplify WSL instances management experience, by providing streamlined tools and automation features, from backups and checkpoints to effortlessly injecting new components\features\tools into instances.

Fancy words for a tool that makes your life so much easier … 🤠

What can we do with it ?

  • Install\Uninstall WSL2 in your system with all dependencies
  • Create named WSL instances based on a linux distribution
  • Create\Restore WSL2 CheckPoints (timestamped vhdx files).
  • Copy a WSL instance to a new one.
  • Export\Import a WSL instance as tar\vhdx files.
  • List\Delete WSL instances.
  • Install apps\tools within a WSL instance easily, thanks to tab key autocompletion.

Think of it as a Swiss Army knife for WSL2, with a lot of tools, features and … extensibility !

A few examples of what you can do with it:

  • For starters, we can create Wsl 2 instance with the simple Add-PnPWsl2Instance cmdlet and select a distribution to be installed.
  • Each time time we create a new Wsl instance, PnPWsl2 automatically will create a checkpoint for us, so you can always go back to a clean state if something goes wrong.
  • We can easily copy a WSL instance to a new one .
  • Export a WSL Instance to a file .. and import it to a new instance.

All automated, streamlined and containerized 🤘 !

We can :

  • build\customize a environment
  • export it
  • share it with the team to import it and have the exact same environment (remember the first episode of the series ?)


We can use it to automate the setup of a SharePoint Framework development environment, and that’s where the 🧙‍♂️ magic happens …

Setting up a SharePoint Framework Development Environment in WSL2

Setting up the SharePoint Framework development toolchain is documented , still …

There’s a lot of work to be done manually. If you are a consultant in multiple clients, multiple tenants, multiple projects is daunting and it can be a little bit messy .

The official documentation is here

Usually we follow these steps:

  1. Install Node.js: Download and install a Node.js LTS Version.
  2. Install the development toolchain prerequisites (Git,Yeoman, Gulp and Microsoft\SharePoint Yeoman Generator)
  3. Install Visual Studio Code
  4. Trust the self-signed developer certificate
  5. Install other optional tools

We usually need to execute a few more steps to have a complete ready to go development environment, like configure git, create a sshkey to be shared between wsl and windows , upload it to our AzureDevops\GitHub, and so on…

The “problem”

The “problem” with this process is that it is not streamlined\automated: we have to download\install each one of the components, and configure them all manually, align with what we need. #noteasy4anewbie #timeconsuming #pronetoerrors

The solution

The PnP.Wsl2 module comes with a bundle of tools that can help us to automate the process of setting up WSL2 and a SharePoint development environment from scratch, and also can help, applying those settings\tools\configurations in an existing SPFX development.

To enable WSL on the system we use the Enable-PnPWsl2 cmdlet

Then we need to create a new WSL instance : Add-PnPWsl2Instance -Distribution Ubuntu-20.04 -InstanceName mySpfxEnv


To create a ready to go new SPFX development with all steps mentioned before, we use the Add-PnPWsl2Candy cmdlet and the 🍭ub-spfx-FullDevEnvironment candy available

The “candy” is nothing more then a bash script that executes all of those mentioned steps one by one.

The candy will :

  1. Install build essentials (packages needs for compiling software inside linux)
  2. Install Nvm, Node (where you can select the version)
  3. Install gulp, yeoman ,microsoft yeoman generator
  4. Install spfxfastserve (a command-line utility that is used to improve the SPFX flow by speeding up the “serve” command)
  5. Prompts for a global git configuration
  6. Creates a SSHKey in Wsl , Copy that key to your windows host and upload it to a Azure DevOps instance

Kinda … cool no? 🤠

Plus … …
each one of the steps is a candy itself, and we can execute them in an isolated mode on any WSL2 instance we have !

It is a ⌛time saver : a way to ensure that all the steps are executed in the same way, no matter who is doing it, in a streamlined automated containerized manner.

We can have a complete SPFX development environment in a single command … and that’s a game changer, definitely …

Here’s a couple of screenshots of the process:

... and it's done ! A ready to go SPFX development environment !

In a nutshell, our WSL environment can be easily updated to be used as a regular frontend-development including SPFX, Teams development, Angular, we can use it to have PowerShell, Python, AI and Machine learning emerging stacks, … and so on …

Intentionally, i didn’t referred any link yet, in order for the reader to have an overview of the process, and to understand the simplicity and power of the tool.

Don’t worry , it’s at the end of the article .

What do you think?

Is it a tool that will make your life easier?

Its being already used within some companies\partners\clients and the experience\adoption has been overwhelming …

The code is open source 🤠 aka free to use, and you can contribute to it, so if you have a cool idea, or a feature that you think is missing, … make it even better !

Share your thoughts in a tweet using #PnPWsl2 , in the comments below, in a email or whatever channel you like to use.

I would love to hear from you. #anyfeedbackisgoodfeedback

Where to find it ?

The documentation is here : PnPWsl2 where you can follow the instructions to install the PnP.Wsl2 PowerShell Module and start using it. There’s a lot of cmdlets, and a lot of features, so take your time to explore it.

Don’t forget to take a peak at all the candy available also, we now can have a WSL2 Instance ready to go with : PowerShell Core, PnP.PowerShell, AzureCli, PnPCli-microsoft365, Node, SSH & PAT creation and integration, a ready to go Machine Learning environment, and so on … (24 candy and counting !)

Whats next …

Stay tuned, and get ready for the next episode Episode IV of V - … where we are going to leverage the tool to enhance other areas besides SharePoint Framework environments !

See also

Rodrigo Pinto