Customers can leverage the SharePoint Framework (SPFx) in any of the modern or recent SharePoint versions. This includes SharePoint Online & SharePoint on-premises versions SharePoint Server 2016 & SharePoint Server 2019. To build a SPFx project, you use the Yeoman generator for the SharePoint Framework to create your project and get started. But there seems to be some confusion on which version you should install depending on your target SharePoint environment. Let’s clear this up, once and for all.
SPFx support in the different SharePoint environments
Microsoft made sure that the SharePoint Framework is supported on three different SharePoint environments. But only certain versions of SPFx are supported on each environment. Why? SPFx was built to be the way you customize and extend the modern UX. But Microsoft did do some work to back port client-side web parts to work in classic pages. This is what lets us work with SPFx in SharePoint Server 2016 (SPS2016).
When they added extensions to SPFx, they set the requirement that they would only work in modern pages. Because the modern UI was not added to SharePoint Server until SharePoint Server 2019 (SPS2019), which is why extensions aren’t available in SPS2016.
SharePoint Online (SPO) always supports the latest and greatest, partly because some of the features in the SPFx API require cloud services like Microsoft Graph & Microsoft Entra ID.
In summary, that leaves the support matrix for SPFx in the three most recent environments as follows:
- SharePoint Server 2016 (with Feature Pack 2) supports SharePoint Framework v1.1
- SharePoint Server 2019 supports SharePoint Framework <= v1.4.1
- SharePoint Online supports all versions of SharePoint Framework
Difference between the SPFx Developer Toolchain & SPFx Runtime
What I think causes confusion for many developers is that you have to look at SPFx as two distinct parts.
The SPFx Developer Toolchain is everything you need to develop a SPFx component. This includes the Yeoman generator for SharePoint Framework as well as utilities, and packages required to build, bundle and package your component.
The SPFx Runtime are the libraries Microsoft loads on a SharePoint page required to load and run SPFx component. These libraries are shared by all SPFx components and include things like the SPFx APIs for calling the HTTP endpoints, the Microsoft Graph, and more. In addition, these things are not included in your project; they are already deployed and hosted in the target SharePoint environment. All you deploy is YOUR code, not Microsoft code.
This is an important distinction… these two things are different, very different, and understanding the distinction is key to understanding what you want to install when you create a new project. Many developers get confused by this I think because the names are the same & there’s this mindset you have to have SPFx stuff installed on your machine to do SPFx dev. It’s not true.
Let’s use an analogy to try to clean things up. Note the bolded terms…
You use the Yeoman generator for the SharePoint Framework to create a SharePoint Framework project project that will result in building a package that you deploy to SharePoint that uses the already deployed SharePoint Framework runtime. You use any editor, such as Visual Studio Code, to develop the project.
Now, compare this statement to doing an ASP.NET web application with Visual Studio…
You use Visual Studio project templates to create an ASP.NET project that will result in building a package/series of assets that you deploy to a web server that has the already deployed ASP.NET runtime. You use Visual Studio to develop the project.
See the similarities and differences? With ASP.NET, you only use the Visual Studio project template wizard to create the project; you never use it again, just like the Yeoman generator. You don’t deploy ASP.NET when you deploy a project; it’s already installed on your web server, just like SPFx.
Let me be very clear on a few points:
You ONLY need Node.js, a package manager (npm), & Gulp-CLI installed to BUILD, RUN and/or PACKAGE a SPFx project
Let’s say I give you a SPFx project to play with, or you clone one from a source repo. What do you need to run it? Only two things:
- Node.js
- npm (or any package manager like Yarn or PNPM)
- Gulp-CLi (installed globally)
Why? Because an SPFx project has a list of all the things it needs within it’s package.json file. This includes the production pieces and development pieces (such as webpack & the SPFx local workbench). You get all those dependencies with npm. You run everything using Gulp tasks. And all these tools require the Node.js runtime in order to run.
This is true for every version of the SPFx and every SharePoint environment supported by SPFx.
You ONLY use Node.js, Yeoman, & the Yeoman Generator for SPFx to CREATE a project
But let’s say you want to create a project… what do you need? You ONLY need to have Yeoman and the Yeoman generator installed… that’s it! All this does is create the folders & files that define the project. Yeoman requires the Node.js runtime in order to run.
Once you have your project, the previous statement is true.
This is true for every version of the SPFx and every SharePoint environment supported by SPFx.
Which Version of the SharePoint Framework Should You Install?
Now, let’s get back to the point of my post… what version of the generator should you install for each SharePoint environment?
Easy answer for an easy question: Always install the most recent version of the generator, regardless of your SharePoint environment..
Before I get a comment on this post, let me be as clear as I can be. Today, the current SPFx generator version is v1.9.1. So…
- Install @microsoft/generator-sharepoint v1.9.1 if you are building for SharePoint Server 2016 (with Feature Pack 2)
- Install @microsoft/generator-sharepoint v1.9.1 if you are building for SharePoint Server 2019
- Install @microsoft/generator-sharepoint v1.9.1 if you are building for SharePoint Online
Remember what I said above:
- The SPFx generator is used to create the project scaffolding
- Each SPFx project contains a list of all it’s dependencies, including the versions of those dependencies
There are multiple reasons why you should always use the latest version of the generator:
- It contains all of the latest updates and fixes that apply to any/all environments.
- It contains all performance optimizations & improvements to the generator’s process in creating a project.
- It contains all changes to the project templates, such as omitting or including specific packages in the project’s package.json file.
Special Note about SharePoint Server 2016
There is one point that does need to be singled out related to SharePoint Server 2016. The above is still true: use the latest generator. This is mentioned in the SPFx docs Set up your SharePoint Framework development environment: Troubleshooting section, but let me add my own spin on it.
When the SharePoint Framework v1.1 was released, at that time the SPFx packages were built and tested to using the supported version of Node.js at that time: Node.js v6.x. At that time, the Node.js v6 web stack defaulted to HTTP1. This changed in Node.js v8 to it switching to HTTP2. The change in these two protocols required some changes to the SPFx packages so they could support both HTTP1 & HTTP2.
If you follow my guidance in this post (that mirrors what Microsoft will tell you), use the latest version of the Yeoman generator for SPFx, you will also install Node.js v10.x. Node.js v10.x also defaults to HTTP2.
But if you create a project for SharePoint Server 2016, it will contain references to the packages for SPFx v1.1 that still assume HTTP1. So, what you have to do is configure Node.js to use HTTP1, not it’s default of HTTP2. When Node.js v8 came out, they added the environment variable NODE_NO_HTTP2 which you could set to 1 to do this. To do this, you’d run NODE_NO_HTTP2=1 gulp serve.
However, that environment variable was removed in Node v10.
What does this mean?
At the present time, if you are working with SharePoint Server 2016 SPFx projects and you need the local web server, you will need to use Node.js v8. The current version of the SharePoint Framework generator, v1.9.1, still works with Node.js v8 but that may change in the future.
You need the local web server if you want to use the local workbench, or if you want to use the hosted workbench in SharePoint Server 2016 to test things.