git:20260319.9192953 to git:20261011.86834d4
70 added, 15 removed. Audit A to A.
---
name: capacitor-plugin-upgrade-v6-to-v7
- description: Guides the agent through upgrading a Capacitor plugin from v6 to v7. Use when the plugin targets Capacitor 6 and needs the v7 migration path. Do not use for app upgrades, other major versions, or non-Capacitor plugins.
+ description: Upgrades a Capacitor plugin library from v6 to v7 using `npx @capacitor/plugin-migration-v6-to-v7@latest`, then the manual checklist - dev deps `^7.0.0` and peer `@capacitor/core` `>=7.0.0`, tooling bumps (eslint, swiftlint, prettier 3 with prettier-plugin-java, rollup 4 with `rollup.config.mjs`, rimraf 6, docgen 0.3), minSdk 23 and compile/target SDK 35 defaults, AGP 8.7.2, Gradle 8.11.1, Java 21, Kotlin 1.9.25, iOS 14 in podspec and `Package.swift`, pinned `capacitor-swift-pm` `from: "7.0.0"`, plus removed APIs - `call.success()` / `call.error()` (use `resolve` / `reject`), `registerWebPlugin`, `Capacitor.platform` / `isNative`, Android `BridgeFragment`. Use when a plugin targets Capacitor 6 and must support 7. Do not use for app upgrades, other major versions, or non-Capacitor libraries.
allowed-tools:
- Bash(node -e *)
- Bash(find *)
---
# Capacitor Plugin Upgrade v6 to v7
- Upgrade a Capacitor plugin from version 6 to version 7.
+ Move a plugin library to Capacitor 7. Source of truth: https://capacitorjs.com/docs/updating/plugins/7-0
- ## When to Use This Skill
+ ## When to Use
- - User says the plugin targets Capacitor 6 and must move to v7
- - User wants the exact v6 to v7 migration path
- - User needs v7-specific native and package updates
+ - 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
+
+ | File | Load when |
+ | --- | --- |
+ | `references/android.md` | Applying Gradle, Java, or Kotlin changes by hand |
+ | `references/ios.md` | Raising the iOS target in podspec / `Package.swift` / old-structure Xcode project, pinning `capacitor-swift-pm` |
+ | `references/tooling.md` | Updating eslint, swiftlint, prettier, rollup, rimraf, docgen |
+
+ ## Preflight
+
+ | Tool | Minimum |
+ | --- | --- |
+ | Node.js | 20+ |
+ | Xcode | 16.0+ |
+ | iOS deployment target | 14.0 |
+ | Java | 21 |
+ | AGP / Gradle | 8.7.2 / 8.11.1 |
+ | Android SDK defaults | minSdk 23, compileSdk 35, targetSdk 35 |
+
## Procedure
- 1. Start from the injected snapshot and confirm the current Capacitor peer dependency range in `package.json`.
- 2. Update the peer dependency range to Capacitor 7.
- 3. Review the v6 to v7 migration notes before editing native files.
- 4. Update the example app if it exists.
- 5. Run `npm install`.
- 6. Sync and verify the example or test app.
+ 1. Confirm 6.x and a clean tree.
+ 2. From the plugin root:
+ ```bash
+ 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
+
+ ```bash
+ 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
- - If the example app breaks, fix the plugin API or native bridge before moving on.
- - If iOS fails, verify the deployment target for Capacitor 7.
- - If Android fails, verify the Gradle and Java requirements for Capacitor 7.
+ | Error | Fix |
+ | --- | --- |
+ | `cannot find symbol ... success(` / `error(` on `PluginCall` | Use `resolve` / `reject`. |
+ | `invalid source release: 21` | Gradle JDK must be 21. |
+ | SPM: target `requires minimum platform version` higher than the plugin declares | Set `platforms: [.iOS(.v14)]` in `Package.swift` and pin `capacitor-swift-pm` `from: "7.0.0"`. |
+ | Rollup 4 fails to load `rollup.config.js` (ESM config) | Rename to `rollup.config.mjs` and update the `build` script. |
+ | `Property 'platform' does not exist on type 'CapacitorGlobal'` | Use `Capacitor.getPlatform()`. |