SharePoint Framework React web part for SharePoint 2016

SharePoint Framework (SPFx) is page and web part model that supports client side development for SharePoint 2016 (Feature Pack 2) onwards. It’s certainly a major milestone for Microsoft to let developers use their favorite frameworks and open source tools, but if your solution is targeting SharePoint 2016, there are a few sacrifices you have to make, namely – downgrades. 

Node.js

If you try to scaffold and run SharePoint Framework project with Yeoman SharePoint Generator without preparing your environment, you’ll run into this or similar error.

~ gulp serve

ReferenceError: primordials is not defined
    at fs.js:36:5
    at req_ (C:\repos\spfx\node_modules\natives\index.js:143:24)
    (so on so forth...)

The reason is the version of node.js. For the time being (June 2020) SPFx only supports node.js 10.*.* for SharePoint 2019 or SharePoint Online and node.js 8.*.* for SharePoint 2016.

If you don’t want to alternate between different versions of node by reinstalling them, you should try nvm (or Windows version here). It allows you to flawlessly switch between different versions of node.js without the need to download and install them manually.

3rd party libraries

SharePoint 2016 only supports SPFx v1.1 which leads to some interesting scenarios when trying to utilize external libraries:

1. You are stuck with lower version of react.js (v15.*). Before you use any fresh features of off your favorite react libraries (Material-UI, Office UI Fabric etc.), make sure you’re installing a version that supports your version of React.
2. You are stuck with lower version of TypeScript (v2.4) (?). Not only it means some of the tricks you know might not work this time but also, if you strike to maximize the benefit of strong typing, you will need to specifically pick version of declaration files for any new library – latest version of types will most likely not support TypeScript below version 3. One of many painful examples here is the o-mighty PnP/PnPjs library.
3. You are stuck with Web Parts. SPFx for SharePoint 2016 does not support any other development model. One of the unexpected consequences here is that you can't use gulp serve configurations as you could with SPFx Extensions.

(?) interestingly enough, if you work with SPFx v1.4.1 you can try to upgrade to TypeScript 3.6 even though it comes with 2.2 by default.

To better understand dependencies between different SPFx versions and JavaScript libraries, refer to SPFx Compatibility Matrix.

ERR_SSL_PROTOCOL_ERROR 

If you are on Windows, one of the most common problems is SSL error when serving your solution to local workbench with gulp.

~ gulp serve

This site can’t provide a secure connection
localhost sent an invalid response.
Try running Windows Network Diagnostics.
ERR_SSL_PROTOCOL_ERROR

The solution here is to set NODE_NO_HTTP2 environmental variable to 1. Normally, it can be done with set command:

~ set NODE_NO_HTTP2=1

but it limits it to this single command prompt, so it's more convenient to change it in system settings.

Alternatively you can serve your project without https.

~ gulp serve --no-https

Why struggle?

Although SPFx setup and development for SharePoint 2016 can lead to occasional mental breakdowns and anxiety, we believe it’s still worth to familiarize oneself with this development model. It’s already much easier to get started when targeting SharePoint Online (go back to compatibility matrix if you’re wondering why) and will surly become even smoother as SharePoint development catches up with modern web development. For the time being – be patient and good luck.