Definitive guide for developers: SharePoint Framework for SharePoint Server 2019

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 2019 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 2019, 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 2019 which means the project will use SPFx v1.4.1. SPFx v1.4.1 only works with Node.js LTS v6 & v8.

See the problem? You’ve stuck because you have a version of Node.js installed (v10/12/14) that SPFx v1.4.1 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 2019

This is the most important question - what can SharePoint Server 2019 support?

SharePoint Server 2019 supports the SharePoint Framework v1.4.1 and all prior releases.

This means you can use any of the following SharePoint Framework releases in your SharePoint Server 2019 environment:

• SPFx v1.0.0 (including v1.0.1 & v1.0.2)
• SPFx v1.1.0 (including v1.1.1 & v1.1.3)
• SPFx v1.2.0
• SPFx v1.3.0 (including v1.3.1, v1.3.2, & v1.3.4)
• SPFx v1.4.0
• SPFx v1.4.1

While all of these releases work and are supported in SharePoint Server 2019 deployments, the rest of this post will focus on using the most current version, SPFx v1.4.1.

Notable SPFx capabilities available in SharePoint Server 2019

The following native SPFx capabilities are supported are available in SharePoint Server 2019 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.4.1 web part will look different.

• App customizer extensions

• Field customizer extensions

• List view command set extensions

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

• 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.

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

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

• Web part project templates

  • Knockout v3.4
  • React v15.6.2

• Office UI Fabric (later renamed to Fluent UI): projects include office-ui-fabric-core v9.1.0 npm package

  Included as a dependency of @microsoft/sp-office-ui-fabric-core included in all projects.*

• Build toolchain dependencies

  • Node.js LTS v6 or LTS v8
  • TypeScript v2.4
  • Gulp v3
  • Webpack v3.6

In addition to this list, SharePoint Server 2019 also includes the Application Lifecycle Management (ALM) REST APIs that enable programmatic deployment of SPFx solutions.

Notable SPFx omissions from SharePoint Server 2019

Unfortunately, because the latest version of the SPFx that’s supported is v1.4.1, you’re missing out on quite a bit of functionality. SPFx v1.4.1 was released on February 15, 2018 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
• Search query extension
• Library components
• Adaptive Card Extensions (ACEs)
• 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 2019, 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

Now let’s look at the tools you need.

1. All the tools you need to create & run SPFx solutions are Node-based. So you need to install a supported version of Node.js. 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.

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

   If you elect to Node.js LTS v6, you’ll need to fixup the yeoman install. For more information about this, refer to the instructions in for my Definitive guide: SharePoint Framework for SharePoint Server 2016 .

   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.4.1 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.4.1.

   npm install [email protected] --global
   

Once you have Node.js installed, you can install everything else in one line like this:

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

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

yo @microsoft/sharepoint

That covers the minimal requirements for creating SPFx v1.4.1 projects for SharePoint Server 2019. 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.4.1 & the build toolchain it uses support up to Node.js LTS v8, also known as Carbon, which includes v8.9.0 - v8.17.0.
• 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 2019. 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. However, Yeoman v3 can be used with the SPFx generator v1.8.1 - v1.12.1.

My dev environment recommendation for SharePoint Server 2019

To be very clear, what follows is my recommendation. It may not match exactly what Microsoft tells you.

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 2019.

Remember, the most recent version of SPFx that’s supported on SharePoint Server 2019 is v1.4.1. 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 2019 projects.

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

The oldest 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.4.1 projects for SharePoint Server 2019. But to build, run, debug, and package it up you’ll have to use a different environment that has Node.js LTS v6 or LTS v8 installed. That’s a pain… we’re supposed to work smarter, not harder.

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.4.1 projects. That’s the Yeoman generator SPFx v1.10.0… it’s the last version of the generator that supports Node.js LTS v8.

Furthermore, the Yeoman generator for SPFx v1.10.0 works with Yeoman v3.*.

So… here’s my development environment sweet spot for creating SPFx 1.4.1 projects for SharePoint Server 2019:

• Node.js LTS v8 (specifically, Node.js v8.17.0 )
• Gulp-CLI v2.3.0
• Yeoman generator for the SharePoint Framework v1.10.0
• Yeoman v3.1.1

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

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

Now you’re good to go to create SharePoint Framework projects for SharePoint Server 2019!