When it comes to building web applications which heavily rely on platforms like Node.js, a Linux environment is often the best choice. These platforms were created with the Linux ecosystem as main target and, as such, tools like NPM (the Node Package Manager) provide much better performances than when they are executed on Windows due to the different file system implementation. On Windows, however, we have a much better graphical experience and a richer ecosystem of applications that we can use for our development purposes, from Visual Studio Code to all the major browsers.
Luckily, thanks to the Windows Subsystem for Linux, we don't have to choose anymore or go through the hassle of setting up a virtual machine. We can run a Linux environment right inside our Windows installation.
In this post, we'll focus on the experience in setting up WSL properly to build Viva Connections extensions (or any other extension based on SPFx, the SharePoint Framework) so that we can get the best of both worlds: the Windows experience, but the Linux performances when it comes to build and run our project.
Setting up WSL
WSL is available both on Windows 10 and Windows 11. The team has recently enabled a new installation experience so, if you don't already have it on your machine, all you have to do is open a terminal with administrator rights and run the following command:
wsl --install
The command will install Ubuntu as default distribution but, if you prefer, you can use another one by passing an extra parameter. You will find all the information and options in the official docs. During the process, you will be asked to create a new administrator user and to choose a password.
The best tool to work with WSL
is Windows Terminal, which is the default terminal in Windows 11. If, instead, you're using Windows 10, you can manually install it from the Microsoft Store. After you have installed WSL, in fact, a new tab will be automatically added to open up a new terminal on your Linux installation:
Setting up the development environment
Setting up the development environment to build projects with SPFx (including Viva Connections extensions) isn't different from setting up a Windows or MacOS machine, so we can follow the official guidance. As the first step, let's install Node.js. However, instead of installing the standard version, we're going to leverage nvm, a tool that you can use to install multiple versions of Node.js on the same machine. The main motivation is that, by default, you can have only a single Node.js installation on a machine, however some frameworks might require different versions to work properly. With nvm, we can easily manage this scenario since it allows us to install multiple versions of Node.js and then, with a single command, make one of them the "default" version installed on the system.
Open Windows Terminal, make sure to open tab on Ubuntu and run the following command:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
After the operation is completed, let's install a Node.js version. We can use version 16.x for SPFx, so let's run the following command:
nvm install 16
That's it. Since this is the only version we have, it will be automatically set as default version for the machine. If, in the future, let's say that we install a framework which requires Node.js v14.x, we can just run the following command:
nvm install 14
nvm use 14
If you want to check, at any point in time, which version of Node.js you're running, you can just type:
node -v
Now that we have Node.js up and running, we can leverage NPM to install the three tools which are required to work with SPFx:
- Gulp: it's a task runner based on JavaScript. It's used by SPFx to build projects, create bundles and run the testing environment.
- Yeoman: it's a tool to scaffold new projects, by providing a series of steps that the developer can follow to configure it.
- Yeoman SharePoint Generator: it's a specific implementation of the Yeoman generator for SharePoint. It contains various templates to create projects for SharePoint and Viva, like web parts or Adaptive Card Extensions.
We can install all of them by running a single command:
npm install gulp-cli yo @microsoft/generator-sharepoint --global
The tools will be installed as global, which means that you will be able to leverage them from any location on your machine.
Now that we have all the tools we need, we can start the creation of a new project. We're going to build an extension for Viva Connections.
Creating a new project
As a developer, you might already have a folder on your Windows machine (called src or Source, for example) where you store code projects. As such, when you start a new SPFx based project on WSL, you might be tempted to look for a way to store the project in the same folder. This is indeed possible: the local Windows drives are automatically mounted on WSL, so with a command like cd /mnt/c/Users/<your_username> you will be able to access your Windows user folder and all its subfolders. Don't do that! You will lose all the performance advantages which led you, in the first place, to adopt WSL to build your SPFx based projects. To gain the maximum file system performance, in fact, you must leverage the native Linux file system, which means that you will have to create your project in your Ubuntu user folder, instead of using the Windows one.
When you open Windows Terminal on Ubuntu, you will be automatically logged in to your home folder, so all you must do is create a folder to host your code:
mkdir src
cd src
Now let's create a folder to host our project and navigate to it:
mkdir viva-connections-hello-world
cd viva-connections-hello-world
Now we can generate our first project using Yeoman, by typing the following command:
yo @microsoft/sharepoint
We will be greeted by an ASCII user interface, which will ask a few questions to properly scaffold our new project. In this case, we're assuming we're going to build an Adaptive Card Extension for Viva Connections, so let's set the following properties:
- What is your solution name?: viva-connections-hello-world
- Which type of side client-component to create?: Adaptive Card Extension
- Which template do you want to use?: Basic Card template
- What is your Adaptive Card Extension name?: HelloWorld
After you have provided all the information, Yeoman will scaffold the project and will automatically use NPM to restore all the required dependencies.
Now that we have a project, we can build it and test it. However, there's an extra step we must take care of before: trusting the development certificate.
Working with the development certificate
When you are debugging a project created with SPFx, you leverage a SharePoint feature called Workbench: you're going to run the extension on your real SharePoint environment, but the code will be served by your local machine. This will allow you to test the extension in a real environment, but taking advantage of all the benefits of a local debugging system, like breakpoints, watchers, live reload, etc. To effectively use this feature, Yeoman generates a development certificate, which must be trusted by your own machine, otherwise your local environment won't be considered secure, and you will get all kinds of warnings and issues. Gulp provides a command to generate the development certificate. Go back to your Ubuntu environment in Windows Terminal and, in the root of your project, type the following command:
gulp trust-dev-cert
This command will generate the certificate, but when you run it on Linux it won't automatically trust it. As such, we must take a couple of extra steps, which Don Kirkham (Microsoft MVP) highlighted in his excellent post about working with SPFx on Docker. In our case we aren't using Docker, but we can apply the same technique to manage our certificate in WSL.
The first step is to copy the generated certificate in the root of the project, so that Linux can leverage it:
cp ~/.rushstack/rushstack-serve.pem ./spfx-dev-cert.pem
This command will place the certificate in the root of our project and rename it to spfx-dev-cert.pem. However, this isn't enough. Linux will indeed serve the extension, but in our case, Windows will consume it. When we start testing it, in fact, we won't use a browser running inside the Linux environment, but our favorite browser (Edge, Chrome, Firefox, etc.) running on our Windows machine. As such, we must trust this certificate on Windows as well, if we want to avoid warnings and errors from our browser that the content is coming from an unsafe source. The first step is to convert the generated certificate into a format that Windows can understand, since the .pem one we have works only for Linux. This is the command we can use:
openssl x509 -inform PEM -in ~/.rushstack/rushstack-serve.pem -outform DER -out ./spfx-dev-cert.cer
Now, in the root of our project, we'll have also a file called spfx-dev-cert.cer, which is the certificate we can use on Windows. To install it, we can leverage a feature that was recently added to Windows 10 and Windows 11: File Explorer integration. If you're using a recent version of Windows, you will see the following icon in File Explorer:
By clicking on it, you will be able to browse the Linux file system. As such, you can head to the path where you have created your Viva Connections extension (which will be something like \home\<your username>\src\viva-connections-oil-prices) to see the files which belong to your project. Double click on the spfx-dev-cert.cer file and follow these steps:
- Click on Install certifcate.
- Choose Local machine.
- Choose Place all certificates in the following store.
- Click Browse and seleted the store called Trusted Root Certificate Authorities.
- Click Next, then Finish to complete the import process.
You're all set! Now you're ready to launch and debug your extension.
Debug your extension
Now we can use gulp to launch the debugging experience of our project. Back to the Ubuntu terminal, type the following command:
gulp serve -nobrowser
Gulp will package the project and it will serve it through your localhost environment. One of the powerful features of WSL is that it's able to automatically tunnel the Linux network to your Windows machine. As such, even if your Viva Connections extension is being served by a process running in your Linux environment, it will be visible by your browser running on Windows. To test this, you can simply open your browser on Windows and open the following URL: https://localhost:4321/temp/manifests.js. If you did everything correctly, two things would happen:
- The browser will display the content of the manifest file for the Viva Connections extension.
- The connection will be reported as safe since the development certificate being used is trusted.
Now that we have verified that the server is working properly, open your favorite browser on the SharePoint workbench, which URL is https://<yourdomain>.sharepoint.com/_layouts/workbench.aspx. Then click on the + sign to add a new component to the page. You should see your extension available under a section called Local, as in the following image:
Please note! If you want the browser experience to be opened up automatically when you start gulp, you can edit the file called serve.json that you can find under the config folder, which looks like this:
{
"$schema": "https://developer.microsoft.com/json-schemas/spfx-build/spfx-serve.schema.json",
"port": 4321,
"https": true,
"initialPage": "https://enter-your-SharePoint-site/_layouts/workbench.aspx"
}
Make sure to replace the initialPageproperty with your real URL, then launch gulp without the -nobrowseroption:
gulp serve -nobrowser
That's great! Now we can fully leverage the power of the Windows ecosystem to test a web project which, instead, is being served by a Linux environment. But wait, what if we want to make some changes to the project? Surely, we don't want to deploy a HelloWorld solution to our customers!
Use Visual Studio Code with WSL
Visual Studio Code is the best editor to work with web projects and, in the context of WSL, it's even better. Visual Studio Code, in fact, supports the ability to remotely connect to a WSL instance, so that you can have your development experience on Windows, but edit, test and debug the code running on Linux. The first thing you need, of course, is Visual Studio Code installed on your Windows machine. The second step is to install the Remote Development extension, that you can find in the marketplace. Once it's installed, move to the Ubuntu terminal and simply type:
code .
If you are still running gulp from the previous task, make sure to stop it first or to open another Terminal session on the same folder before executing the command.
The first time WSL will install the Visual Studio Code Server extension, which is required for the remote experience. Once the operation is completed, Visual Studio Code will open. Compared to a standard execution, however, you will notice the following icon in the lower left corner:
Visual Studio Code is connected to our Ubuntu instance, but it's still providing a full development experience. Through the panel on the left, we can see all the files that belong to our project and edit them. If we open a terminal instance within Code, it will run in the Linux environment. You can also launch a debugging session, by using the built-in Hosted workbench target, which will enable you to put breakpoints, add watchers, etc. To get the full debugging experience, you have first to open the launch.json file under the .vscode folder. You will find a property called url set in the following way:
"url": "https://enter-your-SharePoint-site/_layouts/workbench.aspx",
Replace the URL with the one of your SharePoint websites. The next step is to launch gulp since the debugger won't do it for us automatically. In Visual Studio Code click on Terminal → New terminal, which will open a new terminal instance on our WSL installation. Type the usual command:
gulp serve -nobrowser
Then, once gulp is up & running, move to the Run and Debug tab in Visual Studio Code and click the play symbol near Hosted workbench:
The debugger will start, and it will launch a new browser instance on your SharePoint workbench. You will be asked to login to your SharePoint tenant and then you will be able to add your custom component to the page. Once the component gets added, you will trigger any breakpoint that you have placed in your project. As an example, you can try to place it in the onInit function declared in the file src/adaptiveCardExtensions/helloWorld/HelloWorldAdaptiveCardExtension.ts, which gets called when the component is rendered. As soon as you add the component to the page, you will see the breakpoint being hit, giving you the option to explore the content of each variable, the threads, the call stack, etc:
Wrapping up
Linux is a great platform when it comes to hosting web applications and working with SharePoint and Viva Connections isn't any exception. Thanks to WSL, we can get the best of both worlds: host our extensions in a Linux environment, so that we can get maximum performance, but still using the great tools and usability provided by Windows. And we don't have to do this by switching context or having to create our own virtual machine, but simply by opening a new tab in our terminal. WSL will do all the heavy work to blend the two ecosystems.
Happy coding!