What SharePoint Framework version can I use?

What version of the SharePoint Framework should you use for your project? 'The latest' seems an easy answer, but there is more to it.

SharePoint Framework versions

Over the last few years, we've seen a number of updates to the SharePoint Framework - the latest development model for extending SharePoint. At the time of writing this article, SharePoint Framework v1.9 has been released and v1.10 should be available shortly.

Between the different versions of the SharePoint Framework, you can distinguish three main streams: latest, which works with SharePoint Online, v1.4.1 which works with SP2019, and v1.1.0 which works with SP2016. And here is where things get confusing.

SharePoint Framework and the Yeoman generator

When we talk about the SharePoint Framework, there are actually two things that we refer to: the framework itself, and the Yeoman generator that we use to create new projects and add new components. The version of the generator matches the latest version of the SharePoint Framework for which it can create a project. For example, generator v1.8.2 can create SharePoint Framework projects for SharePoint Framework v1.8.2, but it can do more.

When Microsoft decided to support SharePoint Framework in SharePoint 2016, they decided to release one version of the SharePoint Framework Yeoman generator. Depending on the selected platform, it will create a project using the latest version of the SharePoint Framework, v1.4.1 or v1.1.0. And this is where things get tricky.

Inconvenient SharePoint Framework versions

With each release of the SharePoint Framework, Microsoft is updating the SharePoint Framework Yeoman generator. Unfortunately, sometimes things that used to work no longer do. On the other hand, if you took the generator v1.1.0 and created a project with it, it would likely work just fine. Which brings us to the question: should you use the latest version of the SharePoint Framework Yeoman generator?

Inconvenient SharePoint Framework and Yeoman generator versions

If you're building projects for SharePoint Online, the latest version of the SharePoint Framework will offer you the most benefits. One caveat is, that new releases often have errors so you might want to hold off for a week or two after a release to ensure that it works as expected.

If you can't use the latest version of the SharePoint Framework, there is no benefit for you to use the latest version of the SharePoint Framework Yeoman generator. After all, if you create a project for SP2019 or SP2016, it will be the same project that you would create using the generator from one or two years back! In fact, with using the latest version of the generator, there is only the risk, that something that previously worked just fine, won't work anymore.

Even if there were no regressions, there is this confusing idea, that while the SharePoint Framework Yeoman generator has been tested with the LTS version of Node.js available at the time of its release, it can create projects for use with versions of Node.js that are two years old, which also could lead to issues.

So what should you do?

SharePoint Framework Yeoman generator for you

If you need to create projects for SP2019 or SP2016 I'd recommend two options to choose from. Either, use NVM (for Windows or macOS/Linux) to install the LTS version of Node for SPFx v1.4.1 or 1.1.0 and install the original SharePoint Framework Yeoman generator or use the Docker images that I've published that contain all dependencies in them. Either way, use what's proven to work rather than bet on the latest version of the generator that has no added value for your on-prem projects and which could only cause trouble.