Migrating from gulp and Heft

TL;DR: Move an existing SPFx project by dropping gulp and Heft files, rewriting entrypoints, and adding a bundler config. Run rspfx migrate to automate it. To try without migrating, see Try mode.

This is the definitive guide to SPFx replace Webpack, SPFx eject webpack, SPFx custom Webpack, and the SPFx Heft custom toolchain replacement — the SPFx custom build pipeline that replaces webpack + Heft + gulp. See Migration case study for a real example.

See also Why RSPFx for "SPFx Vite", "SPFx Vite replacement", "SPFx alternative bundler", "SharePoint Framework Vite", "SharePoint Framework alternative build tool", "SPFx Rspack", and "SPFx esbuild" search terms.

Read Why not to migrate first if you are unsure. For a zero-risk trial that keeps gulp and Heft, start with Try mode.

What you keep

Item	Status
src/webparts/<name>/	unchanged
config/package-solution.json	read directly
config/serve.json	read directly
config/config.json	honored - entrypoints rewritten from ./lib/ to ./src/
config/write-manifests.json	cdnBasePath honored
sharepoint/ assets	unchanged
@microsoft/sp-*	externalized - keep only if you import that runtime
Localized strings	resolved via localizedResources
Lazy import() chunks, SCSS modules, HTML, JSON	supported

Shared manifests for both toolchains

config/config.json, config/package-solution.json, and src/*/*.manifest.json work for Heft and RSPFx. You can keep Heft for prod and use rspfx dev for dev before you migrate. See Hybrid dev.

Automated path

Preview, then apply:

rspfx migrate --dry-run
rspfx migrate
bun install
rspfx dev
rspfx package

rspfx migrate writes vite.config.ts by default. Use --bundler rspack or --bundler rsbuild for those files.

After migrate, bun run build and rspfx build run the chosen bundler. Dry run touches no files. The command backs up to .rspfx/migrate-backup.json.

Revert

rspfx migrate --revert

Or:

git restore .
git clean -fd .rspfx
bun install

Delete the generated vite.config.ts, rspack.config.ts, or rsbuild.config.ts if present.

What gets removed

• gulpfile.js and Heft rig - gulp serve, heft test, heft clean go away.
• Toolchain dev deps - heft, spfx-heft-plugins, spfx-web-build-rig, rush-stack-compiler-*, sp-build-web, gulp, webpack, loaders.
• Heft configs - config/rig.json, config/typescript.json, config/sass.json, config/deploy-azure-storage.json, config/spfx-customize-webpack.js.
• Heft scripts - start, eject-webpack.

What rspfx migrate does

The command is idempotent. It never installs.

1. package.json - drops toolchain dev deps, adds rspfx scripts, relaxes engines.node to >=20, adds @mbsks/rspfx-plugin.
2. config/config.json - rewrites entrypoints ./lib/webparts/<name>/<Name>WebPart.js to ./src/webparts/<name>/<Name>WebPart.ts and renames bundle keys to folder names.
3. SCSS - rewrites @import 'pkg:<pkg>/<path>' to a relative node_modules path.
4. Deletes Heft only config files.
5. Writes bundler config and a plain tsconfig.json if the old one extended a rig.

Troubleshoot

Symptom	Fix
entrypoint not found	rewrite config.json from ./lib/... to ./src/...
Can't resolve XxxWebPartStrings	check localizedResources
Manifest missing <bundle>.js	bundle name must equal folder name or set paths
@import 'pkg:…' fails	rewrite as in step 5
Type errors on *.module.scss	add declare module '*.module.scss'

After migration

Migrate keeps the detected spfxVersion. To change it, edit spfxVersion: '1.24' and run bun update @mbsks/rspfx-plugin.

See Upgrading SPFx version and ../../reference/compatibility.md.