capacitor-plugin-upgrade-v6-to-v7

Files (5)

• SKILL.md
• metadata.json
• android.md · references/
• ios.md · references/
• tooling.md · references/

SKILL.md (first lines)

# 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

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

| 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()`. |

From Cap-go/capgo-skills, MIT.

More from Cap-go/capgo-skills