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.

Preflight

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:

   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

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