Set Up SharePoint Framework (SPFx) Project with Heft [Step-by-Step Guide]

If you’ve worked with SharePoint Framework before, you might remember the older setup where we used Gulp for building and running projects. It was the standard way of working, and most projects followed the same approach.

With SPFx 1.22, things have changed. Microsoft has introduced a new build system called Heft, which replaces Gulp and handles the build process more structurally.

In this guide, I’ll walk you through how to set up a new SharePoint Framework (SPFx) project with Heft step by step, from checking what’s already installed, cleaning up old tools, installing the right versions, creating the project, and ensuring everything runs properly.

What Is Heft and Why Should You Care?

Heft is a config-driven build toolchain from Microsoft’s Rush Stack ecosystem. Instead of writing JavaScript task files (like the old gulpfile.js), you configure your build process using JSON files. Heft then calls the tools you need: TypeScript compiler, ESLint, Jest, Webpack, in the right order, at the right time.

Think of it this way: with Gulp, you had a JavaScript file that said: “do this, then do that.” With Heft, you have JSON files that say “here’s how the build is structured” — and Heft figures out the execution.

Here’s why Microsoft moved to Heft:

• The old Gulp toolchain (@microsoft/sp-build-web and gulp-core-build) had barely been maintained since around 2020. It had outdated npm dependencies and triggered dozens of audit warnings.
• The build process was essentially a black box. Developers couldn’t easily see or customize what was happening internally.
• Microsoft had already switched to Heft internally for products like Microsoft Teams, Office Web, and VS Code extensions, but SPFx developers were still stuck on the old system.

By moving SPFx to Heft, Microsoft unified its internal and external development experience. Now, when Microsoft ships improvements to Heft, SPFx developers benefit from them automatically, not months later.

Want to learn SPFx development? Check out the complete SPFx training course.

Setting Up a New SPFx Project with Heft

Now that you have a basic idea of what Heft is and why it’s being used, let’s move to the practical part. Instead of jumping straight into creating a project, I like to check my local environment first. This helps ensure everything is in good condition before we start.

Step 1: Check Your Current Environment

Before installing anything, I always check what’s already on the system. This avoids weird conflicts later. Open your terminal and run:

node -v
npm -v
yo --version
gulp -v

What you’re looking for

• Node version (important)
• npm version
• Yeoman version
• Whether Gulp is still installed

At this stage, I’m just trying to understand what I’m working with, not fixing anything yet.

Check globally installed packages

npm list -g --depth=0

This shows all global tools, like:

• Yeoman (yo)
• SPFx generator
• Gulp CLI (if still installed)
• Heft (optional)

Sometimes you’ll find tools here that you forgot you installed months ago.

Check specific packages

npm list -g gulp
npm list -g @microsoft/generator-sharepoint
npm list -g typescript

This helps confirm whether old tools are still hanging around. I usually do this just to be 100% sure before cleaning things up.

Step 2: Remove Old Gulp-Based Tooling

If you’ve worked with older SPFx versions, you probably have Gulp installed globally. Most of us do, especially if we’ve been working with SPFx for a while.

We don’t need it anymore.

Remove Gulp CLI

npm uninstall -g gulp-cli

Check if Gulp is still available

gulp -v

If it still shows up, it means there are leftover files. This happens more often than you’d expect on Windows.

Find where Gulp is coming from

where gulp

If you see something like:

C:\Program Files\nodejs\gulp.cmd

Then manually delete:

del "C:\Program Files\nodejs\gulp"
del "C:\Program Files\nodejs\gulp.cmd"
del "C:\Program Files\nodejs\gulp.ps1"

Restart your terminal and confirm:

gulp -v

You should see:

'gulp' is not recognized...

Once you see this, you know Gulp is completely gone.

Step 3: Clean Up Global Tools

Now let’s make sure only the necessary tools remain.

Ensure Yeoman is up to date

npm install -g yo

Verify:

yo --version

You should see version 7.x or higher. If it’s not updated, it can cause weird issues during scaffolding.

Reinstall SPFx Generator

Even if it’s already installed, I prefer a clean reinstall:

npm uninstall -g @microsoft/generator-sharepoint
npm install @microsoft/generator-sharepoint --global

Install Heft

Now install the heft globally by running the command below.

npm install @rushstack/heft --global

Final global check

npm list -g --depth=0

You should now have something like:

• yo
• @microsoft/generator-sharepoint
• npm
• rushstack

That’s it. Clean and simple.

Step 4: Create a New SPFx Project

Now we’re ready to actually create the project.

Create a folder

md SPFxHeftProject
cd SPFxHeftProject

Run the generator

yo @microsoft/sharepoint

When prompted:

• What is your solution name? sp-fx-heft-project
• Which type of client-side component to create? WebPart
• Add new Web part to solution sp-fx-heft-project.
• What is your Web part name? HeftProject
• Which template would you like to use? React

Step 5: Understand What Just Changed

When the generator runs, it defaults to the Heft-based toolchain. You’ll notice immediately that the generated project looks slightly different from older projects:

• There’s no gulpfile.js
• There’s a ./config/rig.json file
• There’s a ./config/sass.json that extends the rig configuration
• There’s a ./config/typescript.json for TypeScript plugin settings
• The package.json scripts call heft instead of gulp

