AI-Driven SPFx 1.22 Upgrade: A Reproducible Process Flow

Source: Dev.to

Introduction

With the release of SharePoint Framework (SPFx) 1.22, Microsoft introduced a brand‑new build chain. The changes are so extensive that SPFx 1.22 feels more like a 2.0 release than a minor update.

The classic gulp/webpack toolchain is being phased out in favor of Microsoft’s new build system called Heft:

https://heft.rushstack.io

The key question is: How can you upgrade existing SPFx projects to SPFx 1.22 and Heft without breaking anything—especially when you touch an older project for the first time?

TL;DR

This post walks through a reproducible, AI‑driven process for upgrading SPFx projects to SPFx 1.22 and the Heft build chain. At the end you’ll find a ready‑to‑copy AI prompt you can run on any project.

DISCLAIMER – If you use spfx‑fast‑serve the flow may differ; it is oriented toward regular SPFx projects.

My previous way to upgrade SPFx

At the time of writing the only supported version was 1.22.0 (release candidate 0). Someone will have to update the code to the released version.

Since I started using Copilot, I feed the upgrade output directly into it, and Copilot performs the upgrade for me.

One prompt to upgrade

A manual upgrade doesn’t automatically mean it’s better. Humans make mistakes and can overlook important details. Artificial intelligence also makes errors—but it can often detect and correct its own issues (which is admittedly a bit scary).

To handle the upgrade I created a single prompt and tested it across multiple SPFx projects, including scenarios where several projects coexist in the same repository.

Let’s break it down.

1. Read the instructions

The upgrade definition lives here:

Follow these instructions to upgrade to the latest SPFx version using Heft:
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/migrate-gulptoolchain-hefttoolchain

By giving the AI this piece of instruction I tell it exactly what I want to do. I read the upgrade definition, analyze it, and get a basic understanding of the required steps.

2. Build a safety net

When I use AI I want to know every risk I’m facing after the upgrade. The repository often contains hidden documentation that I might not be aware of.

Before you start the migration, perform a risk assessment of the
current solution and document it in a Markdown file.

This second step gives me a full analysis of the project, highlights potential issues, and lets me abort the upgrade before any damage is done.

Example risk‑assessment output

First, an inventory of the current solution is generated, followed by the identified risks.

With that, I have a clear understanding of how to deal with the risks.

3. After acceptance, please proceed

Once the risks are reviewed and accepted, the AI proceeds with the actual migration.

Once those risks have been accepted, based on the current branch,
please create a new upgrade branch, follow the instructions, using
only the referenced versions, including optional steps that match my solution,
and normalize all npm scripts to follow best‑practice colon notation.

• Create a new branch – This protects the main branch; if the upgrade fails I can simply delete the upgrade branch.
• Follow the official instructions step‑by‑step – The AI decides which optional steps are required for the specific solution.
• Normalize npm scripts – See the next section for details.

4. Follow best practice – normalizing npm scripts

The documentation recommends a specific naming convention for npm scripts. Here’s the relevant excerpt:

{
  "scripts": {
    "test-only": "heft run --only test --",
    "deploy": "heft dev-deploy",
    "start": "heft start --clean",
    "build-watch": "heft build --lite",
    "package-solution": "heft package"
  }
}

The prompt line

... normalize all npm scripts to follow best‑practice colon notation.

tells the AI to rename scripts that use hyphens (e.g., test-only) to a colon‑based format (e.g., test:only). This makes the scripts easier to read, group, and invoke (e.g., npm run test:only).

Complete AI Prompt

Copy the block below and paste it into your Copilot/ChatGPT session to run the same upgrade flow on any SPFx project:

You are an expert SharePoint Framework developer. Follow these steps to upgrade a project to SPFx 1.22 using Heft:

1. Read the official migration guide:
   https://learn.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/migrate-gulptoolchain-hefttoolchain

2. Perform a risk assessment of the current solution and write a detailed Markdown report that includes:
   - An inventory of the project’s dependencies, custom scripts, and configuration files.
   - Potential breaking changes (e.g., deprecated APIs, gulp tasks, custom webpack configs).
   - Any hidden documentation or scripts that could affect the upgrade.

3. Present the risk report to the user. Wait for the user to confirm that the risks are accepted.

4. Once accepted:
   - Create a new Git branch named `upgrade/spfx-1.22`.
   - Follow the migration guide step‑by‑step, using only the versions referenced in the guide.
   - For each optional step, decide whether it applies to the current project (based on the risk report) and include it if needed.
   - After the migration, update the `package.json` scripts:
     * Convert hyphenated script names to colon notation (e.g., `test-only` → `test:only`).
     * Ensure the scripts match the examples in the guide:
       - `"test:only": "heft run --only test --"`
       - `"deploy": "heft dev-deploy"`
       - `"start": "heft start --clean"`
       - `"build:watch": "heft build --lite"`
       - `"package:solution": "heft package"`

