Ionic Upgrade Readiness Checklist

1. Establish a baseline and rollback point

• Identify Ionic integration, Angular/React/Vue, router, TypeScript, Node, package manager, Capacitor/Cordova and exact installed versions.
• Commit or preserve current work, lockfiles and native application source on a dedicated branch. Tag or record the last working commit.
• Build the existing app first. Save web and native logs; identify pre-existing failures.
• Record CI images, local IDE/JDK/Xcode versions and required build configuration. Keep credentials and signing files out of Git.
• Define rollback: which app build can be restored, what stored-data changes are reversible, and who decides to stop.

git status --short
node --version
npm ls --depth=0
npm run build

Use your package manager's equivalents and your trusted app's scripts. If there is no reproducible baseline, fix that uncertainty before attributing failures to an upgrade.

2. Choose a target stack, not just an Ionic number

• Select exact target majors/releases for the UI, framework, router and native runtime.
• Check the framework's Node/TypeScript support table and Ionic integration requirements.
• Read each intervening major's migration guide. For Ionic 6 → 8 or 9, include 6 → 7, 7 → 8, then 8 → 9 where applicable.
• Separate UI, framework and native work where possible; define a build checkpoint after each stage.
• Document supported browsers, devices and OS versions for the combined stack. One package's minimum cannot stand in for the whole application.

Use Angular's version table where applicable and the chosen Ionic/Capacitor migration guides. A range that satisfies npm is only one constraint.

3. Resolve dependency and plugin uncertainty

• Inventory direct/transitive dependencies, local packages, Git dependencies and forks. Record why each native plugin is present.
• Check exact-release peer dependencies, engines, changelogs and platform constraints.
• Separate wrappers from native implementations; flag packages with no credible target-version evidence.
• Classify each platform using the plugin evidence checklist; assign owners to unknown and manual-review items.
• For legacy plugins, decide retain, replace, remove or manually test with the Cordova migration review.
• Resolve peer conflicts deliberately. Do not label a forced install as compatibility validation.

Keep the resolved lockfile after an intentional upgrade. npm ci is a clean reproducibility check for npm projects with a matching lockfile; it is not the command that chooses new versions.

4. Review Android and iOS before editing

Android

• Compare JDK, Gradle, AGP, compile/target/min SDK and plugin-native libraries with the selected runtime.
• Inspect custom activities, manifest entries, build variants, repositories, permissions and CI toolchains.
• Plan device/layout tests for behavior changes introduced by the target SDK. For Capacitor 8, start with the documented Android requirements.

iOS

• Review Xcode, project and target deployment settings, CocoaPods/SPM resolution and plugin support.
• Inventory entitlements, usage descriptions, privacy manifests, app extensions and lifecycle customization.
• Keep dependency-manager migration separate where feasible. Check minor-release native changes as well as major guides.
• Distinguish simulator compilation from device signing, distribution and hardware testing.

For a Capacitor 6 baseline targeting 8, follow the two-stage native migration. Do not regenerate native directories to avoid understanding customization.

5. Map APIs and configuration to actual usage

• Find removed/renamed Ionic APIs, event handlers, routing imports and CSS customizations used by the app.
• Review framework migrations, change detection and build configuration separately from Ionic component changes.
• Inspect Capacitor config, web output directory, plugin config and environment-specific differences.
• Write a concrete action for each match: file/component, documented change, replacement and verification step.
• Label text-search matches as candidates until inspected. Comments and unreachable code do not prove runtime impact.

The official breaking-change reference is the starting evidence. Application usage determines the actual work.

6. Validate dependency, web, sync and native stages

1. Apply a scoped migration and inspect the package/lockfile diff.
2. Run a clean install with the intended package manager and lockfile.
3. Run type checks, application tests and the production web build.
4. Confirm generated assets match Capacitor's webDir; run npx cap sync for the installed platforms.
5. Inspect native changes, dependency resolution and skipped-plugin warnings.
6. Build Android and iOS using the chosen toolchains. Save exact versions and the first failing error if blocked.

The Capacitor development workflow makes web build, sync and native build separate stages. A sync result cannot replace either build.

7. Test the real upgrade installation

• Test a fresh launch and an upgrade from the existing installed release with representative stored data.
• Exercise authentication, routing, deep links, overlays, input/keyboard, permissions and every retained plugin feature.
• Test denied permissions, failed network requests, background/resume and cancellation paths.
• Check minimum supported and current OS versions; record device/platform details.
• Verify stored data, file paths and identifiers after plugin replacements. Define a recovery path if the migration fails.

Mark untested behavior as untested. “Build passed” is useful evidence, but it does not imply that persistence, background tasks or hardware integrations work.

8. Close the plan with evidence and remaining decisions

Keep a small migration ledger: detected issue, evidence, affected feature, required action, owner, verification and remaining uncertainty. A blocked feature needs a replacement decision or an explicit release decision; an unknown feature needs investigation or testing.

A useful readiness decision states what is verified, what is still unknown and what must happen before release. It should not turn a count of warnings into a guaranteed-success score.