SharePoint Framework development with SharePoint Server 2019 and Subscription Edition

SharePoint Server 2019 and Subscription Edition support SharePoint Framework client-side web parts in classic and modern pages, and extensions in modern pages.

Important

SharePoint Server Subscription Edition (SE) has all the same dependencies and requirements for the SharePoint Framework (SPFx) as SharePoint Server 2019.

Which version of the SharePoint Framework to use

Because SharePoint Online and SharePoint Server 2019 have different release cycles for new capabilities, they also have different capabilities when it comes to the SharePoint Framework. SharePoint Online always uses the latest version of the SharePoint Framework, but SharePoint Server 2019 only supports the version that matches the server-side dependencies of the deployed packages.

Important

SharePoint Server 2019 supports SharePoint Framework client-side web parts hosted on classic or modern SharePoint pages built by using the SharePoint Framework v1.4.1.

SharePoint Server 2019 also supports SharePoint Framework extensions hosted on modern SharePoint pages built using SharePoint Framework v1.4.1. This means that when you're targeting the SharePoint Server 2019 platform, you need to use the SharePoint Framework v1.4.1 because of the server-side version dependencies.

Starting from v1.3, the SharePoint Framework Yeoman generator supports scaffolding solutions that use both the latest version of the SharePoint Framework meant for use with SharePoint Online, and solutions that can be used with SharePoint on-premises based on the v1.1.0 or v1.4.1 of the SharePoint Framework. You don't need to install a separate version of the SharePoint Framework Yeoman generator to scaffold solutions meant for use with SharePoint on-premises.

Development environment considerations

When you're developing SharePoint Framework client-side web parts, you need Internet connectivity to access npm packages. This is required when solutions are being scaffolded by using the SharePoint Framework Yeoman templates.

If Internet access isn't available for the development machines, you can set up a local on-premises registry for the required npm packages. However, this requires more software and a significant amount of work to set up and maintain local package versions with packages in the actual npm gallery.

The Team-based development on the SharePoint Framework guidance document includes different options for development environment setup including when you might need to support multiple SharePoint Framework versions.

Node.js, gulp-cli, and Yeoman versions

The dependencies for SPFx v1.4.1 frameworks, tools, and the associated versions don't match the same dependency matrix for the latest versions of SharePoint Framework. In these cases, you may need to install specific versions of the tools. Because SPFx v1.4.1 is supported on Node.js v6 and Node.js v8 by default, you need to ensure you have a supported version of Node.js installed as well as an older version of Gulp CLI and Yeoman.

Note

• The Gulp team introduced a separate package, gulp-cli, that should be installed globally. It can be used by projects that use either Gulp v3 & Gulp v4.
• Learn more about the gulp-cli here: gulpjs/gulp/#2324.

Microsoft recommends using the most recent version of the Yeoman generator for the SharePoint Framework @microsoft/generator-sharepoint that supports creating on-premises projects: SPFx v1.10.0.

Important

The Yeoman generator for the SharePoint Framework, starting with v1.13.0, only supports projects for SharePoint Online. Learn more about this change in the SharePoint Framework v1.13 release notes. However, SPFx 1.4.1 is supported on Node.js v6 and Node.js v8 by default. Therefore, you need to get the latest version of the Yeoman generator for the SharePoint Framework that works on the same version of Node.js (v6 or v8) that SPFx v1.4.1 is supported on. Solution structure is created then with the v1.4.1 version packages as long as you select the environment target properly in the Yeoman generator flow.

Prepare the environment for SharePoint Framework development

