🧠 Modern SPFx Development with v1.22.2, Heft, and Docker

/ Sudharsan K...

🚀 What’s New in SPFx 1.22.x

With the release of SharePoint Framework (SPFx) 1.22 and subsequent patch 1.22.2, Microsoft delivered the biggest toolchain shift in years by replacing the legacy gulp-based build system with Heft — a configuration-driven task orchestrator from the Rush Stack ecosystem.

Key Highlights

  • 🔄 Heft replaces gulp as the default build orchestrator for new projects. Webpack remains the bundler but is now orchestrated via Heft plugins instead of gulp tasks.
  • 🧰 Projects scaffolded with the latest generator include config files such as heft.json, rig.json, typescript.json, and sass.json.
  • 🛡 npm audit issues in scaffolded projects and generator dependencies have been addressed.
  • 🆕 Default TypeScript version for new projects is now TS 5.8.
  • 📦 v1.22.2 is a minor patch releasing monthly updates focused on keeping the local dev environment free from audit warnings and ensuring predictable dependency hygiene.

This transition aligns SPFx with modern build tooling, making it more maintainable, scalable, and consistent with other Microsoft 365 toolchains.

🧪 Heft: What Is It and Why It Matters

Heft is a config-driven build orchestrator designed for large codebases and monorepos. It replaces complex custom scripts with structured configurations and extensibility via plugins. Unlike gulp where custom .js tasks were common, Heft encourages declarative, maintainable build definitions.

What Heft gives you:

  • Consistent tooling for build, serve, test, and lint.
  • Clear configuration files instead of gulpfiles.
  • Easier integration with standard workflows and extensibility models.

🐳 Introducing the sudharsank/spfx Docker Image

To make modern SPFx development easier for everyone — regardless of OS or machine architecture — I’ve published the Docker image sudharsank/spfx on Docker Hub:
👉 https://hub.docker.com/r/sudharsank/spfx sudharsank/spfx Docker Hub image

This container provides a ready-to-use development environment for SPFx 1.22.2 projects with support for:

  • 🔹 Heft-based toolchain
  • 🔹 Yeoman SPFx generator
  • 🔹 Multi-architecture builds (AMD64 & ARM64 via Docker manifest)
  • 🔹 Works on Windows, macOS, and Linux via Docker Desktop
  • 🔹 Exposed ports for serve & live reload

🧰 What’s Inside the Image

While the Docker Hub page lists the overview, this image is specifically designed for SPFx 1.22+ with Heft support:

✔ Yeoman (yo)
✔ @microsoft/generator-sharepoint@latest
✔ Heft CLI (@rushstack/heft)
✔ Node (multi-arch base supported)
✔ Webpack and SPFx build ecosystem

All tooling required for generation, build, serve, and debugging is included.

🚀 Getting Started with the Docker Image

1. Create or Navigate to Your SPFx Project

mkdir spfx-demo
cd spfx-demo

2. Run the Docker Container

docker run -it --rm \
-v "$PWD":/usr/app/spfx \
-p 4321:4321 \
-p 35729:35729 \
sudharsank/spfx:latest


Inside the container:

yo @microsoft/sharepoint
npm install
npm run build
npm run serve

This scaffolds and bootstraps a new SPFx project using Heft-based scripts (e.g., npm run build now calls heft build).

🛠 Development Workflow

Serve Config Update

To allow SPFx serve to work in Docker (not just localhost), ensure your project’s config/serve.json looks like:

{
  "hostname": "0.0.0.0",
  "port": 4321,
  "https": true
}

This ensures external devices and browsers can reach the local workbench running inside Docker.

🧩 Behind the Scenes: Multi-Arch Support

The Docker image is built as a multi-architecture image supporting both linux/amd64 and linux/arm64. This means it can run natively on:

  • Intel/AMD machines
  • Apple Silicon Macs
  • Linux ARM servers

Docker automatically pulls the correct image variant based on your host architecture, thanks to Docker’s multi-platform image manifests.

🔄 Migrating Existing Projects

For projects originally scaffolded with gulp (pre-1.22):

  1. Update SPFx dependencies in package.json to 1.22.x.
  2. Start using Heft-based build scripts.
  3. Migrate custom gulp tasks to Heft plugin or config equivalents.

Microsoft provides guidance on migration from gulp to Heft, but the easiest path for most is to gradually adopt Heft while keeping the project build stable.

✍️ Conclusion

SPFx 1.22 and 1.22.2 represent a modern, scalable, and secure evolution of the SharePoint Framework. By replacing the old gulp-centric toolchain with Heft and shipping a high-quality Docker image (sudharsank/spfx), we can now deliver consistent dev environments across platforms — empowering developers to scaffold, build, and serve SPFx projects with ease.

👉 Try the image today:
https://hub.docker.com/r/sudharsank/spfx sudharsank/spfx Docker Hub image

Happy Sharing…

Leave a comment