Capacitor Plugin Upgrades

Capacitor Plugin Upgrade

Upgrade a Capacitor plugin to a newer major version (4→5, 5→6, 6→7, or 7→8).

Prerequisites

| Target Version | Node.js | | -------------- | ------- | | 5 | 16+ | | 6 | 18+ | | 7 | 20+ | | 8 | 22+ |

The project must be a Capacitor plugin (not an app project).

Procedures

Step 1: Detect Current Version

Read @capacitor/core version from package.json (devDependencies or peerDependencies). Determine the current major version.

Ask the user for the target version. Default to the latest (8) if not specified.

Step 2: Execute Upgrade

For each major version jump between the current and target version, apply the corresponding upgrade guide sequentially:

| Current → Target | Reference | | ---------------- | ------------------------------------ | | 4 → 5 | references/upgrade-v4-to-v5.md | | 5 → 6 | references/upgrade-v5-to-v6.md | | 6 → 7 | references/upgrade-v6-to-v7.md | | 7 → 8 | references/upgrade-v7-to-v8.md |

For multi-version jumps (e.g., 5 → 8), apply each upgrade in order:

1. Read and apply references/upgrade-v5-to-v6.md
2. Run npm install && npx cap sync, build, and verify the plugin's test/example app
3. Read and apply references/upgrade-v6-to-v7.md
4. Run npm install && npx cap sync, build, and verify the plugin's test/example app
5. Read and apply references/upgrade-v7-to-v8.md
6. Run npm install && npx cap sync, build, and verify the plugin's test/example app

Do not skip intermediate versions.

Step 3: Final Verification

After completing all upgrade steps:

npm install
npx cap sync

Build the plugin's test/example app on both platforms to verify.

Error Handling

• If automated upgrade tools fail, check the terminal output for which steps failed and apply those manually using the steps in the corresponding reference file.
• If Android build fails after upgrade, run Tools > AGP Upgrade Assistant in Android Studio.
• If iOS build fails, verify the deployment target matches the target version requirements in the reference file.
• If Gradle property syntax warnings appear (v8+), search all .gradle files for property assignments without = and update them.
• If a multi-version upgrade fails mid-way, fix the current version step before proceeding to the next.

Related Skills

• capacitor-app-upgrades — If the app project itself also needs upgrading, use this skill.
• capacitor-plugin-spm-support — After upgrading a plugin to Capacitor 6+, use this skill to add Swift Package Manager support.
• capacitor-plugin-development — For creating new Capacitor plugins from scratch, including scaffolding, native implementation, and publishing.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: capawesome-team
• Source: capawesome-team/skills
• License: MIT

Install and usage instructions live in the source repository linked above.