Upgrading and deploying a SharePoint Framework solution safely requires more than changing a package version. This checklist gives developers and SharePoint administrators a repeatable way to verify SPFx, Node.js, TypeScript, dependencies, APIs, permissions, deployment controls, and rollback options before a change reaches production.
Overview
SharePoint Framework upgrades can affect the local toolchain, project dependencies, build output, authentication flow, Microsoft Graph or SharePoint API calls, and the way an application is packaged for an app catalog. A solution may compile successfully on a developer workstation and still fail during deployment because the build agent uses a different Node.js version, a package resolves differently, or a permission request has not been approved in the target tenant.
The safest approach is to treat every upgrade as a controlled change. Record the current state, confirm compatibility against Microsoft’s current SharePoint Framework guidance, test the solution in an environment that resembles production, and define a rollback path before deployment begins. This process applies to a routine dependency update as well as a larger SPFx upgrade, CI/CD change, or app-catalog migration.
Use this article as a recurring worksheet rather than a one-time tutorial. The exact supported versions and tool requirements can change, so the compatibility section should always be checked against current Microsoft documentation before a team commits to an upgrade.
What to track
1. Record the compatibility baseline
Start with a small version-compatibility table for every solution. Do not fill it with assumptions or copy values from an older project. Verify each value from the relevant Microsoft compatibility matrix or release guidance.
| Item | Current project value | Target value | Verification point |
|---|---|---|---|
| SPFx version | Recorded from the project configuration | Planned framework version | Microsoft compatibility guidance |
| Node.js | Local and CI versions | Required or supported runtime | SPFx toolchain requirements |
| TypeScript | Package and compiler settings | Version supported by the target SPFx release | Framework and project documentation |
| Package manager | npm, pnpm, or another approved tool | Standard used by the team | Lockfile and CI configuration |
| Build tools | Gulp, Heft, or project-specific commands | Target command set | Build and deployment pipeline |
| Browser and client assumptions | Supported user scenarios | Validated target scenarios | Application test plan |
Keep the table in the repository or change record. The important detail is not only the target version but also the environment that produced the current production package. That comparison often reveals drift between a developer laptop, a build agent, and the deployment operator’s workstation.
2. Audit packages and lockfiles
Review package.json, the lockfile, project configuration files, and any custom build scripts. Separate direct dependencies from transitive dependencies so the team knows which packages it intentionally owns and which arrive through another package. Look for duplicate versions of common libraries, deprecated packages, packages with broad version ranges, and dependencies that are used only by a development task.
Before changing packages, create a clean branch and preserve the last known-good lockfile. Install from that lockfile in a clean workspace, run the existing build, and save the result. After the upgrade, repeat the same process. This makes it easier to distinguish a framework change from an installation or environment problem.
3. Review APIs and permissions
List every external dependency used by the solution, including SharePoint REST, Microsoft Graph, third-party services, custom APIs, and environment-specific endpoints. For each one, record the operation, authentication method, requested permission, administrator approval status, and test account used.
An upgrade is a useful point to remove permissions the solution no longer needs. It is also a good time to test the least-privileged user journey, not only the administrator experience. Confirm that the application behaves predictably when a request fails, a token cannot be acquired, a user lacks access to a site, or an external service is unavailable.
Permission design should align with the wider SharePoint site provisioning and ownership process. Clear ownership helps ensure that API consent, app-catalog approval, and operational support do not depend on one developer.
4. Check configuration and content assumptions
Compare environment-specific settings such as site URLs, list and library names, tenant identifiers, feature flags, service endpoints, and telemetry destinations. Avoid embedding production values in source code. Use the configuration approach supported by the team’s deployment process, and document which values must be supplied at build time or deployment time.
Also test the data structures the web part or extension expects. Changes to column internal names, content types, permissions, views, or list thresholds can appear to be code failures when the real issue is an environment mismatch. A review of SharePoint document library metadata, folders, views, and content types can help identify these dependencies.
Cadence and checkpoints
Use a consistent sequence for every upgrade. The following checkpoints work for a scheduled framework update, a dependency refresh, or a pipeline change.
- Plan: define the reason for the change, affected solutions, target environment, owner, test scope, and proposed deployment window.
- Baseline: capture the production package, source revision, framework and runtime versions, lockfile, configuration values, API permissions, and current monitoring signals.
- Upgrade in isolation: create a branch, update one logical group of dependencies at a time, and avoid combining unrelated refactoring with the framework change.
- Install cleanly: remove generated output, install from the intended lockfile, and run the same commands used by the build pipeline.
- Test locally: verify rendering, properties, editing experiences, navigation, forms, file operations, error states, and responsive behavior.
- Build in CI: use a pinned and documented toolchain where practical. Treat warnings as review items rather than assuming a successful build means the change is safe.
- Deploy to a nonproduction environment: install the package through the same app-catalog or release path planned for production.
- Run acceptance tests: test representative sites, users, permissions, browsers, data volumes, and connected services.
- Release progressively: begin with a limited audience or low-risk site when the operating model allows it, then expand after reviewing results.
- Record the outcome: document the deployed package, approvals, test evidence, known issues, and the next review date.
For CI/CD teams, the pipeline should fail clearly when the Node.js runtime, package manager, lockfile, or required environment variable does not match the approved baseline. A deployment log should identify the source revision and package artifact so an operator can connect a production issue to a specific change.
How to interpret changes
Not every difference requires a rollback. Classify findings by impact and reversibility.
- Tooling-only change: the solution behaves the same, but build warnings or installation steps changed. Fix the documentation and pipeline before the next release.
- Functional change: a command, API call, property pane, or user flow behaves differently. Hold the release until the behavior is understood and tested.
- Permission change: the solution requests new consent or loses access to a required resource. Stop and review the permission design and approval path.
- Environment change: the package works in one site or tenant context but fails in another. Compare configuration, site structure, permissions, and service availability before changing code.
- Production regression: users cannot complete a critical task, errors are widespread, or data integrity may be affected. Use the rollback plan while investigation continues.
A simple rollback decision tree is useful:
- Is the issue caused by the new package or a separate service or configuration change?
- Can the affected audience be isolated while the team investigates?
- Is the previous package available, tested, and deployable through the same route?
- Would rollback restore the user experience without creating a known security or data problem?
- After rollback, what evidence must be retained before attempting another release?
Rollback is not a substitute for testing. It is a control for limiting impact. Keep the previous package, source revision, configuration notes, and deployment instructions available before starting the release. If the solution changes stored data or performs irreversible operations, document those risks separately because reverting the front-end package may not reverse the data change.
When to revisit
Review this checklist monthly or quarterly for active solutions, with a deeper review before each planned upgrade. Revisit it immediately when Microsoft publishes new SharePoint Framework or developer-tool compatibility guidance, when the team changes Node.js or TypeScript, when a package manager or lockfile changes, or when the CI/CD platform is updated.
Use additional checkpoints after a security advisory, a significant browser or client change, a new Microsoft Graph or SharePoint API dependency, an app-catalog permission request, a tenant migration, or a production rollback. A solution that has not changed may still need review if its runtime, connected service, permissions, or hosting process has changed.
Before closing each review, assign an owner and record four outcomes: the approved compatibility baseline, the dependency exceptions, the latest successful test date, and the location of the rollback artifact. If any of these is missing, the next deployment should be treated as a readiness task rather than a routine release.
Finally, keep the checklist alongside the project’s source and deployment documentation. Teams responsible for broader SharePoint migration and cutover work can use the same discipline: establish a baseline, test the target environment, confirm permissions, define rollback limits, and record what changed. That makes SPFx deployment a repeatable operational process instead of a last-minute build exercise.
