--- title: How to Upgrade Your Capacitor App to Capacitor 8 description: Learn how to upgrade your Capacitor app to Capacitor 8 using the CLI, AI-powered Capawesome Skills, or a manual approach. date: created: 2026-03-23 updated: 2026-07-17 authors: - robingenz categories: - Guides faq: true --- # 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](https://blog.cocoapods.org/CocoaPods-Specs-Repo-Rate-Limiting/){:target="_blank"} 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](https://capacitorjs.com/docs/updating/8-0){:target="_blank"}. ### 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: ```groovy 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. ```bash 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](https://github.com/capawesome-team/skills){:target="_blank"} 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: ```bash 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](https://capacitorjs.com/docs/updating/8-0){:target="_blank"} 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: ```bash npm i @capacitor/cli@latest @capacitor/core@latest @capacitor/ios@latest @capacitor/android@latest ``` 3. **iOS**: Update Xcode to 26.0+, set the deployment target to 15.0, and update the `Podfile` platform accordingly. 4. **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`. 5. Update all official and third-party Capacitor plugins to their Capacitor 8–compatible versions. 6. 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. ## FAQ ### Do I have to switch to Swift Package Manager to upgrade to Capacitor 8? No — SPM is only the default for new projects. Existing apps aren't forced onto SPM by upgrading; you can keep CocoaPods or explicitly opt into it on a new iOS platform add with `npx cap add ios --packagemanager CocoaPods`. The version bump and the dependency-manager switch are two separate decisions. ### Will `npx cap migrate` handle every change automatically? For most standard projects, yes — but check its output carefully. Apps with significant native customizations (custom build scripts, manual Gradle edits, non-standard project structures) can hit steps the CLI skips or flags for manual follow-up. The migration output itself tells you where it needs help, so read it rather than assuming a clean run means everything is done. ### Do I need to update every third-party plugin before upgrading my app? Yes, if those plugins aren't yet compatible with Capacitor 8 — an incompatible plugin can break your build or fail at runtime after the core upgrade. Both the CLI migration and the manual path include a step for updating all official and third-party plugins to their Capacitor 8-compatible versions; skipping it just moves the failure from upgrade-time to first-run. ### What if my project uses `adjustMarginsForEdgeToEdge` — does removing it break my UI? It stops working, since the config option is gone entirely in Capacitor 8, not deprecated-but-functional. The replacement is the new System Bars core plugin, which manages system bar insets via CSS `env` variables instead — this is a required code change, not just a config rename, so budget time to actually wire up the new plugin rather than expecting a drop-in. ### Is the Capawesome Skills approach only useful for large, plugin-heavy projects? It's most valuable there, but not exclusively. The skill covers both the core Capacitor upgrade and configuration for 160+ Capacitor plugins, which is where it saves the most time on a complex project — but it still works fine as an assisted upgrade path for smaller projects, falling back to manual steps wherever automation can't safely proceed. ## Related Posts - [How to Fix Capacitor Plugin Build Errors with AGP 9](./how-to-fix-capacitor-plugin-build-errors-with-agp-9.md) - [Support 16 KB page sizes in Android with Capacitor](./support-16kb-page-sizes-with-capacitor.md) ## Try Capawesome Cloud Building and deploying Capacitor apps is easier with [Capawesome Cloud](/){:target="_blank"}. Get cloud-based native builds, over-the-air live updates, and automated app store publishing — all in one platform. [Try Capawesome Cloud Free](/){ .md-button .md-button--primary } ## 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](./how-to-upgrade-your-capacitor-plugin-to-capacitor-8.md) for a full walkthrough of the plugin-level migration. If you're also using Capawesome plugins, check out [Updating to Capacitor 8.0](./updating-to-capacitor-8.md) for a breakdown of plugin-specific breaking changes. If you have questions, join the [Capawesome Discord server](https://discord.gg/VCXxSVjefW){:target="_blank"}. To stay up to date with the latest news, subscribe to the [Capawesome newsletter](/newsletter/){:target="_blank"}.