Why you should NOT migrate (yet)
RSPFx is young. It mirrors official SPFx formats, but it's not the official toolchain and doesn't support everything. This is the honest decision guide — if a row matches you, staying on gulp/Heft is lower-risk. See Microsoft docs: SharePoint Framework overview and SPFx compatibility.
Tip: Try in a branch before deciding:
rspfx migrate --dry-run,rspfx doctor,rspfx dev,rspfx package. You'll know within an hour if you're in the happy path. See migrating-from-gulp-heft.md.
Hard blockers — do not migrate if this is you
| Feature | RSPFx status | What to do |
|---|---|---|
| SharePoint 2019 / on-premises | ❌ Not supported | Stay on official. RSPFx targets SPFx Online only — see compatibility.md#spfx-version-matrix. |
| Other framework without a preset | ⚠️ Bring your own preset | No built-in preset for other frameworks. Any framework works via FrameworkPreset + BaseWebPart (see custom-framework.md). Don't migrate unless you can provide it. |
Everything else is supported or has a workable alternative.
Supported — verified
All compile, preview locally and in the workbench, and install from the app catalog:
| Component | Status | Notes |
|---|---|---|
| Web parts (React, Vanilla, Solid, Preact, Vue, Svelte) | ✅ | rspfx new --framework <id>; see frameworks.md |
| Application extensions | ✅ | rspfx new --component applicationcustomizer |
| Field customizers | ✅ | rspfx new --component fieldcustomizer |
| List view command sets | ✅ | Mock list view with onExecute wiring |
| Form customizers | ✅ | rspfx new --component formcustomizer |
SPFx libraries (src/libraries/) | ✅ | componentType: Library → Library_<id>.xml |
| Teams tab / personal app | ✅ | teams/ folder with manifest.json v1.13 + icons |
See real-tenant-validation.md for verification. See Microsoft docs: Extensions overview, Library component overview, and Integrate with Microsoft Teams.
Warnings — eyes open
| Feature | Consequence | Alternative |
|---|---|---|
| Custom gulp pipelines | No gulp task ecosystem | Use plugin-api hooks or extend your bundler config — you own the scripting |
| Webpack config surgery | spfx-customize-webpack.js deleted; webpack-only loaders don't auto-port | Configure via RspfxPlugin / rspfxVite in your bundler file; most aliases are unnecessary |
| SPFx version pinning | spfxVersion typed to supported targets | Keep sp-* pins in sync — rspfx doctor warns on drift. See compatibility.md#spfx-version-matrix |
| Multi-locale | ✅ Works | Per-locale AMD modules; preview honors ?locale=fr-fr |
| React 18/19 skew | Same as official | Bundle React per web part; watch version skew |
Tip: If your webpack surgery only adds aliases or polyfills, you likely don't need it — try building without it and check
rspfx doctor.
Softer risks
- Young toolchain — fewer battle-tested users than
gulp serve+spfx-fast-serve. - Framework APIs unstable until M5.
- No build-extension ecosystem (no PnP CLI build plugins, no Heft rigs; PnPjs libraries still work).
- Microsoft supports the official pipeline; Stack Overflow won't cover RSPFx.
- CI is yours to port (~10 lines, see migrating-from-gulp-heft.md).
.sppkgformat captured from official packages and validated by tenant install per real-tenant-validation.md and reference/FORMATS.md.
When migration IS the right call
- Web parts, extensions, or libraries on SPFx Online.
- Team wants fast builds (seconds vs minutes), zero Heft/webpack surface, one config file.
- You can live without gulp-task plumbing.
Decision table
| Your project | Verdict |
|---|---|
| 1 web part, React, standard config | ✅ Migrate |
| 4 web parts, localization, PnP controls | ✅ Migrate (?locale= works) |
| Extension or library | ✅ Migrate |
| Other framework without a preset | ⚠️ Bring a preset first — see custom-framework.md |
| Custom webpack doing real work | ⚠️ Try it — extend bundler config; webpack-only plugins may need equivalents |
| SPFx 1.16 / 2019 / on-prem | ❌ Don't |
| Risk-averse enterprise | ❌ Don't — revisit at stable release |
Comparison vs official
| Aspect | Official (gulp/Heft) | RSPFx |
|---|---|---|
| Web parts + extensions + libraries (Online) | ✅ | ✅ (verified) |
| On-premises / 2019 | ✅ | ❌ |
| Other frameworks | — no preset | ✅ one-file FrameworkPreset — see custom-framework.md |
| Build speed | Minutes | Seconds (Vite/Rsbuild/Rspack + SWC) |
| Config files | Many (gulpfile, Heft rig, webpack overlay) | One optional bundler config, else zero-config |
| Support | Microsoft + Stack Overflow | Community |