5. Run `npm install` and then `heft build` to verify the project builds successfully.

6. If any step fails, revert the changes on the upgrade branch, document the failure in the Markdown report, and stop.

Provide the final upgraded project structure, the updated `package.json`, and a short summary of what changed.

Conclusion

By combining a clear, step‑by‑step migration guide with AI‑driven risk assessment and script normalization, you can upgrade SPFx projects to 1.22 and Heft safely and reproducibly. The single prompt above encapsulates the entire workflow, making it easy to apply the same process to any repository. Happy upgrading!

Script Naming Conventions

{
  "scripts": {
    "package-solution": "heft package-solution",
    "deploy-azure-storage": "heft deploy-azure-storage",
    "eject-webpack": "heft eject-webpack",
    "trust-dev-cert": "heft trust-dev-cert",
    "untrust-dev-cert": "heft untrust-dev-cert"
  }
}

The dashes in the script names work, but they follow an uncommon pattern and can become hard to read as the list grows. A more common (and often best‑practice) approach is to use colon notation, which groups similar commands together.

{
  "scripts": {
    "build": "heft build --clean",
    "build:watch": "heft build --lite",
    "build:prod": "heft build --production",

    "devcert:trust": "heft trust-dev-cert",
    "devcert:untrust": "heft untrust-dev-cert",

    "start": "npm run build:watch",

    "test": "heft test",
    "test:only": "heft run --only test --"

    // ...
  }
}

With this transformation, it’s easier to group related tasks (e.g., all test commands). You can also add custom commands—such as a special linter (stylelint)—or DevOps tasks. Overall, the scripts are better organized into groups for build, devcert, test, deploy, etc.

Manual Changes During the Upgrade

Some manual adjustments are required to reorganize the scripts after the upgrade.

Perform an Acceptance Test

Before accepting the upgrade, run a final acceptance test to ensure everything works. Multiple things can go wrong: incomplete documentation, hidden issues after the upgrade, etc.

As a final acceptance run, execute the build command to check for issues.
If issues are found, provide fact‑based solutions.

If everything succeeds, congratulations—you have an upgraded solution. If not, iterate and fix the problems. Emphasizing “based on facts” keeps the AI from making unfounded changes and encourages evidence‑based fixes.

Documentation

The final step is to create proper documentation of everything you did. This serves as a reference and eliminates surprises if something isn’t working as expected.

Provide a detailed summary of the applied configuration changes.

In addition to the summary, recommend updates to the documentation
based on issues encountered during the upgrade.

Also, make a recommendation for the Microsoft upgrade guide.

This step is crucial because it clearly outlines what was wrong (if anything) and what has been fixed. It’s optional only if you encountered minor issues with Microsoft’s documentation.

The Prompt

Below is the complete prompt to upgrade a SharePoint Framework (SPFx) solution to SPFx 1.22. No tools or magic—just a clear process for describing the required updates.

Follow these instructions to upgrade to the latest SPFx version using heft:
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/migrate-gulptoolchain-hefttoolchain

Before you start the migration, perform a risk assessment of the current solution and document it in a Markdown file.

Once those risks have been accepted, based on the current branch, please create a new upgrade branch, follow the instructions, using only the referenced versions, including optional steps that match my solution, and normalize all npm scripts to follow best‑practice colon notation.

As a final acceptance run, execute the build command to check for issues: when there are issues, please provide solutions based on facts.

Provide a detailed summary of the applied configuration changes.

In addition to the summary, recommend updates to the documentation based on issues encountered during the upgrade.

Also, make a recommendation for the Microsoft upgrade documentation.

The Upgrade Process

These instructions provide a reproducible upgrade plan with all precautions in place. The author recommends using Claude Sonnet 4 for the upgrade, as it yields more reliable results than Copilot.

The overall upgrade follows a 15‑step plan and allows user interaction. Runtime is typically a couple of minutes.

During the upgrade, an ESLint configuration issue not documented by Microsoft was fixed manually by comparing the SPFx package.json dependencies. The author had a minimal ESLint configuration; for the full Microsoft ESLint file, copy it from another boilerplate.

Verdict

Overall, the SPFx 1.22 upgrade process with AI worked almost flawlessly. The only real issue encountered was a small documentation gap in Microsoft’s official upgrade guide. The prompt‑driven approach was successfully tested with Claude Sonnet.

4 (via GitHub Copilot) – across multiple projects and SPFx solutions

For me, this AI‑assisted upgrade flow is absolutely worth using. Instead of spending hours on a manual SharePoint Framework upgrade, the entire SPFx with Heft migration can be completed in minutes.

Because the workflow builds in a safety net, I can decide at any point whether to keep or discard the upgrade branch without risking my main codebase.

What I appreciate most is that this method is reproducible and applies the same automated upgrade process to every SPFx project. Once everything is properly documented, upgrading to SPFx 1.22 with Heft becomes almost a no‑brainer.