Definitive guide for developers: SharePoint Framework for SharePoint Server 2016

Microsoft’s updates about the SharePoint Framework, as well as articles, blog posts, and videos from the community showing off their projects all have one thing in common: they overwhelmingly focus on SharePoint Online & ignore SharePoint Server.

Customers who’re using the SharePoint Framework (SPFx) on SharePoint Server deployments, also known as SharePoint on-premises, never see new features or capabilities for their environments. Sure… you get it; Microsoft isn’t updating the SPFx for SharePoint Server from what’s already provided.

But as the SPFx keeps evolving and the tools keep updating, it’s hard to keep track of what is or isn’t supported on-premises.

It’s hard to keep track of what you need to create and maintain your SPFx solutions for SharePoint Server deployments.

If you’re reading this and nodding your head in agreement, and maybe with a bit of frustration, then this article is for you.

In this post, my goal is to provide the definitive guide to the SharePoint Framework for SharePoint Server 2016 on-premises deployments.

Overview

Let’s first start by setting expectations what you’ll find in this post.

• Limiting this to SharePoint Framework features. There very well may be features you argue that are related to the SPFx, but if it isn’t a SPFx feature, I’m not covering it.
• Limiting this to tools you need to create, run, & maintain SharePoint Framework projects. I’m not going to cover community tools or things from the PnP group.
• Limiting this to the developer audience. I’m not going to go through the process of how to install & configure your SharePoint Server deployment with the necessary things to support apps which is required to host & deploy SharePoint app packages (*.sppkg). “But sometimes developers are responsible for doing this in their deployments!” Yeah… I get it, but those are IT pro tasks, not developer tasks. Just because I know how to replace the oil in a car doesn’t mean I’m a mechanic ;)

Universal truths for SPFx solutions on all SharePoint Server (on-premises) deployments

Before we look the specifics of SharePoint Server 2016 with Feature Pack 2, I want to cover some universal truths that apply to all versions of SharePoint Server with respect to the SPFx.

Setup & configure SharePoint Server to host apps

The SPFx relies on the existing support SharePoint has for apps. Much of the investments Microsoft made in SharePoint Server 2013 to support the add-in model, originally called the app model, are used to deploy SPFx solutions. Most notably is the tenant app catalog.

Use the following links to ensure your SharePoint Server is configured to host apps. This is a required prerequisite for deploy SPFx solutions to your on-prem SharePoint Server deployments. This requirement applies to SharePoint Server 2016 with Feature Pack 2, SharePoint Server 2019, & SharePoint Server Subscription Edition (SE).

• Microsoft: Install and manage apps for SharePoint Server
• Microsoft: Configure an environment for apps for SharePoint Server
• Microsoft: Manage the App Catalog in SharePoint Server

Microsoft has no plans to update SPFx for SharePoint Server

In the following section I’ll explain exactly what version(s) of the SPFx are supported in each SharePoint Server version. However, one thing is universally true across all of them.

Microsoft has no plans to update the SPFx deployments on SharePoint Server.

If there’s a bug in one version that’s fixed in a later version of SPFx, Microsoft doesn’t plan to retroactively jump back and fix SPFx. For example, known bugs in SPFx v1.4.1 that were fixed in a later version won’t make it to SharePoint Server deployments.

Unfortunately, the implications are significant. This is certainly disappointing, but it’s been the case since the they added support for SPFx to SharePoint Server 2016 with Feature Pack 2. Microsoft hasn’t changed their position on this topic so I’m not optimistic the story will change in the future.

Debunked: any SPFx generator can create on-prem projects

Another thing I want to address before we look at the specific on-premises versions is a common misperception… one that I admit I’ve helped spread.

First, up until the SPFx v1.13.0 release, the Yeoman Generator for SPFx , developers could create projects for SharePoint Online, SharePoint Server 2016, SharePoint Server 2019, and SharePoint Server Subscription Edition (SE). While this is true, it doesn’t factor in the real world.

What’s the problem? Sure, the generator can create the projects, but those SharePoint Server targets use old versions of the SPFx…

… and those old SPFx versions only run on older versions of Node.js.

So while you can create the project, it might not build or run because it doesn’t support a newer version of Node.js.

