SharePoint Framework toolchain

The SharePoint Framework toolchain is the set of build tools, framework packages, and other items that manage building and deploying your client-side projects.

The toolchain:

  • Helps you build client-side components such as web parts.
  • Helps you test client-side components in your local development environment by using tools such as the SharePoint Workbench.
  • Enables you to package and deploy to SharePoint.
  • Provides you with a set of build commands that help you complete key build tasks such as code compilation, packaging the client-side project into a SharePoint app package, and more.

Important

The local workbench does not support Internet Explorer 11.

Use npm packages

Before diving into the various toolchain components, it’s important to understand how the SharePoint Framework uses npm to manage different modules in the project. npm is one of the preferred open-source package managers for JavaScript client-side development.

A typical npm package consists of one or more reusable JavaScript code files, called modules, along with a list of dependency packages. When you install the package, npm also installs those dependencies.

The official npm registry consists of hundreds of packages that you can download to build your application. You can also publish your own packages to npm and share them with other developers. The SharePoint Framework uses some of the npm packages in the toolchain and also publishes its own packages to the npm registry.

SharePoint Framework packages

The SharePoint Framework consists of several npm packages that work together to help you build client-side experiences in SharePoint.

The following npm packages are in the SharePoint Framework:

  • @microsoft/generator-sharepoint. A Yeoman plug-in for use with the SharePoint Framework. Using this generator, developers can quickly set up a new client-side web part project with sensible defaults and best practices.
  • @microsoft/sp-client-base. Defines the core libraries for client-side applications built using the SharePoint Framework.
  • @microsoft/sp-webpart-workbench. The SharePoint Workbench is a standalone environment for testing and debugging client-side web parts.
  • @microsoft/sp-module-loader. A module loader that manages versioning and loading of client-side components, web parts, and other assets. It also provides basic diagnostic services. It is built on familiar standards such as SystemJS and webpack, and is the first part of the SharePoint Framework to load on a page.
  • @microsoft/sp-module-interfaces. Defines several module interfaces that are shared by the SharePoint Framework module loader and also the build system.
  • @microsoft/sp-lodash-subset. Provides a custom bundle of lodash for use with the SharePoint Framework's module loader. To improve runtime performance, it only includes a subset of the most essential lodash functions.
  • @microsoft/sp-tslint-rules. Defines custom tslint rules for usage with SharePoint client-side projects.
  • @microsoft/office-ui-fabric-react-bundle. Provides a custom bundle of office-ui-fabric-react that is optimized for use with the SharePoint Framework's module loader.

Common build tool packages

Along with the SharePoint Framework packages, a common set of build tools is also used to perform build tasks such as compiling TypeScript code to JavaScript and converting SCSS to CSS.

The following common npm build tools packages are in the SharePoint Framework:

Scaffold a new client-side project

The SharePoint generator scaffolds a client-side project with a web part. The generator also downloads and configures the required toolchain components for the specified client-side project.

Install npm packages

The generator installs required npm packages locally in the project folder. npm allows you to install a package either locally to your project or globally. There are benefits to both, but the general guidance is to install the npm packages locally if your code depends on those package modules. In the case of a web part project, your web part code depends on the various SharePoint and common build packages, and thus requires those packages to be installed locally.

As the packages are installed locally, npm also installs the dependencies associated with each package. You can find the packages installed under the node_modules folder in your project folder. This folder contains the packages along with all their dependencies. It is ideal that this folder contains dozens to hundreds of folders, because npm packages are always broken down to smaller modules, which result in dozens to hundreds of packages being installed. The key SharePoint Framework packages are located under the node_modules@microsoft folder. The @microsoft is an npm scope that collectively represents packages published by Microsoft.

Every time you create a new project using the generator, the generator installs the SharePoint Framework packages along with its dependencies for that specific project locally. In this way, npm makes it easier to manage your web part projects without affecting other projects in the local dev environment.

Specify dependencies with package.json

The package.json file in the client-side project specifies the list of dependencies the project depends on. The list defines what dependencies to install. As described earlier, each dependency could contain several more. npm allows you to define both runtime and build dependencies for your package by using the dependencies and devDependencies properties. The devDependencies property is used when you want to use that module in your code as in the case of building web parts.

The following is the package.json of the helloworld-webpart.

