Skip to content

How to Upgrade Your Capacitor Plugin to Capacitor 8

Capacitor 8 makes Swift Package Manager the default on iOS, bumps the Android target to SDK 36, and upgrades to Kotlin 2.2. This guide covers three ways to bring your Capacitor plugin up to date — an automated CLI tool, AI-powered Capawesome Skills, or a fully manual upgrade.

Build and deploy your Capacitor app with Capawesome Cloud

Why Upgrade to Capacitor 8

Before jumping into the migration steps, here's why the upgrade matters for plugin authors:

  • Swift Package Manager by default: New iOS projects use SPM instead of CocoaPods. CocoaPods entered maintenance mode in August 2024 and its Specs repository will become read-only in December 2026. Updating your plugin's Package.swift ensures compatibility with SPM-based projects.
  • Android SDK 36: Targeting the latest Android platform keeps your plugin compatible with apps that follow Google's target API requirements.
  • Kotlin 2.2: The jump from Kotlin 1.9 to 2.2 is a major upgrade that brings performance improvements and language features, but also includes breaking changes like the removal of the kotlin-android-extensions plugin.
  • Edge-to-edge support: Capacitor 8 introduces a new System Bars plugin for managing status and navigation bar insets, replacing the removed adjustMarginsForEdgeToEdge config option.
  • Updated platform tooling: Xcode 26+ and Android Studio Otter (2025.2.1+) are now required.

What Changes at a Glance

Here's a summary of the most impactful changes for plugin authors. For the full list, see the official plugin upgrade guide.

Dependencies

  • Update @capacitor/core peer dependency to >=8.0.0.
  • Update @capacitor/cli, @capacitor/core, @capacitor/android, and @capacitor/ios dev dependencies to ^8.0.0.

Android

  • Compile and target SDK updated to 36, minimum SDK raised to 24.
  • Gradle wrapper updated to 8.14.3, Android Gradle Plugin (AGP) to 8.13.0.
  • Kotlin updated to 2.2.20.
  • Gradle syntax change: The space-assignment syntax is deprecated. Properties like compileSdk 36 must be written as compileSdk = 36.
  • Replace the deprecated kotlinOptions{} block with the new compilerOptions{} API.
  • Various AndroidX dependency version bumps (AppCompat, JUnit, Espresso, and others).

iOS

  • Deployment target raised to 15.0 in .podspec files and Podfile.
  • Update Package.swift to specify .iOS(.v15) and change the Capacitor SPM dependency from version 7.0.0 to 8.0.0.

Upgrade Options

There are three ways to upgrade — pick the one that best fits your project and workflow.

Option 1: Upgrade Using the Capacitor CLI

The fastest way to upgrade your plugin is the official migration tool. Run the following command from your plugin's root directory:

npx @capacitor/plugin-migration-v7-to-v8@latest

The tool automatically updates your package.json dependencies, adjusts build.gradle values, updates the Gradle wrapper, bumps the iOS deployment target, and applies the Kotlin version change.

This works well for most plugins with a standard project structure. If your plugin has significant native customizations — custom Gradle configurations, non-standard directory layouts, or complex build scripts — you may need to handle some steps manually after the migration. Check the tool's output for any warnings or skipped steps.

Option 2: Upgrade Using Capawesome Skills

Capawesome Skills are agent-optimized instruction sets designed for AI coding assistants like Claude Code, Cursor, or GitHub Copilot. They provide step-by-step upgrade instructions that handle both the automated migration and manual fallback steps.

First, add the skills to your project:

npx skills add capawesome-team/skills

Then, use the following prompt with your AI coding assistant:

Use the `capacitor-plugin-upgrades` skill from `capawesome-team/skills`
to help me upgrade my Capacitor plugin to Capacitor 8.

The skill will attempt the CLI migration first and fall back to manual steps where needed. It also covers edge cases like adding SPM support, updating Kotlin compiler options, and handling the Gradle syntax changes — making it a good option if the CLI tool doesn't catch everything.

Option 3: Upgrade Manually

If you prefer full control, follow the official Capacitor 8 plugin upgrade guide step by step. Here's a condensed overview:

  1. Update @capacitor/core peer dependency to >=8.0.0 and dev dependencies to ^8.0.0.
  2. Android: Update compileSdk, targetSdkVersion, and minSdkVersion in build.gradle:
compileSdk = 36
minSdkVersion = 24
targetSdkVersion = 36
  1. Android: Update Kotlin to 2.2.20 and replace kotlinOptions{} with compilerOptions{}.
  2. Android: Update the Gradle wrapper to 8.14.3 and AGP to 8.13.0.
  3. Android: Switch to the = assignment syntax in all Gradle files.
  4. Android: Update AndroidX dependency versions (only the ones your plugin uses).
  5. iOS: Raise the deployment target to 15.0 in your .podspec file.
  6. iOS: Update Package.swift to target .iOS(.v15) and set the Capacitor SPM dependency to 8.0.0.

This approach takes more effort but gives you complete visibility into every change.

Which Approach Should You Choose?

Approach Best for Trade-off
Capacitor CLI Most plugins with standard project structures Fast, but may miss steps in heavily customized plugins
Capawesome Skills Plugins with custom native code or complex setups Handles edge cases well, requires an AI coding assistant
Manual Plugin authors who want full control Most effort, but complete visibility

For most plugins, the Capacitor CLI migration tool is the right starting point. If you run into issues or have a complex plugin with custom build configurations, Capawesome Skills can fill in the gaps. The manual approach is always available when you need full control.

Try Capawesome Cloud

Building and deploying Capacitor apps is easier with Capawesome Cloud. Get cloud-based native builds, over-the-air live updates, and automated app store publishing — all in one platform.

Try Capawesome Cloud Free

Conclusion

Capacitor 8 brings meaningful updates for plugin authors — SPM as the iOS default, Android SDK 36, Kotlin 2.2, and modernized Gradle syntax. The CLI migration tool handles most of the work, Capawesome Skills can assist with more complex plugins, and the manual route gives you full control when you need it.

If you're also upgrading a Capacitor app project, check out How to Upgrade Your Capacitor App to Capacitor 8 for a full walkthrough of the app-level migration.

If you have questions, join the Capawesome Discord server. To stay up to date with the latest news, subscribe to the Capawesome newsletter.