Let’s demonstrate this with an example: let’s say you have the Yeoman generator SPFx v1.12.1 installed. That version only supports Node.js LTS v10, v12, & v14. For the sake of this example, let’s say you have any of those three Node.js versions installed.

So you use the SPFx v1.12.1 generator to create a project for SharePoint Server 2016 which means the project will use SPFx v1.1.0. SPFx v1.1.0 only works with Node.js LTS v6.

See the problem? You’ve stuck because you have a version of Node.js installed (v10/12/14) that SPFx v1.1.0 doesn’t support!

While you can switch Node.js versions to create different projects, that’s a pain. While there are ways to address this if you want to use a more recent version of the generator, I think there are easier ways of dealing with this.

What versions of SharePoint Framework are supported on SharePoint Server 2016 with Feature Pack 2

This is the most important question - what can SharePoint Server 2016 with Feature Pack 2 support?

SharePoint Server 2016 supports the SharePoint Framework v1.1.0 and all prior releases.

This means you can use any of the following SharePoint Framework releases in your SharePoint Server 2016 with Feature Pack 2 environment:

• SPFx v1.0.0 (including v1.0.1 & v1.0.2)
• SPFx v1.1.0 (including v1.1.1 & v1.1.3)

While all of these releases work and are supported in SharePoint Server 2016 with Feature Pack 2 deployments, the rest of this post will focus on using the most current version, SPFx v1.1.0.

Notable SPFx capabilities available in SharePoint Server 2016

The following native SPFx capabilities are supported are available in SharePoint Server 2016 deployments:

• Web parts & property panes

  Microsoft refactored the property pane objects out of the web part npm package and into it’s own npm package in SPFx v1.8.0, so if you’re looking web part code samples, make sure you check the versions as your import statements at the top of your SPFx v1.1.0 web part will look different.

• Local workbench for building & testing your web parts on your dev environment

Let’s look at a few version specifics on some npm packages and dependencies your SPFx components come with when using SPFx v1.1.0.

• Web part project templates
  • Knockout v3.4
  • React v15.4.2
• Office UI Fabric (later renamed to Fluent UI): projects include office-ui-fabric v2.6.1 npm package
• Build toolchain dependencies
  • Node.js LTS v6
  • TypeScript v2.4
  • Gulp v3
  • Webpack v2.2.1

Notable SPFx omissions from SharePoint Server 2016

Unfortunately, because the latest version of the SPFx that’s supported is v1.1.0, you’re missing out on a lot of functionality. SPFx v1.1.0 was released on June 16, 2017 and Microsoft has added a lot of capabilities to SPFx since that time.

Things you’ll miss out on include:

• Web parts:

  • Any non-SharePoint usage of web parts such as Microsoft Teams or Viva Connections
  • Single part app pages (aka: Single Page Apps, or SPAs)
  • Isolated web parts

• App customizer extensions

• Field customizer extensions

• List view command set extensions

• Search query extension

• Library components

• Adaptive Card Extensions (ACEs)

• Tenant-wide deployment (aka: tenant-scoped solution deployment)

• Inclusion of SPFx assets (JavaScript bundles, images, etc) within the SharePoint app package

  These are deployed to the app catalog when the solution is deployed.

• SPFx APIs related to Microsoft 365 & Azure, including:

  • AADHttpClient
  • MSGraphClient

• Site collection app catalog

• Build toolchain:

  • Support for multiple versions of TypeScript using the Rush Stack Compiler

SPFx development environment (including versions)

Now that you know what you can and can’t do with SPFx in SharePoint Server 2016, let’s look at what you need to set up your developer environment so you can start creating custom solutions!

We’ll break this up into the following categories:

• what you need
• what will work
• my recommendations

What you need:

Let’s start with what you need. Microsoft says you can develop SPFx solutions on any platform, including:

• Windows
• macOS
• Linux

All the tools you need to create & run SPFx solutions are Node-based. So you need to install a supported version of Node.js.

1. Node.js LTS v6: At a minimum, you need Node.js LTS v6, also known as Boron. Node.js LTS v6 includes v6.9.0 through v6.17.1.

   Once you’ve installed Node, you need to install three dependencies: Gulp, Yeoman & the Yeoman generator for the SharePoint Framework.