{
  "name": "helloword-webpart",
  "version": "0.0.1",
  "private": true,
  "engines": {
    "node": ">=0.10.0"
  },
  "dependencies": {
    "@microsoft/sp-client-base": "~1.0.0",
    "@microsoft/sp-core-library": "~1.0.0",
    "@microsoft/sp-webpart-base": "~1.0.0",
    "@types/webpack-env": ">=1.12.1 <1.14.0"
  },
  "devDependencies": {
    "@microsoft/sp-build-web": "~1.0.0",
    "@microsoft/sp-module-interfaces": "~1.0.0",
    "@microsoft/sp-webpart-workbench": "~1.0.0",
    "gulp": "~3.9.1",
    "@types/chai": ">=3.4.34 <3.6.0",
    "@types/mocha": ">=2.2.33 <2.6.0"
  },
  "scripts": {
    "build": "gulp bundle",
    "clean": "gulp clean",
    "test": "gulp test"
  }
}

While there is lot of packages installed for the project, they are required only for building the web part in the dev environment. With the help of these packages, you can depend on the modules, and you can build, compile, bundle, and package your web part for deployment. The final minified bundled version of the web part that you deploy to a CDN server or SharePoint does not include any of these packages. That said, you can also configure to include certain modules depending on your requirements. For more information, see Add an external library to a web part.

Work with source control systems

As project dependencies increase, the number of packages to install also increases. You don’t want to check in the node_modules folder, which contains all the dependencies, to your source control system. You should exclude the node_modules from the list of files to ignore during check-ins.

If you are using git as your source control system, the Yeoman scaffolded web part project includes a .gitignore file that excludes the node_modules folder, among other things.

When you check out, or clone, the web part project from your source control system the first time, run the command to initialize and install all the project dependencies locally:

npm install

After you run the command, npm scans the package.json file and installs the required dependencies.

Update developer information

Starting from version 1.11, the solution manifest defined in the package-solution.json file has been extended with the developer section that allows you to store additional information about your organization. Information from this section is validated when you publish your solution to the marketplace. Even if you're building a solution for internal use, it's recommended that you fill in the different properties in your solution manifest. If you specify this information, in the future you might get access to additional insights into the usage of your application.

Important

If you choose to expose your web parts in Microsoft Teams, users will see the information from the developer section when installing your app in Teams.

Important

Developer section is required to contain valid information for any SharePoint Framework solution which will be available from the Office store or from AppSource.

Following properties are available as a part of the developer section:

Attribute Description Mandatory
name Name of the organization that built the application Yes
websiteUrl URL of a website with additional information about the application Yes
mpnId Microsoft Partner Network ID (more details on MS Partner Network) No (but highly recommended)
privacyUrl Privacy statement URL Yes
termsOfUseUrl Terms of use URL Yes

Build tasks

The SharePoint Framework uses gulp as its task runner to handle processes like the following:

  • Bundle and minify JavaScript and CSS files.
  • Run tools to call the bundling and minification tasks before each build.
  • Compile LESS or Sass files to CSS.
  • Compile TypeScript files to JavaScript.

The toolchain consists of the following gulp tasks defined in the @microsoft/sp-build-core-tasks package:

  • build - Builds the client-side solution project.
  • bundle - Bundles the client-side solution project entry point and all its dependencies into a single JavaScript file.
  • serve - Serves the client-side solution project and assets from the local machine.
  • clean - Cleans the client-side solution project's build artifacts from the previous build and from the build target directories (lib and dist).
  • test - Runs unit tests, if available, for the client-side solution project.
  • package-solution - Packages the client-side solution into a SharePoint package.
  • deploy-azure-storage - Deploys client-side solution project assets to Azure Storage.

To initiate different tasks, append the task name with the gulp command. For example, to compile and then preview your web part in the SharePoint Workbench, run the following command:

gulp serve

Note

You cannot execute multiple tasks at the same time.

The serve task runs the different tasks and finally launches SharePoint Workbench.

gulp serve task

Build targets

In the previous screenshot, you can see that the task indicates your build target as follows:

Build target: DEBUG

If no parameter is specified, the commands target the BUILD mode. If the ship parameter is specified, the commands target the SHIP mode.

Usually, when your web part project is ready to ship or deploy in a production server, you target SHIP. For other scenarios, such as testing and debugging, you would target BUILD. The SHIP target also ensures that the minified version of the web part bundle is built.

To target SHIP mode, append the task with --ship:

gulp --ship

In DEBUG mode, the build tasks copy all of the web part assets, including the web part bundle, into the dist folder.

In SHIP mode, the build tasks copy all of the web part assets, including the web part bundle, into the temp\deploy folder.

See also