Edit

Share via

Set up your SharePoint Framework Gulp-Based development environment

Note

This article focuses on the legacy gulp-based toolchain that applies to all versions of the SharePoint Framework from v1.0 through v1.21.1. This includes all on-premises versions of SharePoint Server where the SharePoint Framework is supported.

If you are working with the SharePoint Framework v1.22+, you should refer to the modern Heft-based toolchain set up guide: Set up your SharePoint Framework development environment.

Important

The SharePoint Framework (SPFx) used a gulp-based toolchain from SPFx v1.0 - v1.21.1. SPFx v1.22 transitioned to a new Heft-based toolchain, replacing the previous dependency on gulp. As part of this change, build toolchain configurations and customizations were also changed.

Ensure you are following the correct guidance and documentation for toolchain used by version of SPFx you're. Learn more about the different toolchains:

You can use any text editor to build SharePoint Framework (SPFx) solutions. You can use a macOS, Windows, or Linux environment as well.

Note

Before following the steps in this article, be sure to Set up your Microsoft 365 tenant.

You can also follow these steps by watching this video on the Microsoft 365 Platform Community (PnP) YouTube Channel:

Important

The following steps assume you're building solutions for SharePoint Online using the SPFx v1.21.1.

If you're building solutions for SharePoint Server 2016, or SharePoint Server 2019, or SharePoint Server Subscription Edition, refer to the additional documentation referenced in the See also section below.

Install Node.js

Install the most recent LTS version of Node.js v22.

This version is the recommended version of Node.js to use with the SPFx v1.21.1. If you are using a different version of SPFx, verify you install a version of Node.js that's supported by that version of SPFx.

Important

Node.js is frequently updated and available on multiple platforms including macOS, Windows, and Linux. Because the exact download links change frequently, they aren't linked to from this page. Instead, use the details below to determine which installer to download for your platform.

Be aware that Node.js maintains two different releases at all times: LTS & Current version. The SPFx is only supported on LTS versions. For more information about Node.js's Long Term Support (LTS) releases, see: Node.js > About.

Tip

The Node.js website always recommends the latest installer for both the LTS & Current releases. To download specific versions of Node.js versions, use the Node.js > Downloads page and select the version you want to install.

  • Windows users can use the *.msi installers for x86 or x64 depending on your Windows installation. There are usually only two *.msi files with names similar to node-v{version-number}-x[86|64].msi.
  • macOS users can use the *.pkg installer that's usually is named node-v{version-number}.pkg.

You can check if you already have Node.js installed, including the installed version, by running the following command:

node --version

SPFx v1.21.* is supported on Node.js v22 LTS (aka Jod).

Caution

If you're building SPFx components for SharePoint on-premises deployments, refer to the additional pages listed in the See also section for more information.

Install a code editor

You can use any code editor or IDE that supports client-side development to build your web part, such as:

The steps and examples in this documentation use Visual Studio Code, but you can use any editor of your choice.

Install development toolchain prerequisites

The SPFx development and build toolchain leverages various popular open-source tools. While most dependencies are included in each project, you need to install a few dependencies globally on your workstation.

Tip

You can install all three of the following tools in a single line:

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

Install Gulp

Gulp is a JavaScript-based task runner used to automate repetitive tasks. The SPFx build toolchain uses Gulp tasks to build projects, create JavaScript bundles, and the resulting packages used to deploy solutions.

Enter the following command to install the Gulp CLI:

npm install gulp-cli --global

Install Yeoman

Yeoman helps you kick-start new projects, and prescribes best practices and tools to help you stay productive. SharePoint client-side development tools include a Yeoman generator for creating new web parts. The generator provides common build tools, common boilerplate code, and a common playground website to host web parts for testing.

Enter the following command to install Yeoman:

npm install yo --global

Important

SPFx v1.18.2 release included the support for Yeoman v5. If you use a previous SPFx version, you might need to install an older version. Yeoman v4.x is required by the SPFx v1.13 until v1.18.1. You can install the latest Yeoman v4 version with the following command:

npm install yo@4.3.1 --global

Install Yeoman SharePoint generator

The Yeoman SharePoint web part generator helps you quickly create a SharePoint client-side solution project with the right toolchain and project structure.

To install the SPFx Yeoman generator globally, enter the following command:

npm install @microsoft/generator-sharepoint --global

For more information about the Yeoman SharePoint generator, see Yeoman generator for the SPFx.

