Use GitHub Copilot to migrate SPFx 1.21 → 1.22 (Heft)

Use GitHub Copilot to migrate SPFx 1.21 → 1.22 (Heft)

Goal

Upgrade an SPFx 1.21 (gulp-based) project to 1.22 (Heft-based) safely. Use GitHub Copilot to analyze your repo, plan the migration, and execute steps with Microsoft 365 CLI.

References:

The Copilot prompt (paste into VS Code)

Use this structured prompt to have Copilot analyze and guide the migration. It’s designed for the workspace containing your SPFx solution.

You are assisting a migration of a SharePoint Framework solution from SPFx 1.21 (gulp-based) to SPFx 1.22 (Heft-based). Please:

1) Detect gulp customizations
- Search for `gulpfile.js`, `gulpfile.ts`, and calls to `build.configureWebpack`, `build.rig.addPreBuildTask`, `addPostBuildTask`, and custom tasks.
- Summarize each customization: purpose, impacted files, and whether it requires a Heft plugin or webpack ejection.

2) Verify Node.js + tool versions
- Read `.nvmrc` or `engines.node` in `package.json`.
- Report local Node version (`node -v`). If incompatible for SPFx 1.22, recommend a version from SPFx compatibility docs.

3) Prepare the migration
- List `package.json` dependencies that must update to 1.22 (SPFx packages) and dev scripts to replace (gulp → Heft scripts such as `heft build`, `heft start`, `heft package-solution`).
- Identify new config files expected in 1.22: `config/heft.json`, `config/typescript.json`, `rig.json` pointing to `@microsoft/spfx-web-build-rig`.

4) Use Microsoft 365 CLI for upgrade
- Provide commands with `m365 spo` or relevant `m365` commands to scaffold or upgrade where applicable.
- Example: `m365 spfx project upgrade --toVersion 1.22.0 --preview --output md > upgrade-report.md` and summarize changes.

5) PnP Controls review
- Search for references to `@pnp/spfx-controls-react` or related packages.
- Report versions and known compatibility notes with SPFx 1.22. Suggest updates and potential breaking changes.

6) API permissions audit
- Inspect `package-solution.json` `webApiPermissionRequests` and any AadManifest.
- Summarize required permissions and confirm they still apply post-upgrade.

7) Produce an actionable plan
- Assist with the generated `upgrade-report.md`, there is a section with Summary Execute script execute this to have the modifications done some of them has to be made manuell read this and execute this step by step
- Step-by-step tasks to: update dependencies, add Heft config, translate gulp customizations to Heft (plugins or run-scripts), validate webpack changes, run `heft start/build/package-solution`, and verify `.sppkg` outputs.
- Include commands and file changes.

Ground all recommendations in official Microsoft Learn pages (SPFx 1.22 release notes, Heft toolchain articles, migration guide).

Microsoft 365 CLI commands

Run these in your project root to generate an upgrade report and apply updates:

# Install M365 CLI if needed
npm i -g @pnp/cli-microsoft365

# Analyze and produce a report for upgrading to 1.22
m365 spfx project upgrade --toVersion 1.22.0 --preview --output md > upgrade-report.md

# Optional: authenticate for tenant operations (if you later validate permissions)
m365 login

Docs: https://learn.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/migrate-gulptoolchain-hefttoolchain

Detecting gulp customizations

Key patterns Copilot should summarize:

  • gulpfile.js / gulpfile.ts existence
  • build.configureWebpack.mergeConfig(...) custom webpack injection
  • build.rig.addPreBuildTask(...), addPostTypescriptTask(...), addPostBuildTask(...)
  • Custom tasks (copy files, generate code, stylelint)

Mapping to Heft options:

  • Use Heft included plugins (copy-files-plugin, run-script-plugin)
  • Extend SPFx rig with config/heft.json
  • For complex webpack changes, consider heft eject-webpack

Docs:

Verify Node.js version

Check what the project expects and what you’re running:

# your current Node
node -v

# project expectations
cat .nvmrc || jq .engines.node package.json

Use the SPFx compatibility table to choose the right Node LTS for 1.22. Docs: https://learn.microsoft.com/en-us/sharepoint/dev/spfx/compatibility

PnP Controls compatibility

If you use @pnp/spfx-controls-react, validate versions:

npm ls @pnp/spfx-controls-react

Check release notes for compatibility; update if necessary. Validate TypeScript 5.x changes. Docs: PnP Controls repo and SPFx migration guidance; SPFx 1.22 release notes.

Audit API permissions

Review your package-solution.json:

{
  "solution": {
    "webApiPermissionRequests": [
      { "resource": "Microsoft Graph", "scope": "User.Read" }
    ]
  }
}

Confirm the permission list still matches your code paths after migration. If you introduced new APIs, add permissions accordingly and re-consent in the tenant.

Docs: https://learn.microsoft.com/en-us/sharepoint/dev/spfx/use-aadhttpclient

  1. Run the M365 CLI upgrade report and read upgrade-report.md.
  2. Update SPFx dependencies in package.json to 1.22.
  3. Replace npm scripts with Heft scripts (heft build, heft start, heft package-solution).
  4. Add config/heft.json extending @microsoft/spfx-web-build-rig and migrate tasks:
    • Copy/Generate tasks → copy-files-plugin or run-script-plugin
    • Linting → run-script-plugin (example: stylelint)
  5. Translate webpack customizations; for deep changes use heft eject-webpack.
  6. Validate Node version against SPFx compatibility; switch via .nvmrc.
  7. Review @pnp/spfx-controls-react and other dependencies for compatibility.
  8. Audit webApiPermissionRequests and consent changes if needed.
  9. Run: heft start, heft build, heft package-solution and validate .sppkg.

TL;DR

  • Use a structured Copilot prompt to analyze gulp customizations, Node, dependencies, and permissions.
  • Generate an upgrade report with M365 CLI.
  • Migrate tasks to Heft via config/heft.json using built-in plugins or run-scripts.
  • Validate PnP controls and API permissions before packaging.