Skip to content

How to Upgrade Your Capacitor App to Capacitor 8

Capacitor 8 ships with Swift Package Manager as the default for iOS, targets Android SDK 36, and requires Node.js 22+. Whether you prefer an automated CLI migration, an AI-assisted upgrade, or full manual control, this guide walks you through all three approaches so you can pick the one that fits your project best.

Build and deploy your Capacitor app with Capawesome Cloud

Why Upgrade to Capacitor 8

Before diving into the how, here's why the upgrade is worth it:

  • Swift Package Manager by default: New iOS projects use SPM instead of CocoaPods, aligning with Apple's direction for dependency management. CocoaPods entered maintenance mode in August 2024 and its Specs repository will become read-only in December 2026.
  • Android SDK 36: Targets the latest Android platform with updated Gradle tooling.
  • Node.js 22+: Requires the current LTS version, keeping your toolchain up to date.
  • New System Bars plugin: Replaces the removed adjustMarginsForEdgeToEdge config option with a proper core plugin for managing system bar insets via CSS env variables.
  • 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 breaking changes. For the full list, see the official upgrade guide.

iOS

  • SPM is the default for new projects. To use CocoaPods instead, run npx cap add ios --packagemanager CocoaPods.
  • iOS deployment target raised to 15.0.
  • Requires Xcode 26.0+.

Android

  • Minimum SDK raised to 24, compile and target SDK updated to 36.
  • Gradle wrapper updated to 8.14.3, AGP to 8.13.0.
  • bridge_layout_main.xml renamed to capacitor_bridge_layout_main.xml.
  • density must be added to configChanges in AndroidManifest.xml.
  • Updated variables.gradle values:
minSdkVersion = 24
compileSdkVersion = 36
targetSdkVersion = 36

Config

  • android.adjustMarginsForEdgeToEdge has been removed. Use the new System Bars core plugin instead.

Node.js

  • Node.js 22 or greater is required.

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 is the built-in migrate command. It updates your dependencies, adjusts platform configuration files, and handles most of the heavy lifting automatically.

npm i -D @capacitor/cli@latest
npx cap migrate

The CLI will walk you through the migration interactively — updating package.json dependencies, modifying native project files, and prompting you where manual intervention is needed.

This works well for most projects. However, if your app has significant native customizations (custom build scripts, manual Gradle modifications, or non-standard project structures), you may need to handle some steps manually after the migration. Check the CLI output carefully for any warnings or skipped steps.

Option 2: Upgrade Using Capawesome Skills

Capawesome Skills are AI agent tools designed to automate development tasks for Capacitor projects. They work with AI coding assistants like Claude Code, Cursor, or GitHub Copilot and provide step-by-step upgrade instructions that are optimized for machine-actionable execution.

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-app-upgrades` skill from `capawesome-team/skills`
to help me upgrade my Capacitor app to Capacitor 8.

The skill will attempt the automated upgrade first and fall back to manual steps where needed. It covers both the core Capacitor upgrade and the configuration of 160+ Capacitor plugins, making it a good choice for projects with many dependencies.

Option 3: Upgrade Manually

If you prefer full control over every change, you can follow the official Capacitor 8 upgrade guide step by step. Here's a condensed overview of the key steps:

  1. Update Node.js to version 22+.
  2. Install the latest Capacitor packages:
npm i @capacitor/cli@latest @capacitor/core@latest @capacitor/ios@latest @capacitor/android@latest
  1. iOS: Update Xcode to 26.0+, set the deployment target to 15.0, and update the Podfile platform accordingly.
  2. Android: Update Android Studio to Otter (2025.2.1+), run the AGP Upgrade Assistant, update variables.gradle with the new SDK and dependency versions, update the Gradle wrapper to 8.14.3, and add density to configChanges in AndroidManifest.xml.
  3. Update all official and third-party Capacitor plugins to their Capacitor 8–compatible versions.
  4. Replace any usage of adjustMarginsForEdgeToEdge with the new System Bars core plugin.

This approach takes more effort but gives you the most visibility into exactly what changes in your project.

Which Approach Should You Choose?

Approach Best for Trade-off
Capacitor CLI Most projects with standard setups Fast, but may skip steps in heavily customized projects
Capawesome Skills Projects with many plugins or native customizations Handles edge cases well, requires an AI coding assistant
Manual Teams that want full control over every change Most effort, but complete visibility

For most teams, starting with the Capacitor CLI is the right call. If you run into issues or have a complex project with many plugins, Capawesome Skills can help fill in the gaps. The manual approach is there when you need it, but it's rarely necessary to do everything by hand.

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 platform updates — SPM as the iOS default, Android SDK 36 targeting, and a cleaner approach to system bar insets. Upgrading doesn't have to be painful: the CLI handles most of the work, Capawesome Skills can assist with complex projects, and the manual route is always available as a fallback.

If you're upgrading a Capacitor plugin, check out How to Upgrade Your Capacitor Plugin to Capacitor 8 for a full walkthrough of the plugin-level migration. If you're also using Capawesome plugins, check out Updating to Capacitor 8.0 for a breakdown of plugin-specific breaking changes.

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