This confirms you’re using the new Heft-based build system. This is the key difference compared to older SPFx projects. The Gulf file is also not there.

Your new package.json scripts section will look like this:

  "scripts": {
    "build": "heft test --clean --production && heft package-solution --production",
    "start": "heft start --clean",
    "clean": "heft clean",
    "eject-webpack": "heft eject-webpack"
  }

Notice a couple of things here. First, the bundle task is gone — in Heft, build handles both building and bundling in one step. Second, there’s a brand new deploy command (heft dev-deploy) that didn’t exist in the Gulp world. I’ll explain that below.

The New dev-deploy Command:

This is genuinely useful. With the old toolchain, during development, you’d run gulp serve, and your assets were served locally. With dev-deploy, you can push your built assets to a testing CDN and validate how your component behaves when it’s loaded from an external source rather than localhost.

This is great for catching CDN-specific issues before you do a full production deployment.

Heft vs. Gulp: The Command Mapping

If you’ve been using the old toolchain, here’s the side-by-side comparison you need:

What you used to run (Gulp)	What you run now (Heft)
gulp build	heft build
gulp bundle	(merged into heft build)
gulp clean	heft clean
gulp test	heft test
gulp serve	heft start
gulp package-solution	heft package-solution
gulp package-solution --ship	heft package-solution --production
gulp deploy-azure-storage	heft deploy-azure-storage
gulp trust-dev-cert	heft trust-dev-cert
(didn’t exist)	heft dev-deploy

One important note: --ship no longer works. If you have any CI/CD pipelines running gulp package-solution --ship, update them to use heft package-solution --production.

The Building Blocks: Actions, Phases, Tasks, and Rigs

Now you need to understand how Heft organizes work. It has a specific vocabulary, and once you know these four terms, everything clicks.

• Actions are the top-level commands you run from the CLI. For example, heft build, heft test, heft start. These are similar to the gulp tasks you used to have.
• Phases are logical groupings of work within an action. The build action might contain a build phase and a test phase.
• Tasks live inside phases. A task is a single unit of work — like compiling TypeScript, compiling Sass, or running ESLint.
• Rigs are the really clever part. A rig is a shared, reusable configuration package. Instead of every SPFx project carrying its own massive heft.json file with all the build logic, your project points to a rig package (@microsoft/spfx-web-build-rig) that contains all the default build configuration. Your project only defines what’s different from the default.

In practice, a new SPFx v1.22 project has a very lean ./config/rig.json file that looks like this:

{
  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
  "rigPackageName": "@microsoft/spfx-web-build-rig"
}

That single file tells Heft: “use all the build phases, tasks, and configurations defined in the SPFx rig package.” Clean and simple.

Step 6: Trusting the Development Certificate

SPFx uses a local HTTPS server for development that relies on a self-signed certificate. Since this certificate isn’t trusted by default, you need to manually trust it once after creating your project.

heft trust-dev-cert

Step 7: Update the Workbench URL

Before testing your web part, make sure to update the initialPage in the serve.json file. Replace {tenantDomain} with your actual SharePoint tenant URL so the local workbench opens correctly in your environment.

Step 8: Run the Project

Instead of the old Gulp command:

gulp serve

You now use:

npm run start
# or
heft start --clean

After running the command, the local workbench will open in your browser. At this point, you may see a prompt asking “Allow debug scripts?”. This is expected when running SPFx solutions locally, as the page is loading scripts from your development machine.

Since you are testing your own code, you can safely click “Load debug scripts” to proceed and continue testing your web part.

Then, the page below will open. Click the + Add icon and find your web part. You can either search for your web part name, and it will display.

Once you’re confident that your web part is working as expected, the next step is to prepare it for deployment. Run the command below to create the package, and once it completes, you’ll find the .sppkg file inside the sharepoint folder, as shown in the image below.

heft package-solution --production

Now upload the generated .sppkg file to your tenant app catalog or site collection app catalog. The deployment process remains the same as before, so you can follow the usual steps you’ve already used for deploying SPFx solutions.

Common Mistakes to Avoid

From experience, these are the most common issues and how you can avoid them.

1. Using the wrong Node version

Symptoms:

• npm install fails
• build errors

Fix: Switch to Node 18

2. Old Gulp is still installed

Symptoms:

• Confusion between commands
• unexpected behavior

Fix: Remove Gulp completely

3. Multiple Yeoman versions

• Symptoms: Wrong generator behavior
• Fix: Clean reinstall of yo

4. Mixing old and new projects

Don’t try to upgrade old Gulp-based projects manually.
Create a fresh one instead.

Conclusion

In this tutorial, I explained how to create a SPFx project using Heft step by step. Setting up SPFx used to be a bit messy, especially with all the global dependencies and Gulp-based tooling.

With Heft, things are much cleaner—but only if your environment is clean to begin with.

If you follow this approach:

• Check what’s installed
• Remove old tools
• Use the correct Node version
• Install only what’s needed

You’ll avoid most of the common headaches. Do let me know if you still have any questions.

Also, you may like:

• SPFx ListView Command Set Extension Tutorial: Create & Deploy with Example
• Add Custom Controls in SPFx Property Pane
• Display SharePoint List Items in SPFx Web Part (Complete Tutorial)
• Build a SharePoint Folder Tree View Using SharePoint Framework (SPFx)