Definitive guide for developers: SharePoint Framework for SharePoint Server SE

In this post, my goal is to provide the definitive guide to the SharePoint Framework for SharePoint Server Subscription Edition (SE) on-premises deployments.

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

Before we look the specifics of SharePoint Server SE, 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 SE 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 SE

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

The initial release of SharePoint Server SE 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 SE 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 SE deployments, the rest of this post will focus on using the most current version, SPFx v1.4.1.

Since the initial release of SharePoint Server Subscription Edition, Microsoft has released to updates that updated SPFx version as follows:

• SharePoint Server SE + 23H2 feature update updated the SharePoint Framework to v1.5.1. Learn more about this release here: SharePoint Framework Updated in SharePoint Server Subscription Edition.
• SharePoint Server SE + 23H2 feature update downgraded the SharePoint Framework to v1.5.0. Learn more about this release here: SPFx Devs: Beware of the SharePoint SE 23H2 Feature Update.
• SharePoint Server SE + 24H1 feature update left the SharePoint Framework version unchanged with v1.5.0. Learn more about this release here: SharePoint Framework and SharePoint Server SE 24H1.

Notable SPFx capabilities available in SharePoint Server SE

The following native SPFx capabilities are supported are available in SharePoint Server SE 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 SE also includes the Application Lifecycle Management (ALM) REST APIs that enable programmatic deployment of SPFx solutions.

Notable SPFx omissions from SharePoint Server SE

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)

  • (Domain) Isolated web parts

    Domain isolated web parts will be retired in April 2026. Learn more: SharePoint Framework Domain Isolated Webpart Retirement.

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

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

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

If we take a step back, remember, the most recent version of SPFx that’s supported on SharePoint Server SE 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 SE 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 SE. 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 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.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 SE:

• 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 SE & 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 SE!