1. Install Node.js v8.17.0.

   SPFx v1.4.1 is also supported on Node.js v12, v14 and v16 (v12.18.1, v14.17.1 and v16.15.0 to be specific), though there are incompatible issues (gulp v3 is incompatible with Node v12+, and node-sass v4 requires Node.js v14 or below). The workaround to resolve them is to specify the version of the graceful-fs component as v4+, and to replace node-sass with sass. You can manually modify package-lock.json or npm-shrinkwrap.json and then re-run npm install. Or you can create a new *.js file located in the root folder of your project, copy the following code into that file, run node your_new_js_file and re-run npm install.

   const fs = require('fs');
   const lockedVersionFile = 'package-lock.json';
   // const lockedVersionFile = 'npm-shrinkwrap.json';
   const lockedVersionJson = JSON.parse(fs.readFileSync(lockedVersionFile));
   if (lockedVersionJson.packages) {
       const vinylFSJson = lockedVersionJson.packages["node_modules/vinyl-fs"];
       if (vinylFSJson && vinylFSJson["dependencies"] && vinylFSJson["dependencies"]["graceful-fs"]) {
           vinylFSJson["dependencies"]["graceful-fs"] = "npm:graceful-fs@4.2.11";
       }
   
       const gulpSassJson = lockedVersionJson.packages["node_modules/gulp-sass"];
       console.log(gulpSassJson);
       if (gulpSassJson && gulpSassJson["dependencies"] && gulpSassJson["dependencies"]["node-sass"]) {
           gulpSassJson["dependencies"]["node-sass"] = "npm:sass@1.32.0";
       }
   }
   fs.writeFileSync(lockedVersionFile, JSON.stringify(lockedVersionJson, undefined, 2));
   

2. Install global dependencies

   npm install gulp-cli@2.3.0 --global
   npm install yo@2.0.6 --global
   npm install @microsoft/generator-sharepoint@1.10.0 --global
   

For more information, see  SharePoint Framework development tools and libraries compatibility.

Build and deploy your first web part with SharePoint Framework

To create a new web part with SharePoint Framework, see Build your first SharePoint client-side web part.

To deploy your web part to SharePoint on-premises, unlike deploying to SharePoint Online, some dependent service applications and specific configurations on the SharePoint Server are required. You can contact the SharePoint Server administrator if you don't have appropriate permission to check or configure.

1. Ensure App Management Service and other dependent service applications are configured, see Configure an environment for apps for SharePoint Server.
2. Create and configure App Catalog site, see Manage the App Catalog in SharePoint Server.
3. Package and upload your web part, install it on your site, and add it to modern page, see Deploy your client-side web part to a SharePoint page.

Determine which version was used for a solution

If you have existing SharePoint Framework solutions and you'd like to confirm which version of the SharePoint Framework was used for them, you'll need to check the following locations:

• .yo-rc.json: File in the solution's root folder that stores the SharePoint Framework Yeoman template version used when the solution was created.
• package.json: File in the solution's root folder that contains references to package versions used in the solution.
• npm-shrinkwrap.json: File in the solution's root folder that contains information about the exact versions used (if you used the npm shrinkwrap command to lock down the exact versions of the solution).
• package.json: File in the node_modules/@microsoft/sp-webpart-base folder that contains a version attribute matching the used SharePoint Framework version, if you have installed packages to your solution.

Troubleshooting

Impact of Node.js v6, Node.js v8, HTTP1, & HTTP2

Around the time of the v1.1 release, Node.js was transitioning from Node.js v6.x to v8.x. In this update, Node.js introduced a change where the default HTTP protocol switched from HTTP1 to HTTP2. SPFx v1.1 was written for HTTP1, not HTTP2, so this change affected the local web server for SPFx v1.1 projects.

In Node.js v8.x, you can force HTTP1 by setting the following environment variable to instruct Node.js to use HTTP1 instead of the default HTTP2: NODE_NO_HTTP2=1. This environment variable only exists in Node.js v8.x. That's why if you're building SPFx solutions for SharePoint Server 2016, you should use Node.js v8.x.

This issue doesn't impact later versions of SPFx because they've been updated to support HTTPs.

For more information, see issue #1002.

See also

• SharePoint Framework Overview.
• SharePoint Server 2019 development platform.
• Definitive guide for developers: SharePoint Framework for SharePoint Server 2019.
• Definitive guide for developers: SharePoint Framework for SharePoint Server SE.