Essential Guide to Setup SPFx Development Environment

SharePoint Framework (SPFx) development requires a specific set of tools and configurations. Below is a comprehensive, up-to-date guide for setting up your environment for SPFx development on Windows, macOS, or Linux.

1. Install Node.js (LTS Version)

  • Download the latest Long Term Support (LTS) version of Node.js from the official Node.js website.
  • For SPFx v1.21 (current as of 2025), Node.js v22 LTS is recommended[1][2].
  • Run the installer and make sure that Node Package Manager (npm) is included.
  • Verify installation by running:

node --version
npm --version

You should see version numbers for both[1][2].

Once Node.js and npm are installed and verified, it’s a good practice to update npm to the latest version. Run npm install -g npm to do this. This ensures compatibility and access to the newest features and bug fixes.

After confirming your Node.js and npm setup, configure your npm registry and cache. If you’re behind a corporate proxy or firewall, follow your IT team’s guidelines for proxy settings. Setting these configurations early can help prevent package installation issues later on.

Check the compatibility of your Node, TypeScript, and SPFx versions. Refer to the latest compatibility table here.    

2. Install a Code Editor

  • You can use any code editor, but Visual Studio Code is highly recommended for its integration and extensions[1].
  • Alternatives include WebStorm, Atom, or Sublime Text.

3. Install Global Development Toolchain Prerequisites

Open a terminal or command prompt and run:

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

This command installs:

  • Gulp CLI: Task runner for building and serving projects.
  • Yeoman: Scaffolding tool for generating project structure.
  • SPFx Yeoman Generator: Tool to scaffold SPFx projects[1][2].

4. (Optional but Recommended) Use a Node Version Manager

  • Tools like NVM (Node Version Manager) or NVS (Node Version Switcher) allow you to manage multiple Node.js versions, which is useful if you work on different SPFx or Node.js projects[3].
  • Install NVM/NVS and use it to install the required Node.js LTS version.

5. Install a Modern Web Browser

  • Use Microsoft Edge, Google Chrome, or Mozilla Firefox for testing and development[1].

6. (Optional) Install Additional Useful Tools

  • Git for source control.
  • Postman for API testing.
  • Windows Terminal or Oh My Zsh for enhanced command-line experience[1].

7. Create Your First SPFx Project

  • Create a new directory for your project and navigate into it:

mkdir my-spfx-webpart
cd my-spfx-webpart

  • Scaffold a new SPFx project:

yo @microsoft/sharepoint

  • Answer the prompts (solution name, target environment, web part name, framework, etc.).
    • For beginners, select “No JavaScript Framework” for simplicity[2].
  • Install project dependencies:

npm install

8. Trust the Developer Certificate

  • SPFx uses HTTPS for local development. Trust the self-signed certificate by running:

gulp trust-dev-cert

This ensures your browser trusts the local development server[1].

9. Build and Run Your Web Part

  • Navigate to your project folder (if not already there).
  • Start the local development server:

gulp serve

This compiles your project and opens the SharePoint Workbench for testing[2].

10. (Optional) Configure the SPFX_SERVE_TENANT_DOMAIN Environment Variable

  • For advanced scenarios, set this variable to dynamically specify the tenant domain in your serve configuration[1].

Summary Table

StepActionCommand/Tool
1Install Node.js (LTS)nodejs.org
2Install Code EditorVS Code/WebStorm
3Install Toolchainnpm install -g gulp-cli yo @microsoft/generator-sharepoint
4(Optional) Node Version ManagerNVM/NVS
5Install BrowserEdge/Chrome/Firefox
6(Optional) Additional ToolsGit, Fiddler, Postman
7Scaffold Projectyo @microsoft/sharepoint
8Trust Certificategulp trust-dev-cert
9Build & Servegulp serve
10(Optional) Set Env VariableSPFX_SERVE_TENANT_DOMAIN

You are now ready to develop SPFx solutions! For more details, refer to the official Microsoft documentation and community guides[1][2].

  1. https://github.com/SharePoint/sp-dev-docs/blob/main/docs/spfx/set-up-your-development-environment.md?plain=1   
  2. https://edvaldoguimaraes.com.br/2024/10/13/setting-up-your-development-environment-for-sharepoint-framework-spfx
  3. https://pnp.github.io/blog/post/spfx-setup-part1-nvm-nvs   
  4. https://learn.microsoft.com/en-us/sharepoint/dev/spfx/compatibility