SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscapacitor-app-upgrade-v6-to-v7

capacitor-app-upgrade-v6-to-v7

Deployment & operations

View repository

Updated 10-13 22:01

About this skill

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

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.