Ionic 8 to 9 Upgrade Checklist

Start from a reproducible Ionic 8 build

Commit the lockfile, native projects and current configuration. Record the exact installed versions, not just the ranges in package.json. Save a web-build result and native-build logs so a pre-existing failure does not become an upgrade finding.

npm ls @ionic/core @ionic/angular @ionic/react @ionic/vue
npm ls @capacitor/core @capacitor/cli @capacitor/android @capacitor/ios
npm run build

Use the equivalent commands for your package manager. These commands belong in your own trusted application; a build can execute project scripts.

If starting on Ionic 6, review 6 → 7 and 7 → 8 first. Old slides, virtual scroll and event handlers deserve their own migration pass. Do not interpret an 8 → 9 checklist as covering everything skipped since Ionic 6.

Choose the supported framework and runtime

The official breaking-change reference sets Ionic 9 support at Angular 18+, React 18/19, Vue 3.5+, and Capacitor 7+. Ionic 9 also raises the supported iOS browser/platform baseline to 16. Capacitor's deployment target alone is therefore insufficient to establish support for the combined app.

Choose a specific framework version and check its Node.js and TypeScript requirements. Ionic and Capacitor major numbers do not have to match. If your native target is Capacitor 8, use the separate migration sequence and Android requirements.

Review imports and routing before package changes

• Angular: standalone imports move from @ionic/angular/standalone to @ionic/angular; lazy imports move to @ionic/angular/lazy. IonicModule is deprecated but still works. Review CSS imports containing ~ and subpath resolution.
• React: Ionic 9 uses React Router 6. Audit Route, redirects, history calls and nested outlets rather than only updating router packages. Overlay-hook props now receive stricter types.
• Vue: use Vue Router 5 with Vue 3.5+. Identify navigation guards that still call next().
• Angular change detection: when also moving to Angular 21/22, review asynchronous state updates and Ionic lifecycle hooks. A framework migration can change re-rendering independently of Ionic.

These are selected changes from the Ionic 9 upgrade guide, not a complete replacement for it. A routing audit should include cold-start deep links, back navigation, tab history and modal dismissal on an actual device.

Find API and visual assumptions in the application

The breaking-change list includes input, picker, modal, nav, router outlet, searchbar, select and textarea changes. One concrete trap: ion-input autocorrect is now boolean; autocorrect="off" enables it rather than disabling it. Review bindings and test text entry with a real keyboard.

Search your templates and wrappers for affected components, then inspect event payloads, CSS shadow parts and overlay behavior. Record a migration item only when the changed API is actually used. A project that never uses a removed API does not need that rewrite.

rg 'autocorrect|ion-picker|ion-select|ion-modal|ion-input' src
rg '@ionic/angular/standalone|useIonModal|useIonPopover' src

Adjust src to your source directory. Text matches are an investigation list: they include comments and cannot establish behavior by themselves.

Separate plugin evidence from framework compatibility

Inventory official Capacitor packages, third-party plugins, Cordova implementations and their JavaScript wrappers. A wrapper's TypeScript build does not establish that its native implementation works. Check the exact plugin release against the chosen Capacitor major and each native platform using the plugin compatibility audit.

Review custom Android activities, manifests and Gradle dependencies; review iOS entitlements, lifecycle code and dependency-manager setup. Requirements depend on the chosen native runtime and plugins. Ionic's UI package update cannot perform this review for you.

Apply changes in reviewable steps

Pin the intended major instead of using an unqualified @latest. Make framework migrations, Ionic changes and native-runtime changes separate commits where practical. After each stage, inspect the package and lockfile diff before continuing.

Ionic provides npx @ionic/migrate --dry-run for an initial preview. Its normal migration writes files; review the proposed changes and manual remainder before running it on a clean branch. The tool does not eliminate project-specific testing. Official migration-tool behavior.

Validate the upgrade in layers

1. Resolve dependencies without suppressing peer conflicts; run type checks and the production web build.
2. Run Capacitor sync after producing the web assets; review native changes and build Android and iOS.
3. Exercise routes, overlays, form events, theme modes, safe areas and keyboard layout.
4. Test every retained native feature, permissions denied/granted, background/resume and an upgrade installation with existing data.
5. Record failures, unresolved checks, device/OS and exact package versions. Keep the previous release available for rollback.

A successful compiler run establishes only that build. Native customization, plugin callbacks and data retention still require inspection and runtime evidence. Use the broader upgrade-readiness checklist to track those remaining gates.