The SharePoint Framework (SPFx) has taken a major step forward with version 1.22 by introducing a modern Heft-based build toolchain.
This change marks the beginning of the end for the legacy Gulp-based tooling
and aligns SPFx with modern JavaScript engineering practices.
In this post, I’ll explain what Heft is, why it
matters, what changes you’ll see, and how to upgrade existing
SPFx solutions safely.
🔍 What Is the Heft-Based
Toolchain?
Heft is a modern build orchestration tool developed
under the RushStack ecosystem and now adopted by Microsoft for SPFx.
Starting with SPFx 1.22, Heft becomes the default
build system for new projects, replacing the long-standing Gulp pipeline.
Key characteristics:
- Configuration-driven
(not task-driven)
- Plugin-based
architecture
- Better
alignment with modern Node.js and TypeScript
- Optimized
for CI/CD and long-term maintainability
🆚 Heft vs Gulp: Why the
Change?
Legacy Gulp-Based Toolchain
- Task-oriented
(gulp serve, gulp bundle)
- Heavy
reliance on custom Gulp tasks
- Harder
to extend and maintain
- Increasing
compatibility issues with newer Node.js versions
Modern Heft-Based Toolchain
|
Area |
Heft |
Gulp (Legacy) |
|
Architecture |
Config &
plugin-based |
Task-based |
|
Build consistency |
High |
Varies by custom tasks |
|
Node.js support |
Modern (Node 22 LTS) |
Transitional |
|
CI/CD readiness |
Excellent |
Requires tuning |
|
Future support |
✅ Yes |
❌ Deprecated (planned) |
Bottom line:
Heft is not just a replacement — it’s a modernization of how
SPFx solutions are built, tested, and packaged.
✅ Prerequisites for Heft-Based
SPFx Development
Before getting started, ensure the following:
- Node.js
22 LTS (supported for SPFx 1.22.*)
- SPFx
Generator 1.22.1
- npm
install -g @microsoft/generator-sharepoint@1.22.1
- npm
(comes with Node.js)
- No
global Heft installation required (installed locally per project)
📦 What Changes Will You
See in package.json?
One of the first visible differences is the absence of
Gulp and the presence of Heft-specific scripts and dependencies.
🔹 Scripts Section
(Heft-Based)
"scripts": {
"build": "heft
test --clean --production && heft package-solution --production",
"start": "heft
start --clean",
"clean": "heft
clean",
"eject-webpack":
"heft eject-webpack"
}
➡️ npm run start replaces gulp
serve
🔹 New Key Dependencies
"@rushstack/heft": "1.1.2",
"@types/heft-jest": "1.0.2",
"@microsoft/spfx-web-build-rig": "1.22.1",
"@microsoft/spfx-heft-plugins": "1.22.1"
🔹 What’s Missing
(Intentionally)
- ❌
gulp
- ❌
gulpfile.js
- ❌
@microsoft/sp-build-web
This confirms the project is 100% Heft-based.
🛠️ How to Create a New
Heft-Based SPFx Solution
Choose:
- SPFx
version: 1.22.1
- Build
toolchain: Heft (default)
Then:
npm install
npm run start
That’s it — no extra configuration required.
🔄 Recommended Upgrade
Strategy (Existing Projects)
Microsoft has provided a transition window, not a
forced migration.
✔️ Phase 1: Upgrade SPFx Version
(Keep Gulp)
- Upgrade
legacy projects to SPFx 1.22.1
- Continue
using Gulp
- Minimal
risk
npx @microsoft/spfx-upgrade --toVersion 1.22.1
✔️ Phase 2: Prepare for Heft
Migration
- Identify
custom Gulp tasks
- Review
webpack customizations
- Validate
CI/CD pipelines
✔️ Phase 3: Migrate to Heft
(Before SPFx ~1.24)
- Remove
Gulp tooling
- Remove
@microsoft/sp-build-web
- Add
Heft configs
- Switch
to npm scripts
- Backup your project - always keep a working copy of your Gulp-based solution.
- Upgrade SPFx version using:
- npm install @microsoft/sp-build-web@1.22
- Run project upgrade command:
- gulp upgrade
Microsoft has clearly indicated that Gulp will be
deprecated and eventually unsupported in future SPFx versions (expected
around 1.24).
🧭 When Should You Migrate
Legacy Applications?
|
Application Type |
Recommendation |
|
Business-critical |
Migrate later, after
validation |
|
Internal /
low-risk |
Migrate early |
|
New development |
Heft only |
|
Long-term support
apps |
Must migrate |
Microsoft has given a clear direction (but not a
hard “drop-dead” date yet) for upgrading existing SPFx projects.
Here’s the official timeline + practical interpretation
👇
🧭 Microsoft’s Position on
Gulp → Heft Migration
✅ Current state (SPFx 1.22.x –
today)
- Gulp-based
projects are still supported
- Heft
is the default for new projects
- Existing
projects are NOT forced to migrate
- Both
toolchains are officially supported
👉 This is a transition
phase
⏳ The Important Future Milestone
(This Is the Key)
🚨 SPFx ~1.24 (Planned)
Microsoft has clearly stated:
The Gulp-based toolchain will be deprecated and
eventually unsupported.
What this means in practice:
|
Stage |
Meaning |
|
1.22 – 1.23 |
Gulp supported (transition period) |
|
~1.24 |
Gulp deprecated (warnings, no new fixes) |
|
After 1.24 |
Gulp removed / unsupported |
📌 Microsoft has explicitly
said:
- No
new features
- No
bug fixes
- No
Node compatibility guarantees for Gulp after that point
So while there is no exact calendar date, the version
boundary is very clear.
🗓️ Practical Timeline
(Industry Reality)
Based on Microsoft’s SPFx release cadence:
|
Timeframe |
What You Should Do |
|
Now – next few
months |
Keep existing Gulp
projects running |
|
Next 6–9 months |
Start migrating important
projects |
|
Before SPFx 1.24
adoption |
Finish migration |
|
After 1.24 |
Heft-only world |
🧠 Microsoft’s Intent
(Very Clear Signal)
Microsoft intentionally:
- Introduced
Heft in 1.22
- Kept
Gulp alive temporarily
- Did
NOT auto-migrate projects
- Gave
teams multiple releases to adapt
This is a grace period, not permanent coexistence.
🧩 Do You Need to Rush Right
Now?
No.
But you should plan.
Safe approach:
- 🟢
Business-critical apps → migrate later
- 🟢
Low-risk / internal apps → migrate first
- 🟢
New apps → Heft only
🧭 Recommended Upgrade
Strategy (Architect View)
Phase 1 – Stabilize (Now)
- Upgrade
old projects to SPFx 1.22.1
- Keep
Gulp
- Ensure
Node 22 compatibility
Phase 2 – Prepare (Next)
- Identify:
- Custom
Gulp tasks
- Custom
webpack config
- Document
differences
Phase 3 – Migrate (Before 1.24)
- Remove
Gulp
- Remove
@microsoft/sp-build-web
- Move
to Heft
- Update
CI/CD commands
🔑 Key Takeaway (This Is
the Answer)
❗ Microsoft has NOT given a
forced immediate deadline
❗
But Gulp WILL be removed in a future SPFx version (≈1.24)
❗
1.22–1.23 is the official migration window
Microsoft has effectively given you time,
but not unlimited time.
🎯 Key Takeaways
- SPFx
1.22 introduces a modern, Heft-based build system
- Gulp
is still supported temporarily, but its days are numbered
- New
projects should always use Heft
- Existing
projects should plan migration, not rush it
- Heft offers better performance, maintainability, and future compatibility
🚀 Final Thoughts
The move to Heft is a strategic evolution, not just a
tooling change.
Teams that adopt it early will benefit from cleaner builds, easier upgrades,
and long-term stability.
If you’re maintaining multiple SPFx solutions, now is the
right time to:
- Standardize
your development setup
- Educate
your team
- Plan
a phased migration
Upgrade safely, migrate intentionally, and future-proof your solutions.
📚 References & Acknowledgements
🔹 Official Microsoft References
This document is aligned with and referenced from official Microsoft documentation, including:
SharePoint Framework – Set up your development environment
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-development-environment
These references were used to ensure accuracy around:
Supported Node.js versions
SPFx 1.22+ tooling changes
Heft-based build system adoption
Microsoft’s recommended development practices
🔹 Content Development Acknowledgement
The technical analysis, structure, explanations, upgrade strategies, and architectural guidance in this document were authored with content-writing and structuring assistance from an AI-based technical writing assistant, based on real-world SPFx modernization scenarios and industry best practices.
All technical decisions, interpretations, and implementation responsibility remain with the author.
No comments :
Post a Comment