Install a modern web browser

You should be using a modern web browser like Microsoft Edge, Google Chrome, or Firefox as the development browser.

Trusting the self-signed developer certificate

The SPFx's local web server, used when testing your custom solutions from your development environment, uses HTTPS by default. This is implemented using a development self-signed SSL certificate. Self-signed SSL certificates are not trusted by your developer environment. You must first configure your development environment to trust the certificate.

A utility task is included in every SPFx project in the form of a gulp task. You can elect to do this now, or wait until you create your first project as covered in the Build your first SharePoint client-side web part (Hello World part 1) tutorial.

Once a project has been created with the Yeoman generator for the SPFx, execute the following command from within the root folder of the project.

gulp trust-dev-cert

Note

This assumes you have installed all dependencies with npm install after creating the project. This step will install all gulp tasks as part of a project.

Set the SPFX_SERVE_TENANT_DOMAIN environment variable (optional)

Starting with SPFx v1.17, Microsoft replaced the hosted workbench URL launched when you execute gulp serve with a dynamic value. This is defined in the project's ./config/serve.json file in the initialPage property:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/spfx-serve.schema.json",
  "port": 4321,
  "https": true,
  "initialPage": "https://{tenantDomain}/_layouts/workbench.aspx"
}

The SPFx build toolchain will replace this value on the fly with a value defined in an environment variable on your local workstation.

Developers can use the SPFX_SERVE_TENANT_DOMAIN OS environment variable to specify the tenant domain (or site URL) for serve configurations across different SPFx solutions. If a URL in the serve configuration (for example, pageUrl for Field Customizer) contains the {tenantDomain} placeholder, it will be automatically replaced with the variable's value.

For more information on how to set the environment variable on your developer environment, including Windows or macOS, see Setting the SharePoint Framework Hosted Workbench Test Site.

Optional tools

While not required for SPFx development, you may also find the following tools useful:

Next steps

You're now ready to build your first client-side web part!

SPFx & SharePoint Server (on-prem)

The SPFx is available on SharePoint Online (SPO), SharePoint Server Subscription Edition (SE), SharePoint Server 2019, and SharePoint Server 2016. The configuration instructions on this page assume you're creating solutions using the latest version of the SPFx for SharePoint Online.

SharePoint Online contains all versions of the SPFx, including all previous and the latest version. Each SPFx solution contains information to tell SPO which SPFx runtime it depends on.

If you're building solutions for a SharePoint Server on-prem deployment, review to the See also section for details on specific SharePoint versions. Each SharePoint on-prem only supports a specific version of SPFx. This can introduce complicated development environment configurations if you're creating different solutions for different SharePoint deployments.

Depending on your scenario, you may need to maintain different development environments. Developers have used the following approaches to address these challenges:

  • virtual machines
  • Docker
  • Node version managers

Tip

For more information on Node version managers, see Better Node.js Install Management with Node Version Manager.

Troubleshooting

Check the version of globally installed packages

To get a list of all globally installed packages, run the following command:

npm list --global

Unable to Trust the Self-signed Development Certificate

If you're having trouble trusting your self-signed certificate when you run gulp trust-dev-cert & you've verified that the correct versions of all dependencies are installed, one solution we usually see resolve the issue is to uninstall all globally installed packages, uninstall Node.js, reboot & start again.

In some cases, executing the command gulp trust-dev-cert, doesn't have the wanted effect of trusting the self-signed development certificate on your machine. In rare cases such as these, you may need to delete a hidden folder that's generated in your profile folder.

Locate & delete the folder {{homedir}}/.gcb-serve-data for SPFx version earlier than v1.12.1. For later versions delete folder {{homedir}}/.rushstack then try to trust the self-signed development certificate again. Otherwise running gulp untrust-dev-cert will have same effect to remove the certificate files from the profile folder.

In case the certificate is not added to the Trusted Root Certification Authority despite running gulp trust-dev-cert because of some policies blocking the action, the rushstack-serve.pem file from {{homedir}}/.rushstack folder can be imported manually into the Certificate Manager under Trusted Root Certification Authority with a local admin account.

Unable to Install Packages with npm - Corporate Proxies

If your development environment is behind a corporate proxy, you need to configure npm to use that proxy. Refer to the npm-config documents on how to configure your development environment behind a corporate proxy... specifically the proxy & http-proxy settings. More information: Configure npm for a corporate web proxy

See also

  • Last updated on