Guides the agent through upgrading a Capacitor plugin from v4 to v5. Use when the plugin targets Capacitor 4 and needs the v5 migration path. Do not use for app upgrades, other major versions, or non-Capacitor plugins.

Capacitor Plugin Upgrade v4 to v5 Move a plugin library to Capacitor 5. Source of truth: https://capacitorjs.com/docs/updating/plugins/5 0 When to Use Snapshot shows @capacitor/core 4.x in peer/dev deps and the plugin must work in Capacitor 5 apps. A Capacitor 5 app fails building this plugin with Namespace not specified or Java 17 errors. The plugin manually conforms to CAPBridgedPlugin or calls getObject() / getArray() . Do not use: Upgrading an app capacitor app upgrade v4 to v5 . Plugin already on 5 capacitor plugin upgrade v5 to v6 . Multi hop capacitor plugin upgrades . 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, manifest, Java or Kotlin changes by hand Preflight Tool Minimum Node.js 16+ Xcode 14.1+ Java 17 (AGP 8) AGP / Gradle 8.0.0 / 8.0.2 Android SDK defaults compileSdk 33, targetSdk 33, minSdk 22 iOS deployment target 13.0 (unchanged) Procedure 1. Confirm the plugin is on 4.x from the snapshot and the tree is clean ( git status ). 2. From the plugin root run: It edits package.json , android/build.gradle , the wrapper, gradle.properties , and the manifest. Review git diff . 3. Finish manually anything not applied ( references/android.md ): @capacitor/cli , core , android , ios dev deps to latest 5 ; peer @capacitor/core to ^5.0.0 . SDK defaults 33, AGP 8.0.0, Gradle 8.0.2, namespace in android {} and no package= in the manifest, Java 17, Jetifier removed, Kotlin 1.8.20 with kotlin stdlib . 4. iOS code : if the plugin conforms to CAPBridgedPlugin manually (no CAP PLUGIN macro), move requirements to instance level, rename pluginId to identifier , type pluginMethods as [CAPPluginMethod] , and drop getMethod( :) . Macro based plugins need no change. 5. Android code : call.getObject(key) and call.getArray(key) can now return null . Add null checks and call.reject(...) with a clear message when required. 6. Update the example app (if present) to Capacitor 5 via capacitor app upgrade v4 to v5 . 7. Bump the plugin major version and note "Requires Capacitor 5" in the changelog/README. Verification Run the example app on both platforms and exercise every method. Error Handling Error Fix Namespace not specified Add namespace "<package " to android {} in the plugin build.gradle . Android Gradle plugin requires Java 17 to run Switch the Gradle JDK to 17. NullPointerException from getObject / getArray Add null checks (step 5). Swift: type does not conform to protocol CAPBridgedPlugin Use instance level identifier , jsName , pluginMethods , or switch to the macro. Duplicate class ... kotlin stdlib jdk8 Replace kotlin stdlib jdk7/jdk8 with kotlin stdlib .

capacitor-plugin-upgrade-v4-to-v5