git:20260319.9192953 to git:20261011.86834d4
81 added, 15 removed. Audit A to A.
---
name: capacitor-plugin-upgrade-v7-to-v8
- description: Guides the agent through upgrading a Capacitor plugin from v7 to v8. Use when the plugin targets Capacitor 7 and needs the v8 migration path. Do not use for app upgrades, other major versions, or non-Capacitor plugins.
+ description: Upgrades a Capacitor plugin library from v7 to v8 using `npx @capacitor/plugin-migration-v7-to-v8@latest`, then the manual checklist - dev deps `^8.0.0` and peer `@capacitor/core` `>=8.0.0`, minSdk 24 and compile/target SDK 36 defaults, AndroidX dependency defaults, AGP 8.13.0, Gradle 8.14.3, Gradle `=` property assignment syntax, Java 21, Kotlin 2.2.20 (`kotlinOptions` to `compilerOptions`, no `kotlin-android-extensions`), google-services 4.4.4, iOS 15 in podspec and `Package.swift`, `capacitor-swift-pm` `from: "8.0.0"`, and the renamed `capacitor_bridge_layout_main` resource. Use when a plugin targets Capacitor 7 and must support 8, or on Kotlin 2 / Gradle space-assignment errors. Points to the v8-to-v9 next step. Do not use for app upgrades, other major versions, or non-Capacitor libraries.
allowed-tools:
- Bash(node -e *)
- Bash(find *)
---
# Capacitor Plugin Upgrade v7 to v8
- Upgrade a Capacitor plugin from version 7 to version 8.
+ Move a plugin library to Capacitor 8. Source of truth: https://capacitorjs.com/docs/updating/plugins/8-0
- ## When to Use This Skill
+ ## When to Use
- - User says the plugin targets Capacitor 7 and must move to v8
- - User wants the exact v7 to v8 migration path
- - User needs v8-specific native and package updates
+ - Snapshot shows `@capacitor/core` 7.x and the plugin must work in Capacitor 8 apps.
+ - Building the plugin against Kotlin 2.2 fails on `kotlinOptions` or `kotlin-android-extensions`.
+ - Gradle warns `Properties should be assigned using the 'propName = value' syntax`.
+ Do not use:
+
+ - Upgrading an app -> `capacitor-app-upgrade-v7-to-v8`.
+ - Plugin on 6.x -> `capacitor-plugin-upgrade-v6-to-v7` first. Multi-hop -> `capacitor-plugin-upgrades`.
+ - Plugin already on 8.x -> `capacitor-plugin-upgrade-v8-to-v9`.
+ - Adding SPM -> `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` | Dependency defaults, SDK, AGP/Gradle, `=` syntax, Java 21, Kotlin 2.2 changes |
+ | `references/ios.md` | iOS 15 in podspec / `Package.swift` / old-structure project, `capacitor-swift-pm` 8 |
+
+ ## Preflight
+
+ | Tool | Minimum |
+ | --- | --- |
+ | Node.js | 22+ |
+ | Xcode | 26.0+ |
+ | iOS deployment target | 15.0 |
+ | Java | 21 recommended (17+ supported by AGP 8.13) |
+ | AGP / Gradle | 8.13.0 / 8.14.3 |
+ | Android SDK defaults | minSdk 24, compileSdk 36, targetSdk 36 |
+ | Kotlin (if used) | 2.2.20 |
+
## 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 8.
- 3. Review the v7 to v8 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 7.x and a clean tree.
+ 2. From the plugin root:
+ ```bash
+ npx @capacitor/plugin-migration-v7-to-v8@latest
+ ```
+
+ Review `git diff`.
+ 3. **package.json**: dev deps `@capacitor/cli`, `core`, `android`, `ios` to `^8.0.0`; peer `@capacitor/core` to `>=8.0.0`.
+ 4. **Android** per `references/android.md`:
+ - Only add/update the `ext {}` dependency defaults the plugin actually uses.
+ - SDK defaults 24/36/36, AGP 8.13.0, Gradle 8.14.3, google-services 4.4.4 (if used).
+ - Convert every property assignment to `=` (`namespace = ...`, `compileSdk = ...`, `url = ...`, `abortOnError = ...`). Method calls such as `mavenCentral()` stay unchanged.
+ - Java 21 `compileOptions`.
+ - Kotlin plugins: `kotlin_version` 2.2.20, replace `kotlinOptions {}` with `kotlin { compilerOptions { jvmTarget = JvmTarget.JVM_21 } }`, drop `kotlin-android-extensions` (use `kotlin-parcelize` / view binding).
+ - Code referencing `R.layout.bridge_layout_main` must use `capacitor_bridge_layout_main`.
+ 5. **iOS** per `references/ios.md`: podspec `15.0`, `Package.swift` `.iOS(.v15)`, `capacitor-swift-pm` `from: "8.0.0"`. If the plugin posted `.capacitorViewDidAppear` / `.capacitorViewWillTransition` itself, remove that code; Capacitor 8 emits them.
+ 6. Upgrade the example app via `capacitor-app-upgrade-v7-to-v8`, bump the plugin major, note "Requires Capacitor 8".
+
+ ## After 8.x: next steps
+
+ - Capacitor 8.5 apps adopt the iOS UIScene lifecycle (required by Xcode 27). Plugins that hook AppDelegate methods (`application(_:open:options:)`, `continue userActivity`, `applicationDidBecomeActive`, ...) or use `UIApplication.shared.windows` / `keyWindow` must handle scene-based apps; see `capacitor-uiscene-migration`.
+ - Then `capacitor-plugin-upgrade-v8-to-v9` (Capacitor 9 is on `next`, not GA).
+
+ ## Verification
+
+ ```bash
+ grep -n "\"@capacitor/" package.json # ^8.0.0 / >=8.0.0
+ grep -nE "^\s*(namespace|compileSdk|url|abortOnError|minSdkVersion|targetSdkVersion) [^=]" android/build.gradle # expect none
+ grep -n "kotlinOptions\|kotlin-android-extensions" android/build.gradle # expect none
+ grep -n "VERSION_21\|gradle:8.13.0" android/build.gradle
+ grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties # gradle-8.14.3
+ grep -rn "bridge_layout_main" android/src | grep -v capacitor_bridge # expect none
+ grep -n "deployment_target" *.podspec # '15.0'
+ grep -n "iOS(\|capacitor-swift-pm" Package.swift 2>/dev/null # .v15, from: "8.0.0"
+ npm run build
+ npm run verify # if the repo has the template verify scripts
+ cd android && ./gradlew build --warning-mode all
+ ```
+
+ 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 8.
- - If Android fails, verify the Gradle and Java requirements for Capacitor 8.
+ | Error | Fix |
+ | --- | --- |
+ | `Properties should be assigned using the 'propName = value' syntax` | Add `=` to the property assignment. |
+ | Kotlin: `kotlinOptions` deprecated / error under Kotlin 2.2 | Use `kotlin { compilerOptions { jvmTarget = JvmTarget.JVM_21 } }` with `import org.jetbrains.kotlin.gradle.dsl.JvmTarget`. |
+ | `Plugin [id: 'kotlin-android-extensions'] was not found` | Remove it; use `kotlin-parcelize` and view binding. |
+ | `Inconsistent JVM-target compatibility detected for tasks` | Make Java `compileOptions` and Kotlin `jvmTarget` the same version (21). |
+ | `cannot find symbol` on `R.layout.bridge_layout_main` | Use `capacitor_bridge_layout_main`. |
+ | SPM resolution picks Capacitor 7 | Set `capacitor-swift-pm` `from: "8.0.0"`. |