Definitive guide for developers: SharePoint Framework for SharePoint Server 2019

9 min read

These days, all of Microsoft's updates about the SPFx, or community content have one thing in common: they ignore SharePoint Server 2019. Not this post!

Development Microsoft 365 SharePoint SharePoint Framework

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

☝ See something missing? Still have an unanswered question?

If you think something is missing from this article, or if you have a question about developing and running SPFx solutions on SharePoint Server 2019, let me know!

Help me keep this article the definitive guide & reference for developing SPFx solutions on SharePoint Server 2019!

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.

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:

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:

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!

☝ I’ve included everything you see here in a screencast below where I demonstrate how to install everything.

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.

    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:

    1npm install gulp-cli --global
    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:

    1npm install @microsoft/generator-sharepoint@1.4.1 --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.

    1npm install yo@2.0.0 --global

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

1npm install gulp-cli@2.3.0 yo@2.0.0 @microsoft/generator-sharepoint@1.4.1 --global

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

1yo @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
1npm install gulp-cli@2.3.0 yo@3.1.1 @microsoft/generator-sharepoint@1.10.0 --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!

Share this article

Feedback & comments