Setting up a development environment for the latest refresh of the SharePoint Framework SPFx (v1.22)
This is a short get-you-started guide to setting up a development environment for the newly released SPFX version 1.22.
Useful (indispensable) resources include:
- General Availability of SharePoint Framework 1.22 – A Major Refresh of the Build & Tooling Experience
- Set up your Microsoft 365 tenant
- Set up your SharePoint Framework development environment
Virtualize or not to virtualize, that is the question?
I currently use a fairly hefty Dell laptop as my main development rig using a fairly old (but very stable) SPFx version 1.18. I never moved beyond this version because most of the enhancements were focused on Adaptive Card Enhancements (ACE) which I don’t develop and TBH, I have yet to truly grasp their supposed importance – none of my customers have demanded ACEs – maybe that will come in time?
To help me sleep easy at night, I push all my project source code to GitHub giving me some confidence that in the event of catastrophic laptop failure I can restore my projects, or at the very least I have the source code to rebuild them manually.
This post is not about how to sync your projects to GitHub but if you don’t do this already, I seriously urge you to figure out how to do this now! I have several custom solutions for customers, not mention products in the Microsoft Marketplace and if I were to lose, what amounts to years of intellectual property, I think I would lose the will to live!
Making the leap from SPFx v1.18 to v 1.22 is significant because the tool chain has been revolutionised. I won’t pick over the details because they have already been documented and scrutinized (in much greater detail than I would care to muster – or indeed would be capable of doing) by Andrew Connell at SharePoint Framework v1.22: What's in the Latest SPFx Update.
Despite my confidence in my source code back-up strategy, I must confess to being somewhat nervous of updating my primary development rig for fear of stuffing it up. The prospect of rebuilding everything from scratch is not how I would prefer to waste a day (or more).
So, I decided that a much safer approach will be to build a new dev environment from scratch on a sperate machine. Rather than buy another laptop I decided a better approach would be to stand up a virtual machine in Azure and make that my new development environment.
Setting up a new Windows 11 machine in Azure is a fairly trivial and routine exercise, which took less than 5 minutes (I’ll spare you the step through guide because, quite frankly, if you’re not capable of figuring that out for yourself the rest of this guide is likely to be beyond your skill set – that may sound harsh or arrogant but that doesn’t mean that it’s not true).
Just a word of warning. VMs in Azure aren’t cheap and you’ll want a reasonably high spec one with at least 16GB of RAM. The Azure cost estimator warned me that I could expect a monthly bill of $180. However, that cost is based on running 24/7 and we won’t need the machine 24/7. So long as we remember to turn the VM off at the end of every dev session we should be able to cut this bill by 80% I reckon (so long as we remember to switch it off!).
With hindsight, I might have been better to use a VM from the outset, but I didn’t, so moving on.
Ok, so my new clean Windows 11 VM is up and running in Azure and I can connect to it via a remote desktop session. The rest of this article will step you through my experience of setting things up for SPFx v 1.22
Install Node Version Manager (NVM)
Although only mentioned in passing in one of the above linked articles, I strongly recommend that you download, install and use NVM.
The rationale here is that as new versions of the SPFx are released they are tied to specific versions (or a version range) of Node. This means that you might at some point end up with projects that have a dependency on a different Node versions.
Without NVM this is a real pain as you might need to constantly uninstall and reinstall the appropriate Node release. With NVM, this is a breeze because it allows you to install multiple version of Node alongside each other. You simply select the one you need for a project and switch back at will.
Use NVM – it’s free and I promise you won’t regret it! The steps are:
Download NVM for Windows
- Go to the official GitHub page:<br>https://github.com/coreybutler/nvm-windows/releases
- Download the latest nvm-setup.exe installer.
Run the Installer
- Double-click nvm-setup.exe.
- Follow the prompts:
- Choose an installation directory (default is fine).
- It will also ask where to store Node versions (default is fine).
Node
After installing NVM, open a PowerShell console and install version 22 of Node by running the following:
nvm install 22
Then we need to tell NVM which version of Node we want to use by running:
nvm use 22
And then, just to confirm all is well
node -v
To confirm that you are using the version of Node now required by the latest SPFx release
Version 22 of Node has nothing to do with us using SPFx v1.22. The parity of version numbering (22) is merely a coincidence and you need to check the latest Microsoft documentation (3rd reference link in this post) to make sure that the version of Node you are using is compatible with your intended SPFx version.
Installing the Toolchain
I won’t dwell on this too much as it has all been adequately documented by Microsoft (3rd link above again)
Heft
Heft replaces Gulp – there you can’t more succinct than that! Install it by running:
npm install @rushstack/heft –global
You’ll want to deploy this globally, unless you have a good reason not to.
As you can see, I am notified that a new version of npm is available, but I’ll skip over that for now, assuming that this is not going to be an issue.
Yeoman
From the PowerShell console run:
npm install yo –global
We still need Yeoman and will want to install that globally as well.
Yeoman Generator
And we still need the Yeoman scaffolder for SPFx projects so we install that globally as well:
npm install @microsoft/generator-sharepoint –global
Developer Certificate
As this is a new development environment, we need to create and trust a self-signed developer certificate by running:
heft trust-dev-cert
However, if you try that from the consol now, you’ll end up with an error message like that shown below:
It is not entirely obvious but what we need to do is first scaffold a project and then run the command from with the project – so I’ll come back to this in a moment.
The good thing is that we only need to run this once in our development environment and then not worry about it again.
Actually, the above is not strictly true. A self-signed certificate only lasts for 3 years. If your cert expires you’ll find that none of you projects will build successfully any more. To get things sorted you can just run the above command again, first you have to forcibly remove the old cert (you have been warned).
M365 Tenancy and Visual Studio Code
I assume that you already have an M365 Tenancy that you can develop against. If not, follow the guidance provided in the 2nd link in this article.
You’ll also need an IDE of course. If you have a preference for Webstorm or Atom or even a full version of Visual Studio then good for you. However, I’ll stick with the mainstream and go with Visual Studio Code because:
- It’s free
- It’s from Microsoft
- It’s really rather good!
I won’t distract you or insult you with screenshots showing how to download and install VS Code but rather just assume that you know how to do this and have done so.
Why most developer stick with the default dark theme is beyond me – I much prefer the light theme. When I installed VS Code I selected the option for Windows File Explorer menu integration and would recommend you do the same – but that’s up to you of course.
Creating a test project
To make sure all is well, we need to fire up VS Code, create a test project and make sure all is well.
Where you create and manage you project files is up to you but I have experienced some challenges when trying to provision projects on a network drive (maybe that’s just me). In my new VM I don’t have a network drive in any case and so I have simply create an SPFx folder in the Documents folder, just to confirm all is as it should be.
Fire up VS Code, open the SPFx folder (and make yourself and the folder trusted of prompted to do so).
Then open a new Terminal in VS Code and follow the instructions at Build your first SharePoint client-side web part (Hello World part 1)
As guided, run the following:
yo @microsoft/sharepoint
And now we need to be patient – it was a full minute before my console responded with the familiar start point for provisioning a new project.
I am assuming that you have done this before so won’t bore you with unnecessary screenshots. For my test project I just ran with the staple Hello World web part using the React library.
One thing that was noticeably different was that for a long while I didn’t see a running action script of events as they were processed but instead this weird spinner kept flashing in the console.
I’m hoping that things might speed up when I scaffold subsequent projects, but this first project took noticeably longer to provision than I was used to, over 15 minutes! Along with a list of deprecation warnings (admittedly fewer than normal), it eventually is spat out the faithful Congratulations message alongside the ASCII art.
Let’s do as it says and run:
npm run start
This kicks off the build process and we wait patiently for it to complete.
Hey what’s this?
Oh yea, we forgot to install the dev cert and rather than just bail on us, the UI is now asking if we want to install a certificate – nice. Presuming that we do want to get things working, simply click yes in the dialog.
Great that seemed to work but I forgot to set the page domain name in the ./config/serve.json file and so got the inevitable message:
Swapping this out with my actual dev tenancy domain name and I was expecting all to be well, but it wasn’t.
Knowing that the workbench is on the way out, I figure it is likely an issue with that, and so what I did was set up a text page and just appended the necessary debug params to the URL
?debugManifestsFile=https%3A%2F%2Flocalhost%3A4321%2Ftemp%2Fbuild%2Fmanifests.js&debug=true&noredir=true
That cured it (although I did need to click through a trust dialog the first time)!
What about SPFx Fast Serve
I use the spfx-fast-serve solution with all my projects. Why, because it is an awesome solution that speeds up development cycles no end (the work of a genius name Sergei Sergeev).
My gut feeling was, that with the move to Heft, this wouldn’t work with SPFx v 1.22+, but I plugged the question into Copilot and got this cautiously optimistic response.
Ok, let’s give it a go!
npm install spfx-fast-serve -g
Which you only need to do once for the environment if you deploy in globally
Followed by:
spfx-fast-serve
but here is blows up with:
Which is no surprise as we are no longer using gulp!
I tried adding a missing stub file and this got me past the first hurdle.
But then it failed at:
npm install
The reason is obvious, and as reported in the output – no matching version for SPFx 1.22 could be found.
I think I just need to be patient and hope that Sergei will provide support at some point in the future.
In conclusion
So there we have it. Setting up a new clean development environment for SPFx v1.22 proved to be fairly painless in the end.
I guess it generally make sense to move to the latest and greatest release but in this instance, for anything but test projects, I’m going to hold off for a while. I haven’t tried the PnP JS libraries, or PnP Controls but this version of the SPFx represents such a sea change that but I suspect, as with spfx-fast-server, there may be a bit of catch up time required before things are fully bedded down.