capacitor-app-upgrade-v6-to-v7 ยท diff
git:20260501.ed3e92e to git:20261011.86834d4
86 added, 17 removed. Audit A to A.
---
name: capacitor-app-upgrade-v6-to-v7
- description: Guides the agent through upgrading a Capacitor app from v6 to v7. Use when the project is on Capacitor 6 and needs the v7 migration path. Do not use for other major versions, plugin-only upgrades, or non-Capacitor apps.
+ description: Upgrades a Capacitor app from v6 to v7 using `npx cap migrate` from `@capacitor/cli@latest-7`, then the manual checklist - Node 20+, Xcode 16+, iOS deployment target 14.0 (Xcode project and Podfile), Android Studio Ladybug with JDK 21, AGP 8.7.2, Gradle 8.11.1, minSdk 23, compile/target SDK 35, removed `bundledWebRuntime` and `cordova.staticPlugins` config, `navigation` in configChanges, and official plugin breaking changes (removed deprecated types like `AppUrlOpen`, `HapticsImpactStyle`, `DeviceBatteryInfo`; Device no longer returns disk sizes). Use when `@capacitor/core` is 6.x and the target is 7.x, or on errors like "Capacitor 7 requires JDK 21" or "Module 'X' has no exported member 'AppUrlOpen'". Do not use for other major versions, plugin library upgrades, or non-Capacitor apps.
allowed-tools:
- Bash(node -e *)
- - Bash(npm *)
- - Bash(npx cap *)
---
# Capacitor App Upgrade v6 to v7
- Upgrade a Capacitor app from version 6 to version 7.
+ Move a Capacitor 6 app to Capacitor 7. Source of truth: https://capacitorjs.com/docs/updating/7-0
- ## When to Use This Skill
+ ## When to Use
- - User says the app is on Capacitor 6 and must move to v7
- - User wants the exact v6 to v7 migration path
- - User needs v7-specific native and package updates
+ - `@capacitor/core` in the snapshot below is `6.x` and the user wants `7.x`.
+ - Build fails after bumping to 7 with JDK 21 / AGP 8.7 errors, iOS deployment target 13 errors, or TypeScript errors on removed deprecated plugin types.
+ - The user asks for the exact 6 -> 7 checklist.
+ Do not use:
+
+ - App on 5.x -> `capacitor-app-upgrade-v5-to-v6` first. On 7.x -> `capacitor-app-upgrade-v7-to-v8`. Multi-hop planning -> `capacitor-app-upgrades`.
+ - Plugin library upgrade -> `capacitor-plugin-upgrade-v6-to-v7`.
+ - CocoaPods to SPM -> `cocoapods-to-spm`.
+
## Live Project Snapshot
Current Capacitor packages from `package.json`:
!`node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"`
+ ## References
+
+ Only load a reference when its topic is in play.
+
+ | File | Load when |
+ | --- | --- |
+ | `references/android.md` | Editing `variables.gradle`, `build.gradle`, wrapper, manifest, or Kotlin by hand |
+ | `references/plugins.md` | The app uses official `@capacitor/*` plugins (App, Device, Haptics, Splash Screen, Status Bar, ...) |
+
+ ## Preflight
+
+ | Tool | Minimum for Capacitor 7 |
+ | --- | --- |
+ | Node.js | 20+ (latest LTS recommended) |
+ | Xcode | 16.0+ |
+ | iOS deployment target | 14.0 |
+ | Android Studio | Ladybug 2024.2.1+ (bundles JDK 21) |
+ | Java (Gradle JDK) | 21 |
+ | AGP / Gradle | 8.7.2 / 8.11.1 |
+ | Android SDK | minSdk 23, compileSdk 35, targetSdk 35 |
+
+ ```bash
+ node -v && xcodebuild -version && java -version
+ git status --short
+ grep -rn "bundledWebRuntime\|staticPlugins" capacitor.config.*
+ ```
+
## Procedure
- 1. Start from the injected package snapshot and confirm the current `@capacitor/core` version.
- 2. Update all `@capacitor/*` packages to the v7-compatible range.
- 3. Review the v6 to v7 migration notes before editing native files.
- 4. Run `npm install`.
- 5. Sync with `npx cap sync`.
- 6. Verify the iOS and Android builds.
+ 1. Confirm 6.x from the snapshot. Note: dropping minSdk to 23 and iOS to 14 removes support for older devices; tell the user.
+ 2. Run the automated migration:
+ ```bash
+ npm i -D @capacitor/cli@latest-7
+ npx cap migrate
+ ```
+
+ It bumps packages, raises the iOS deployment target and Podfile to 14.0, updates Gradle files and the wrapper, and runs `cap sync`. Finish every step it reports as skipped or failed.
+ 3. **Config** (`capacitor.config.*`):
+ - `bundledWebRuntime` is removed. `false` -> delete it. `true` -> the app must bundle `@capacitor/core` with a bundler (Vite, webpack, ...) instead of loading `capacitor.js`.
+ - `cordova.staticPlugins` is removed. Cordova plugins that need static linking must use a `podspec` tag with `use-framework` (cordova-ios 7+ does not support the `framework` tag).
+ 4. **iOS**: set **iOS Deployment Target = 14.0** on the Project and every Target in Build Settings, and `platform :ios, '14.0'` in `ios/App/Podfile`. For SPM apps, check `CapApp-SPM/Package.swift` platforms.
+ 5. **Android**: apply `references/android.md` (AGP 8.7.2, Gradle 8.11.1, google-services 4.4.2, Kotlin 1.9.25, optional `navigation` in `configChanges`).
+ 6. Update `@capacitor/*` plugins to `^7.0.0` and community plugins to their Capacitor 7 releases. Fix removed types per `references/plugins.md`.
+ 7. Telemetry is opt-out for new CLI users; it never runs in CI. Disable with `npx cap telemetry off` if the user wants.
+ 8. Run verification.
+
+ ## Traps
+
+ - JDK 21 is required: Capacitor 7 Android modules compile with Java 21 source/target, so a JDK 17 Gradle runtime fails with `invalid source release: 21`. Fix the Gradle JDK (IDE and CI), not the code.
+ - Community plugins still declaring `minSdkVersion 22` or iOS 13 compile, but plugins that declare `@capacitor/core` peer `^6` cause npm `ERESOLVE`. Upgrade or replace them; avoid `--legacy-peer-deps` unless the user accepts the risk.
+ - Device `getInfo()` no longer returns `diskFree`, `diskTotal`, `realDiskFree`, `realDiskTotal`. Remove the matching `PrivacyInfo.xcprivacy` disk-space entries only if no other code reads disk space.
+
+ ## Verification
+
+ ```bash
+ grep -rn "bundledWebRuntime\|staticPlugins" capacitor.config.* # expect none
+ grep -rn "IPHONEOS_DEPLOYMENT_TARGET" ios/App/App.xcodeproj/project.pbxproj | sort -u # 14.0
+ grep -n "platform :ios" ios/App/Podfile 2>/dev/null # '14.0'
+ grep -n "gradle:8.7.2\|google-services:4.4.2" android/build.gradle
+ grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties # gradle-8.11.1
+ grep -n "SdkVersion" android/variables.gradle # 23 / 35 / 35
+ grep -rnE "AppUrlOpen|AppRestoredResult|DeviceBatteryInfo|DeviceLanguageCodeResult|Haptics(Impact|Notification)(Options|Type|Style)|SplashScreen(Show|Hide)Options|diskFree|diskTotal" src/
+ npx cap sync
+ cd android && ./gradlew assembleDebug
+ ```
+
+ Then build iOS in Xcode 16+ and launch both platforms.
+
## Error Handling
- - If the automated migration misses a package, update it manually before syncing again.
- - If iOS fails, check the deployment target and Xcode compatibility for Capacitor 7.
- - If Android fails, check the Gradle and Java requirements for Capacitor 7.
+ | Error | Fix |
+ | --- | --- |
+ | `Migrate can only be used on Capacitor 6, please use the CLI in Capacitor 6 to upgrade to 6 first` | Run `capacitor-app-upgrade-v5-to-v6` first. |
+ | `Capacitor 7 requires JDK 21 or higher. Some steps may fail.` / `invalid source release: 21` | Set Gradle JDK to 21 (Android Studio Ladybug bundles it) and in CI. |
+ | `Skipped updating deployment target` | Set iOS 14.0 manually in Xcode and Podfile (step 4). |
+ | `Unable to find "<text>" in <file>. Try updating it manually` | Apply the diff from `references/android.md`. |
+ | `Module '"@capacitor/app"' has no exported member 'AppUrlOpen'` (or similar) | Rename to the replacement type in `references/plugins.md`. |
+ | `ERESOLVE unable to resolve dependency tree` on `@capacitor/core` | A plugin still peers on v6; upgrade it to its v7 release. |