Capacitor 6 to 8 Migration Checklist

Capture the native baseline first

Record core, CLI, Android, iOS and plugin versions from the installed tree and lockfile. Save a clean web build, Android build and iOS build before editing. Commit native source, build settings and dependency locks; keep signing material outside the repository.

npm ls @capacitor/core @capacitor/cli @capacitor/android @capacitor/ios
npx cap ls
node --version
java -version
cd android
./gradlew --version

Use a locally installed CLI and run these only in your trusted application. java -version alone does not prove Android Studio or CI uses the same JVM; the Gradle version output is the important comparison.

List any edits to MainActivity, AppDelegate, manifests, Gradle files, Xcode targets and plugin forks. Native directories are application source, not disposable build output.

Stage one: migrate 6 → 7 and establish a checkpoint

The official 7 migration guide specifies Node 20+, Xcode 16+, iOS 14, Android Studio Ladybug 2024.2.1+, JDK 21, min SDK 23 and compile/target SDK 35. Its migration pairing is AGP 8.7.2 and Gradle 8.11.1.

npm install -D @capacitor/cli@7
npx cap migrate

Review the migration output and diff. Confirm core and installed platform packages all moved to major 7; do not assume the CLI fixed every plugin or native customization. Select each plugin's supported release independently.

Capacitor 7 removes bundledWebRuntime and cordova.staticPlugins. If bundled runtime was enabled, review how core gets bundled. Audit removed plugin APIs where used, including Device disk fields and renamed App listener types. The official guide also documents CLI telemetry preferences; assess them separately from your app's own privacy behavior.

Build, sync and test this stage before proceeding. For an app already on 7, use this as a baseline audit rather than replaying the 6 → 7 migration.

Stage two: migrate 7 → 8 with explicit targets

npm install -D @capacitor/cli@8
npx cap migrate

Confirm major 8 across core, CLI and the installed native platforms. Keep exact resolved versions in the lockfile. Review the 8 migration guide: Node 22+, Xcode 26+, iOS deployment target 15, Android Studio Otter 2025.2.1+, min SDK 24, compile/target SDK 36, AGP 8.13.0 and Gradle 8.14.3. See the Android toolchain explanation for Java and build-tools distinctions.

Inspect configuration and custom code: edge-to-edge margin handling moves away from android.adjustMarginsForEdgeToEdge; references to bridge_layout_main.xml need review. If you extended the iOS bridge to emit lifecycle notifications, check for duplicated behavior. Use the documented change list against your actual usage rather than copying every example.

Keep the iOS dependency manager deliberate

Update deployment targets for the project and every app target. For an existing CocoaPods project, align the Podfile platform with iOS 15 and inspect the resolved pod dependencies. Do not convert to Swift Package Manager simply because a new Capacitor 8 project defaults to it. Recreating ios/ can change dependency-manager choice and lose customization. Capacitor CLI change.

Check whether every retained plugin supports your dependency manager; Ionic's SPM guidance distinguishes official plugins from third-party and Cordova support. A dependency-manager migration needs its own checkpoint.

Current 8.x caveat: Capacitor 8.5 introduced an iOS scene-lifecycle migration for Xcode 27. If choosing 8.5+ or Xcode 27, also review that minor-version guide. An 8.0 checklist cannot cover later native changes automatically.

Audit plugins across both major transitions

For each native feature, record the package release, Capacitor peer range, platform constraints, changed methods and test owner. Third-party plugin major numbers need not equal Capacitor's. Broad or absent peer ranges leave uncertainty; they do not prove compatibility.

Use the plugin evidence worksheet and Cordova review. Review native library versions as well as the JavaScript interface. A transitive Android library may raise the minimum SDK; a pod may raise the iOS target.

Build, sync, inspect, then build natively

npm run build
npx cap sync android
npx cap sync ios
cd android
./gradlew assembleDebug

Run from the application root until the final cd. Verify webDir points to the generated web assets. Inspect the native diff after sync. For iOS, open the project appropriate to its dependency manager and build the selected simulator target; a simulator build does not validate device signing or hardware features. The official workflow separates web assets, native synchronization and native builds.

Use the first failure to choose the next investigation

Dependency or peer conflict

Compare the offending package's declared range with the selected core/framework version. Resolve the mismatch; bypassing it changes installation behavior, not native support.

Gradle JVM or bytecode error

Compare the JVM used by the wrapper, Studio and CI; then inspect Java/Kotlin compiler targets. Do not randomly lower targets to silence the first message.

AAR metadata, manifest or duplicate-class error

Trace the library back to a plugin or native customization. Check SDK constraints, manifest contributions and duplicate dependencies.

Pod or Swift package resolution error

Check deployment targets, selected package manager and the exact native dependency release before changing unrelated app code.

Sync succeeded; plugin fails at runtime

Confirm native registration, permission configuration, platform support and the actual call path. A web fallback can hide a missing native implementation.

Keep failures and unresolved tests in the readiness checklist. Acceptance should include a device upgrade from an existing installation, not only a fresh debug launch.