Capacitor Plugin Upgrade v6 to v7#

Move a plugin library to Capacitor 7. Source of truth: https://capacitorjs.com/docs/updating/plugins/7-0

When to Use#

• Snapshot shows @capacitor/core 6.x and the plugin must work in Capacitor 7 apps.
• Plugin code still calls call.success(), call.error(), registerWebPlugin, Capacitor.platform, Capacitor.isNative, or uses BridgeFragment.
• Package.swift points capacitor-swift-pm at branch: "main".

Do not use:

• Upgrading an app -> capacitor-app-upgrade-v6-to-v7.
• Plugin on 5.x -> capacitor-plugin-upgrade-v5-to-v6 first; on 7.x -> capacitor-plugin-upgrade-v7-to-v8. Multi-hop -> capacitor-plugin-upgrades.
• Adding SPM from scratch -> capacitor-plugin-spm-support.

Live Project Snapshot#

Plugin and Capacitor package snapshot: !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=['package.name='+(pkg.name||''),'package.version='+(pkg.version||'')];for(const section of ['peerDependencies','dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}console.log(out.join('\n'))"

Example and native project paths: !find . -maxdepth 3 \( -path './example-app' -o -path './ios' -o -path './android' \)

References#

Preflight#

Procedure#

1. Confirm 6.x and a clean tree.

2. From the plugin root:

   shell

   npx @capacitor/plugin-migration-v6-to-v7@latest

   Review git diff.

3. package.json: dev deps @capacitor/cli, core, android, ios to ^7.0.0; peer @capacitor/core to >=7.0.0. Tooling per references/tooling.md (note the rollup.config.js -> rollup.config.mjs rename and the --plugin=prettier-plugin-java script flag).

4. Android per references/android.md: SDK defaults 23/35/35, AGP 8.7.2, Gradle 8.11.1, Java 21, Kotlin 1.9.25.

5. iOS per references/ios.md: podspec s.ios.deployment_target = '14.0', Package.swift .iOS(.v14), capacitor-swift-pm from: "7.0.0" instead of branch: "main".

6. Removed APIs - search and replace:

   • call.success(...) -> call.resolve(...); call.error(...) -> call.reject(...) (Java/Kotlin and Swift).
   • registerWebPlugin and other v2-era definitions are gone; use registerPlugin (see the Capacitor 3 plugin upgrade guide).
   • Capacitor.platform -> Capacitor.getPlatform(); Capacitor.isNative -> Capacitor.isNativePlatform().
   • Android BridgeFragment is removed. If the plugin presents a fragment through it, copy the needed logic into a plugin-owned Fragment class.

7. Upgrade the example app via capacitor-app-upgrade-v6-to-v7, bump the plugin major, note "Requires Capacitor 7".

Verification#

grep -n "\"@capacitor/\|rollup\|prettier\"" package.json
grep -rnE "\.success\(|\.error\(" android/src/main ios/ 2>/dev/null | grep -i call     # expect none
grep -rnE "registerWebPlugin|Capacitor\.platform\b|Capacitor\.isNative\b|BridgeFragment" src/ android/ ios/   # expect none
grep -n "deployment_target" *.podspec                       # '14.0'
grep -n "iOS(\|capacitor-swift-pm" Package.swift 2>/dev/null    # .v14, from: "7.0.0"
grep -n "VERSION_21\|gradle:8.7.2\|: 35\|: 23" android/build.gradle
npm run build
npm run verify        # if the repo has the template verify scripts

Run the example app on both platforms.

Error Handling#