capacitor-app-upgrade-v7-to-v8
Upgrades a Capacitor app from v7 to v8 using npx cap migrate from @capacitor/cli@latest, then the manual checklist - Node 22+, Xcode 26+, iOS deployment target 15.0, Android Studio Otter, AGP 8.13.0, Gradle 8.14.3, JDK 21, minSdk 24, compile/target SDK 36, Kotlin 2.2.20, Gradle = property assignment syntax, density in configChanges, removed android.adjustMarginsForEdgeToEdge (use the System Bars plugin and CSS env vars), bridgelayoutmain.xml renamed, iOS appendUserAgent whitespace fix, and official plugin changes (Geolocation timeout, Screen Orientation/Barcode Scanner on Android 16 large screens). Use when @capacitor/core is 7.x and the target is 8.x. Points to the 8.5 UIScene adoption and v9 next steps. Do not use for other major versions, plugin library upgrades, or non-Capacitor apps.
- Installs
- 707
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-app-upgrade-v7-to-v8- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads capacitor-app-upgrade-v7-to-v8 automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Capacitor App Upgrade v7 to v8
Move a Capacitor 7 app to Capacitor 8 (current stable line: 8.5.x). Source of truth: https://capacitorjs.com/docs/updating/8-0
When to Use
@capacitor/corein the snapshot below is7.xand the user wants8.x.- After bumping to 8: content under the Android status/navigation bar (edge-to-edge),
bridge_layout_mainnot found, Gradle "space-assignment syntax" deprecation warnings, Kotlin 2kotlinOptionserrors, or Geolocation timeouts. - The user asks for the exact 7 -> 8 checklist.
Do not use:
- App on 6.x ->
capacitor-app-upgrade-v6-to-v7first. Multi-hop planning ->capacitor-app-upgrades. - App already on 8.x ->
capacitor-uiscene-migration(8.5 scene lifecycle), thencapacitor-app-upgrade-v8-to-v9. - Plugin library upgrade ->
capacitor-plugin-upgrade-v7-to-v8. - CocoaPods to SPM ->
cocoapods-to-spm.
Live Project Snapshot
Current Capacitor packages from package.json:
!node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"
References
Only load a reference when its topic is in play.
| File | Load when |
|---|---|
references/android.md | Editing variables.gradle, Gradle syntax, wrapper, manifest, Kotlin, or edge-to-edge |
references/plugins.md | The app uses official @capacitor/* plugins (Geolocation, Screen Orientation, Barcode Scanner, Status Bar, ...) |
Preflight
| Tool | Minimum for Capacitor 8 |
|---|---|
| Node.js | 22+ (latest LTS recommended) |
| Xcode | 26.0+ |
| iOS deployment target | 15.0 |
| Android Studio | Otter 2025.2.1+ |
| Java (Gradle JDK) | 21 |
| AGP / Gradle | 8.13.0 / 8.14.3 |
| Android SDK | minSdk 24, compileSdk 36, targetSdk 36 |
| Kotlin (if used) | 2.2.20 |
node -v && xcodebuild -version && java -version
git status --short
grep -rn "adjustMarginsForEdgeToEdge\|appendUserAgent" capacitor.config.*
grep -rn "bridge_layout_main" android/ src/ 2>/dev/null
Procedure
-
Confirm 7.x from the snapshot. Tell the user minSdk 24 and iOS 15 drop older devices.
-
Run the automated migration (
latestresolves to the newest 8.x):npm i -D @capacitor/cli@latest npx cap migrate # add --noprompt in CI, --packagemanager pnpm|yarn if not npmIt installs
^8.0.0packages, raises the iOS target / Podfile to 15.0, runscap sync, addsdensitytoconfigChanges, upgrades the Gradle wrapper and Gradle files, and writes breaking changes. Finish every step it reports as failed; it ends withMigration to Capacitor <v> is completeor... is incomplete. Check the log messages for more information. -
Config (
capacitor.config.*):android.adjustMarginsForEdgeToEdgeis removed. Remove it, then handle insets with the System Bars core plugin and CSSenv(safe-area-inset-*)(seereferences/android.md, andsafe-area-handling).- iOS
appendUserAgentno longer adds two extra spaces. If a server parses the old UA, add a leading space onios.appendUserAgentonly (not the root key, which also affects Android).
-
iOS:
- Set iOS Deployment Target = 15.0 on the Project and every Target;
platform :ios, '15.0'in the Podfile (CocoaPods projects). - Capacitor now emits
CAPBridgeViewControllernotifications forviewDidAppearandviewWillTransition. Delete any app extension that posted them itself, or listeners fire twice.
- Set iOS Deployment Target = 15.0 on the Project and every Target;
-
Android: apply
references/android.md(variables,=assignment syntax, AGP 8.13.0, Gradle 8.14.3, google-services 4.4.4, Kotlin 2.2.20,density). Rename anybridge_layout_mainreference tocapacitor_bridge_layout_main. -
Update
@capacitor/*plugins to^8.0.0and community plugins to their v8 releases. Applyreferences/plugins.md. -
CLI note:
npx cap add iosnow generates an SPM project. Existing CocoaPods apps are unaffected; to keep Pods on re-add usenpx cap add ios --packagemanager CocoaPods. CocoaPods Trunk becomes read-only (expected Dec 2, 2026), so recommendcocoapods-to-spmafter the upgrade. -
Run verification.
After 8.x: next required steps
- Xcode 27 requires the iOS UIScene lifecycle. Capacitor 8.5 adopted it (SceneDelegate,
UIApplicationSceneManifest). After this upgrade, run skillcapacitor-uiscene-migrationbefore building with Xcode 27. Once scenes are adopted, AppDelegateapplication(_:open:options:),continue userActivity, and foreground/background lifecycle callbacks stop firing; deep links and custom AppDelegate code must move to the scene delegate. - Then
capacitor-app-upgrade-v8-to-v9(Capacitor 9 is on thenexttag, not GA yet).
Verification
grep -rn "adjustMarginsForEdgeToEdge\|bundledWebRuntime" capacitor.config.* # expect none
grep -rn "bridge_layout_main" android/app/src src/ | grep -v capacitor_bridge # expect none
grep -rn "IPHONEOS_DEPLOYMENT_TARGET" ios/App/App.xcodeproj/project.pbxproj | sort -u # 15.0
grep -n "gradle:8.13.0\|google-services:4.4.4" android/build.gradle
grep -n "distributionUrl" android/gradle/wrapper/gradle-wrapper.properties # gradle-8.14.3
grep -n "SdkVersion" android/variables.gradle # 24 / 36 / 36
grep -nE "^\s*(namespace|compileSdk|ignoreAssetsPattern) [^=]" android/app/build.gradle # expect none
grep -n "configChanges" android/app/src/main/AndroidManifest.xml # includes density
npx cap sync
cd android && ./gradlew assembleDebug --warning-mode all
Build iOS in Xcode 26+ and run on device. On Android 15+/16 check that content is not under the status or navigation bar.
Error Handling
| Error | Fix |
|---|---|
Migrate can only be used on Capacitor 7, please use the CLI in Capacitor 7 to upgrade to 7 first | Run capacitor-app-upgrade-v6-to-v7 first. |
Capacitor 8 requires JDK 21 or higher. Some steps may fail. | Set Gradle JDK to 21. |
Unable to add 'density' to 'android:configChanges' in <file>. Try adding it manually | Add ` |
gradle wrapper files were not updated | Edit distributionUrl to gradle-8.14.3-all.zip, then cd android && ./gradlew wrapper. |
Unable to find "<text>" in <file>. Try updating it manually | Apply the diff from references/android.md. |
Properties should be assigned using the 'propName = value' syntax (Gradle deprecation) | Add = to property assignments. |
cannot find symbol on R.layout.bridge_layout_main (or AAPT resource layout/bridge_layout_main ... not found) | Use capacitor_bridge_layout_main. |
Kotlin: kotlinOptions / kotlin-android-extensions errors | Move to kotlin { compilerOptions { jvmTarget = JvmTarget.JVM_21 } }; replace synthetics with view binding, parcelize with kotlin-parcelize. |
FAQ
What does the capacitor-app-upgrade-v7-to-v8 skill do?
Upgrades a Capacitor app from v7 to v8 using npx cap migrate from @capacitor/cli@latest, then the manual checklist - Node 22+, Xcode 26+, iOS deployment target 15.0, Android Studio Otter, AGP 8.13.0, Gradle 8.14.3, JDK 21, minSdk 24, compile/target SDK 36, Kotlin 2.2.20, Gradle = property assignment syntax, density in configChanges, removed android.adjustMarginsForEdgeToEdge (use the System Bars plugin and CSS env vars), bridgelayoutmain.xml renamed, iOS appendUserAgent whitespace fix, and official plugin changes (Geolocation timeout, Screen Orientation/Barcode Scanner on Android 16 large screens). Use when @capacitor/core is 7.x and the target is 8.x. Points to the 8.5 UIScene adoption and v9 next steps. Do not use for other major versions, plugin library upgrades, or non-Capacitor apps.
How do I install capacitor-app-upgrade-v7-to-v8?
Run npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-app-upgrade-v7-to-v8 in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/capacitor-app-upgrade-v7-to-v8/ (personal) or .claude/skills/capacitor-app-upgrade-v7-to-v8/ (project).
Which AI agents can use capacitor-app-upgrade-v7-to-v8?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is capacitor-app-upgrade-v7-to-v8 safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains capacitor-app-upgrade-v7-to-v8?
It is published by cap-go in cap-go/capgo-skills. It has 707 recorded installs.
More from cap-go/capgo-skills
capacitor-best-practices
cap-go/capgo-skills
Review and set up Capacitor apps against current best practices (Capacitor 8.5 stable, 9 alpha via @next). Use for a Capacitor codebase review, capacitor.config.ts audit, new project setup, aligning @capacitor/core/cli/ios/android and plugin majors, plugin patterns (availability checks, checkPermissions/requestPermissions, error code handling, web fallbacks), or release prep; or on " " plugin is not implemented on ios, Could not find the web assets directory, platform has not been added yet, a dev server.url shipped to production, lost edits in android/app/src/main/assets/public, SPM vs CocoaPods, or AppDelegate/UIScene drift. Do not use for security audits (capacitor-security), performance (capacitor-performance), tests (capacitor-testing), crashes (debugging-capacitor), major upgrades (capacitor-app-upgrades), SPM migration (cocoapods-to-spm), UIScene adoption (capacitor-uiscene-migration), or live updates (capgo-live-updates).
ionic-design
cap-go/capgo-skills
Builds and reviews Ionic Framework UI in Capacitor apps (Ionic 9 current, Ionic 8 still common) - page structure (ion-header/ion-content/ion-footer), lists, modern form syntax (label/labelPlacement on ion-input/ion-select), sheet modals, tabs + ion-router-outlet, CSS variable theming, dark palettes (palettes/dark.system.css, .ion-palette-dark), iOS vs MD mode, and Ionic 8 - 9 breaking changes (React Router 6, Vue Router 5, Angular 18-22 zoneless, removed ion-picker-legacy, boolean autocorrect, npx @ionic/migrate). Use when writing Ionic components, theming an Ionic app, fixing platform-mode styling, or upgrading @ionic/react, @ionic/vue, @ionic/angular. Do not use for Konsta UI (konsta-ui), Tailwind setup (tailwind-capacitor), raw safe-area CSS (safe-area-handling), keyboard resize (capacitor-keyboard), or Ionic Appflow/Enterprise migrations (ionic-appflow-migration, ionic-enterprise-sdk-migration).
capacitor-plugins
cap-go/capgo-skills
Pick, install, and wire up Capacitor plugins for native features (camera, filesystem, geolocation, biometrics, in-app purchases, social login, SQLite, calendar, contacts, health, BLE, NFC, etc.). Covers official @capacitor/ packages (Capacitor 8.5 stable, 9 alpha on next) plus the 145-package @capgo/ index, native permission keys (Info.plist, AndroidManifest, variables.gradle minSdk), npx cap sync / cap ls verification, and errors like '"Camera" plugin is not implemented on ios', 'unable to find plugin', UNIMPLEMENTED, and OS-PLUG- codes. Use for "which plugin should I use for X", adding a plugin, or a plugin call failing after install. Do not use for push setup (capacitor-push-notifications), splash assets (capacitor-splash-screen), keyboard layout (capacitor-keyboard), deep links (capacitor-deep-linking), OTA updates (capgo-live-updates), upgrading plugin source code (capacitor-plugin-upgrades), or adding SPM to a plugin (capacitor-plugin-spm-support).
debugging-capacitor
cap-go/capgo-skills
Diagnoses and fixes runtime bugs in Capacitor iOS/Android apps - white/blank screen on launch, startup crashes, "X" plugin is not implemented on ios/android, net::ERRCLEARTEXTNOTPERMITTED, App Transport Security blocks, CORS on capacitor://localhost, permission denials, live reload not connecting, and Capacitor 8.5+ UIScene regressions (appUrlOpen, universal links, pause/resume silent because AppDelegate callbacks stopped). Covers Safari Web Inspector, chrome://inspect, Xcode/LLDB, Android Studio, npx cap run --url (Capacitor 9) vs -l --host (8), xcrun simctl openurlprivacypush, xcrun devicectl device process launchopenURL, xctrace. Do not use for only reading device logs (ios-android-logs), the UIScene migration itself (capacitor-uiscene-migration), deep-link setup (capacitor-deep-linking), speed (capacitor-performance), crash SDKs (capacitor-native-observability), tests (capacitor-testing), or upgrades/build errors (capacitor-app-upgrades, cocoapods-to-spm).
capacitor-testing
cap-go/capgo-skills
Testing guide for Capacitor apps and plugins. Covers web-layer unit and component tests with Vitest and mocked Capacitor plugins (vi.mock('@capacitor/core'), registerPlugin), Playwright for the web build, Appium E2E with NATIVEAPP / WEBVIEW context switching, native plugin unit tests with Swift Testing vs XCTest (what can migrate, CAPPluginCall patterns, xcodebuild test on a simulator) and Android JUnit, plus an agent-driven verification loop on simulators and devices (build, install, launch, screenshot, UI hierarchy, tap, logs) with xcrun simctl, xcrun devicectl, adb, Xcode MCP device tools, and live reload via npx cap run --url (Capacitor 9) or -l --host --port (Capacitor 8). Use when adding tests, mocking plugins, "does it work on device", verifying a UI change on a simulator, migrating XCTest to Swift Testing, or setting up test CI. Do not use for crash log capture (ios-android-logs), WebView debugging sessions (debugging-capacitor), or build pipelines (capacitor
safe-area-handling
cap-go/capgo-skills
Fixes notch, Dynamic Island, home indicator, display cutout, and system bar overlap in Capacitor apps. Covers viewport-fit=cover + env(safe-area-inset-), the Capacitor 8 SystemBars core plugin (insetsHandling, injected --safe-area-inset- CSS variables for Android WebView < 140, removal of android.adjustMarginsForEdgeToEdge), Android 15/16 enforced edge-to-edge (overlaysWebView and backgroundColor of @capacitor/status-bar no longer work at targetSdk 36), iOS contentInset, and insets that change at runtime on rotation, iPad/foldable resizable windows. Use when headers sit under the status bar, tab bars hide behind the gesture bar, env() returns 0 on Android, or layout broke after upgrading to Capacitor 8 / targetSdk 35+. Do not use for keyboard overlap (capacitor-keyboard), Ionic/Konsta component theming (ionic-design, konsta-ui), Tailwind utility setup (tailwind-capacitor), or iOS multi-window/resizability adoption (capacitor-ios-resizability).
Popular mobile skills
design-mobile-apps
designed-by-ai/skills
Design mobile app screens with Sleek, edit Sleek projects, and implement their designs in React Native or HTML.
ios-design
uizze.sh
Design and review iOS UI/UX for iPhone apps in SwiftUI, UIKit, or React Native. Use for mobile app design, screen redesigns, navigation flows, typography, forms, keyboard and safe-area layout, and accessibility checks. Apply Apple Human Interface Guidelines and consult real product references through the optional Uizze connection.
vercel-react-native-skills
vercel-labs/agent-skills
React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.
animate-expo
emilkowalski/skills
Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use animate.
xcode-project-setup
firebase/agent-skills
Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).
firebase-remote-config-basics
firebase/agent-skills
Manages Firebase Remote Config templates, feature flags, loading strategies, and SDKs (Android, iOS). Use when downloading/deploying remoteconfig JSON templates, managing version history/feature flags, setting in-app defaults, fetchAndActivate(), real-time listeners, or SDK setup. Don't use for Firebase Hosting, Auth, Firestore, Data Connect, Crashlytics, or App Hosting.