The Capacitor 8 Migration Guide: What You Need to Know

Hey everyone, Nouman here.

If you’re running a serious production app, you know that keeping your native runtime updated is non-negotiable. The Capacitor team just dropped Capacitor 8, and while the migration is mostly straightforward, there are some significant architectural shifts—specifically around how we handle System Bars and Edge-to-Edge layouts.

I’ve gone through the breaking changes so you don’t have to guess. Here is your roadmap to upgrading from v7 to v8.

1. The Big Picture

Before you run any commands, here is what has changed at a high level:

• NodeJS 22+ is now required. If you are still on Node 18 or 20, it’s time to upgrade your environment.
• Edge-to-Edge is mandatory. The old adjustMarginsForEdgeToEdge config on Android is gone. We are moving to a CSS-variable-based approach (using env()), which aligns with modern native standards.
• iOS Package Management: The CLI now defaults to SPM (Swift Package Manager) for new iOS folders. If you rely on CocoaPods, you'll need to specify that explicitly.

2. Automated Migration (The Easy Way)

As always, the Capacitor CLI can do about 90% of the heavy lifting for you. I highly recommend running this first, and then manually checking the items below.

First, update your CLI:

Bash

npm i -D @capacitor/cli@latest

Then run the migration tool:

Bash

npx cap migrate

If the tool yells at you or fails, don't panic. Just follow the manual steps below.

3. Android Breaking Changes

The Android update is heavy on tooling requirements this year.

Tooling Updates:

• Android Studio: You need Otter | 2025.2.1 or newer.
• SDK Versions: Update your variables.gradle to target SDK 36.
  • minSdkVersion = 24
  • compileSdkVersion = 36
  • targetSdkVersion = 36

Gradle Syntax Update: Gradle is deprecating the "space" syntax for property assignment. You need to add = signs in your build.gradle.

Old:

Groovy

namespace "com.getcapacitor.myapp"

New:

Groovy

namespace = "com.getcapacitor.myapp"

Manifest Update (Crucial for Resizing): To stop your WebView from reloading when the app resizes (common on foldables or desktop mode), you must add density to your configChanges in AndroidManifest.xml.

XML

android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"

4. iOS Breaking Changes

Tooling Updates:

• Xcode: You need version 26.0+.
• Deployment Target: Bump your iOS Deployment Target to iOS 15.0. Do this in the Project Settings and your Podfile if you use one.

Config Bug Fix: If you use appendUserAgent in your config, check your iOS behavior. There was a bug that added double spaces on iOS. It's fixed now, so if you were manually adding a space to hack around it, remove that extra space or move it to ios.appendUserAgent to target iOS specifically.

5. The "System Bars" Shift

This is the most critical change for UI developers. The android.adjustMarginsForEdgeToEdge configuration is dead.

If you were relying on Capacitor to automatically push your content down so it doesn't hide behind the status bar, that behavior is gone. Capacitor 8 expects you to handle this like a modern native app: using CSS.

You need to switch to the new System Bars core plugin philosophy. Ensure your CSS uses the safe area environment variables:

CSS

ion-content {
  --padding-top: env(safe-area-inset-top);
  --padding-bottom: env(safe-area-inset-bottom);
}

This effectively forces your app to draw behind the bars (Edge-to-Edge), giving you that premium look by default.

6. Plugin Updates

All core plugins have bumped to 8.0.0. Here are the "gotchas" I noticed:

• Barcode Scanner & Screen Orientation: On Android 16+, locking orientation on large screens (tablets) is ignored by the OS to support better multitasking. You can opt-out temporarily via the manifest, but Google is pushing hard for responsive layouts.
• Geolocation: The timeout property now applies to all requests on Android and iOS. If your GPS calls start timing out, increase your timeout value.

Final Thoughts

This update pushes us closer to a "truly native" mental model. The shift away from automatic margins to CSS safe-areas might feel annoying if you have a legacy codebase, but it offers significantly more control over your UI in the long run.

Update your dependencies, check your Safe Areas, and get that Android SDK bumped.

Happy Coding. — Nouman Sehgal