2. Gulp: install the Gulp CLI globally, not gulp:

   npm install gulp-cli --global
   

   Important: ☝ What? Install the Gulp CLI, not Gulp?

   Yes. This refutes a lot of the guidance that’s out there. I had it wrong for a long time as well. Gulp originally included both the CLI tools & task runner in one package. But the Gulp team realized that Gulp v3 would only work with Node.js up through Node.js v11. When Node.js v12 was released, they introduced Gulp v4.

   But that introduced a new challenge: If you installed Gulp v3 globally, then projects that used Gulp v4 wouldn’t work & vice versa. To resolve this, the Gulp team refactored out all the CLI based stuff you need in the global context into it’s own package: gulp-cli . Gulp CLI can coexist with Gulp v3 and Gulp v4.

   Therefore, the guidance from the Gulp team is to only install gulp-cli globally and use gulp within projects.

3. Yeoman generator for the SharePoint Framework: you need the version of the SPFx generator that can create v1.1.0 projects:

   npm install @microsoft/[email protected] --global
   

4. Yeoman: To run the generator, you need Yeoman. Specifically, you need Yeoman v2.0.0. If you use any other version to run the generator (including minor versions), you’ll run into issues creating projects with the SPFx generator v1.1.0.

   npm install [email protected] --global
   

5. Fixup Yeoman: Unfortunately there’s an issue you need to resolve after installing Yeoman. Yeoman has a dependency, yeoman-environment, it automatically installs. Unfortunately, a later version of this dependency doesn’t work with Node.js LTS v6. For example, if you run Yeoman without this fix, you’ll get this:

   /Users/ac/.nvm/versions/node/v6.17.1/lib/node_modules/yo/node_modules/yeoman-environment/lib/environment.js:154
     options = {singleResult: !options.multiple, ...options};
                                                     ^^^
   
   SyntaxError: Unexpected token ...
       at createScript (vm.js:56:10)
       at Object.runInThisContext (vm.js:97:10)
       at Module._compile (module.js:549:28)
       at Object.Module._extensions..js (module.js:586:10)
       at Module.load (module.js:494:32)
       at tryModuleLoad (module.js:453:12)
       at Function.Module._load (module.js:445:3)
       at Module.require (module.js:504:17)
       at require (internal/module.js:20:19)
       at Object.<anonymous> (/Users/ac/.nvm/versions/node/v6.17.1/lib/node_modules/yo/lib/router.js:9:54)
   

   What’s going on? The spread operator (...), which is the cause of the error, is not supported in Node.js v6. The package yeoman-environment v2.8.0 release included the change that introduced the spread operator to one file in the package. That’s what’s throwing that error. See for your self: this link takes you to the list of changes from v2.7.0 to v2.8.0 . Locate the ./lib/environment.js file and jump to lines 166, 550, & 551.

   To fix this, you need to do a bit of surgery on your Yeoman installation & force it to use yeoman-environment v2.7.0, not a later version:

   1. Install yeoman-environment v2.7.0 globally:

      npm install [email protected] —-global
      

   2. Find where the Yeoman installed version is located. You can use either the which command on macOS or where on Windows to get this:

      # macOS
      ➜ which yo
      /Users/ac/.nvm/versions/node/v6.17.1/bin/yo
      
      # Windows
      c:\users\ac>where /R c:\ yo
      c:\users\ac\AppData\Roaming\nvm\v6.17.1\yo
      

      Warning: Don't forget to fix Yeoman if you use Node v6 LTS

      ☝ The paths listed in this step are what I have on my laptop (macOS) and Windows virtual machine. Your path, specifically the first part, will look different. My paths show my user profile is ac and I’m using a Node Version Manager (NVM) to manage multiple versions of Node on the same environment

      You might see a couple results, so you have to figure out the one you want:

      • macOS: The path returned is where the yo executable is located. In this case, that’s the bin folder. Parallel to the bin folder, you’ll find the lib folder that contains node_modules. That’s where all the npm packages are installed globally by npm. So, in the example above, that’s:

        /users/ac/.nvm/versions/node/v6.17.1/lib/node_modules/yo
        

      • Windows: The path returned above is where the yo folder is found.

      When you open the Yeoman install folder, you see the package.json file for Yeoman as well as the node_modules folder that contains Yeoman’s dependencies.

   3. Delete the folder yeoman-environment from the installed dependencies for Yeoman.

   4. At this point you should be good to go. When you run yeoman, it should use the yeoman-environment v2.7.0 you installed globally. If for some reason it doesn’t, try moving the yeoman-environment v2.7.0 you installed globally into the same place where you deleted the folder in the last step.

