Definitive guide for developers: SharePoint Framework for SharePoint Server 2016

11 min read

These days, all of Microsoft's updates about the SPFx, or community content have one thing in common: they ignore SharePoint Server 2016. 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 2016 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 2016 with Feature Pack 2, let me know!

Help me keep this article the definitive guide & reference for developing SPFx solutions on SharePoint Server 2016 with Feature Pack 2!

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.

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:

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:

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!

☝ 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

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:

    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.1.0 projects:

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

    1npm install yo@2.0.0 --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:

     1/Users/ac/.nvm/versions/node/v6.17.1/lib/node_modules/yo/node_modules/yeoman-environment/lib/environment.js:154
 2  options = {singleResult: !options.multiple, ...options};
 3                                                  ^^^
 4
 5SyntaxError: Unexpected token ...
 6    at createScript (vm.js:56:10)
 7    at Object.runInThisContext (vm.js:97:10)
 8    at Module._compile (module.js:549:28)
 9    at Object.Module._extensions..js (module.js:586:10)
10    at Module.load (module.js:494:32)
11    at tryModuleLoad (module.js:453:12)
12    at Function.Module._load (module.js:445:3)
13    at Module.require (module.js:504:17)
14    at require (internal/module.js:20:19)
15    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:

      1npm install yeoman-environment@2.7.0 —-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:

      1# macOS
2➜ which yo
3/Users/ac/.nvm/versions/node/v6.17.1/bin/yo
4
5# Windows
6c:\users\ac>where /R c:\ yo
7c:\users\ac\AppData\Roaming\nvm\v6.17.1\yo
      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:

        1/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:

1yo @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
1npm install npm@4 --global
2npm install gulp-cli@2.3.0 yo@2.0.0 @microsoft/generator-sharepoint@1.6.0 --global
3
4# +++++ fix the yeoman-environment version problem +++++
5# 1. install yeoman-environment v2.7.0
6npm install yeoman-environment@2.7.0 --global
7# 2. delete existing yeoman-environment installed by yo
8# 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!

Share this article

Feedback & comments