Capacitor App Upgrade V6 To V7

---
name: capacitor-app-upgrade-v6-to-v7
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 *)
---

# Capacitor App Upgrade v6 to v7

Move a Capacitor 6 app to Capacitor 7. Source of truth: https://capacitorjs.com/docs/updating/7-0

## When to Use

- `@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. 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

| 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. |