At this point, you can create new projects for SharePoint Server 2016 by running the Yeoman generator for the SharePoint Framework:

yo @microsoft/sharepoint

That covers the minimal requirements for creating SPFx v1.1.0 projects for SharePoint Server 2016. But you can use newer versions of some of these tools with the same effect.

What will work

Now let’s look at what you can use to set up your development environment. Unless otherwise specified, everything I said above applies.

• Node.js: SPFx v1.1.0 & the build toolchain it uses supports only Node.js LTS v6.
• Gulp: nothing special to say here… follow the exact same guidance for above.
• Yeoman generator for the SharePoint Framework: now things get a bit complicated. Technically, the SPFx generator v1.12.1 can create SPFx projects for SharePoint Server 2016. Make sure you read my recommendation below as to why this isn’t the best idea.
• Yeoman: The version of the SPFx generator you installed will drive the version of Yeoman you need to install. For the SPFx generator up to version up to & including v1.8.0, use Yeoman v2.0.0. However, Yeoman v3 can be used with the SPFx generator v1.8.1 - v1.12.1.

My dev environment recommendation for SharePoint Server 2016 with Feature Pack 2

Let me be absolutely clear: what follows is my recommendation.

My attitude is that you want to use the most current version of every tool that will get the job done. So, I want to use the most recent version of Node.js, the SPFx generator and Yeoman possible to create SPFx projects for SharePoint Server 2016 with Feature Pack 2.

If we take a step back, remember, the most recent version of SPFx that’s supported on SharePoint Server 2016 is v1.1.0. So, that’s our target.

But the version of the generator doesn’t have to match the version of the project it creates. I covered this in my post Understand difference SharePoint Framework generator related packages . I’d rather use the most current version of the generator possible because it might include project templates, toolchain optimizations, or project creation experiences that are better than what an older generator would have.

In the last section, I said we could use the Yeoman generator for the SharePoint Framework v1.12.1 to create SharePoint Server 2016 projects.

So use that, right? Nope… not so fast…

The youngest version of Node.js you can run the v1.12.1 SPFx generator with is Node.js v10.

So… we could install Node.js v10, the SPFx v1.12.1 generator, and use them to create SPFx v1.1.0 projects for SharePoint Server 2016. But to build, run, debug, and package it up you’ll have to use a different environment that has Node.js LTS v6 installed. That’s a pain… we’re working harder, not smarter.

Instead, I think it makes sense to use the most current generator that’s supported on the most current version of Node.js supported for SPFx v1.1.0 projects. That’s the Yeoman generator SPFx v1.6.0… it’s the last version of the generator that supports Node.js LTS v6.

So… here’s my development environment sweet spot for creating SPFx 1.1.0 projects for SharePoint Server 2016 with Feature Pack 2:

• Node.js LTS v6 (specifically, Node.js v6.17.1 )
• npm v4
• Gulp-CLI v2.3.0
• Yeoman v2.0.0 with the Yeoman-environment v2.7.0 fix I mentioned above
• Yeoman generator for the SharePoint Framework v1.6.0

npm install npm@4 --global
npm install [email protected] [email protected] @microsoft/[email protected] --global

# +++++ fix the yeoman-environment version problem +++++
# 1. install yeoman-environment v2.7.0
npm install [email protected] --global
# 2. delete existing yeoman-environment installed by yo
# delete ./PATH_TO_YOUR_GLOBALLY_INSTALLED_PACKAGES/yo/node_modules/yeoman-environment

This way, you’re using the most recent versions of Node.js, Gulp-cli, Yeoman & the generator SPFx to create new SPFx v1.1.0 projects for SharePoint Server 2016 & be ready to run them straight away without having to jump through hoops after creating the project.

I’m also upgrading the version of npm (to v4) from what LTS v6 ships with (v3) as there’s a nice update.

Finally, I fixed the yeoman-environment installation. Now you’re good to go to create SharePoint Framework projects for SharePoint Server 2016 with Feature Pack 2!