capacitor-performance
Diagnoses and fixes performance problems specific to Capacitor apps - slow cold start or long splash, white screen after camera/backgrounding (WKWebView "WebView process terminated" reload, Android onRenderProcessGone), large base64 payloads over the native bridge (Camera, Filesystem.readFile, CapacitorHttp), jank in the WebView, memory growth from unremoved plugin listeners, oversized Preferences storage, slow Android WebView versions, and debug logging left on in release. Covers profiling with Safari Web Inspector, chrome://inspect, Xcode Instruments, Android Studio Profiler, and adb timing commands. Do not use for crash/stack-trace debugging (use debugging-capacitor or capacitor-native-observability), device log capture (use ios-android-logs), offline data architecture (use capacitor-offline-first / sqlite-to-fast-sql), splash configuration details (use capacitor-splash-screen), or generic web performance unrelated to Capacitor.
- Installs
- 1.2K
- 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-performance- 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-performance 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 Performance
Find the bottleneck first (WebView JS, bridge, native, or network), then fix the specific cause. Generic web advice (code splitting, image compression, virtual lists) still applies; this skill focuses on what is different inside Capacitor.
When to Use
TRIGGER when:
- Cold start is slow, splash stays long, or the first screen is blank for seconds.
- App "restarts" or shows a white screen after taking a photo, opening a big file, or returning from background.
- Native calls feel slow, especially with images, files, or large HTTP responses.
- Scrolling/animations jank only on device (often older Android WebView).
- Memory grows over time; listeners pile up.
Do not use:
- Crashes, native stack traces ->
debugging-capacitor,capacitor-native-observability. - Getting logs off a device ->
ios-android-logs. - Offline storage design / SQLite migration ->
capacitor-offline-first,sqlite-to-fast-sql. - Splash screen setup ->
capacitor-splash-screen; keyboard resize jank ->capacitor-keyboard. - OTA bundle size and delta updates ->
capgo-live-updates.
Procedure
- Reproduce on a real device in a release-like build. Debug builds log every bridge call and disable optimizations; simulators hide memory and GPU limits.
- Classify with the profiling table below: JS main thread busy, bridge payloads large, native thread busy, or waiting on network.
- Check the traps list. Most Capacitor-specific regressions are one of these.
- Fix one thing, measure again with the same command/trace. Report before/after numbers to the user.
Profiling Quick Reference
| Question | Tool |
|---|---|
| JS long tasks, layout, paint (iOS) | Safari > Develop > device > app > Timelines. Requires ios.webContentsDebuggingEnabled: true for release builds (debug builds are inspectable by default on iOS 16.4+). |
| JS long tasks, memory heap (Android) | chrome://inspect > Performance / Memory. |
| Native CPU, allocations, leaks (iOS) | Xcode > Product > Profile > Time Profiler / Allocations / Leaks; field data in Xcode Organizer > Metrics. |
| Native CPU/memory (Android) | Android Studio > Profiler. |
| Android cold start time | adb shell am force-stop <appId> && adb shell am start -W -n <appId>/.MainActivity (read TotalTime). |
| Android frame stats | adb shell dumpsys gfxinfo <appId> (janky frames %). |
| Android WebView version | adb shell dumpsys webviewupdate (current provider and version). |
Details and recipes: references/profiling.md.
Capacitor-Specific Traps
- Base64 over the bridge. Every plugin call/response is JSON-serialized across the bridge. Multi-MB base64 strings stall both threads and can kill the WebView process.
- Camera (
@capacitor/camera8.1+ API): usetakePhoto/chooseFromGalleryand displayresult.webPath; settargetWidth/targetHeight/quality. Avoid reading full-resolution base64 unless uploading. The oldergetPhoto/pickImagesare deprecated. - Files: pass paths, use
Capacitor.convertFileSrc(uri)for<img>/<video>src,Filesystem.readFileInChunksfor large reads,@capacitor/file-transferfor uploads/downloads.
- Camera (
- WebView process killed under memory pressure. iOS logs
WebView process terminated; Capacitor resets the bridge and reloads the page, so in-memory JS state is lost (looks like a restart). Android callsonRenderProcessGone; unless handled, the app is killed. Reduce peak memory (trap 1, large canvases, decoded images), persist critical state, restore on load. - CapacitorHttp for large responses. With
plugins.CapacitorHttp.enabled: true,fetch/XMLHttpRequestare routed through native and bodies cross the bridge. Great for CORS/cookies, slower for big downloads or streaming. Use file-transfer for big files. - Preferences as a database.
@capacitor/preferences(UserDefaults / SharedPreferences) is for small key/value data. Large JSON blobs are read/written whole and slow startup; use SQLite (for example@capgo/capacitor-fast-sql). - Logging in release.
loggingBehaviordefaults todebug(logs only in debug builds). If it was set toproduction, every bridge call is logged in release; set it back todebugornone. - Dev server left in config.
server.urlpointing to a LAN/live-reload server in a shipped build loads over network and fails offline. Remove before release; in Capacitor 9 usenpx cap run <platform> --urlfor live reload instead of editing config. - Old Android System WebView. Performance and CSS support depend on the updatable WebView, not the OS version.
android.minWebViewVersion(default 60) only shows an error/server.errorPath; it does not update anything. Expensive CSS (backdrop-filter, largebox-shadow/filteron scrolling content) janks on low-end WebViews. - Listener leaks.
addListenerreturnsPromise<PluginListenerHandle>; await it and callremove()on unmount. Re-registering on every route change multiplies native callbacks (appStateChange,keyboardWillShow, geolocationwatchPosition- clear withclearWatch). - Startup sequencing. Hide the splash only after first meaningful render (
launchAutoHide: false+SplashScreen.hide()), and defer non-critical plugin calls (analytics init, permission checks) until after first paint. Note Capacitor 9 changes AndroidlaunchFadeOutDurationdefault from 200 to 0. - Plugin imports are not the startup cost. Importing
@capacitor/*packages creates lightweight proxies; their web implementations are already lazy-loaded viaregisterPlugin. Lazy-load heavy JS libraries (charts, PDF, maps SDK JS) and routes instead.
Verification
- Same device, same build type, before/after numbers: cold start
TotalTime(Android) or Instruments App Launch / Organizer launch time (iOS), janky frame %, peak memory in Allocations/Profiler. - Grep the release config:
grep -nE '"url"|loggingBehavior|webContentsDebuggingEnabled' capacitor.config.*and confirm no devserver.url. - For trap 1, grep for full-size base64 usage:
grep -rnE "resultType: *CameraResultType.Base64|readFile\(|getPhoto\(" src/. - Background the app, open the camera 10 times, return: the page must not reload (iOS) or crash (Android).
Error Handling
| Message / symptom | Meaning | Fix |
|---|---|---|
WebView process terminated (Xcode console) | WKWebView content process killed (memory) | Trap 1/2: lower peak memory, persist state. |
Android logcat Render process ... gone / app exits after heavy page | Renderer crashed or killed | Reduce memory; implement handling via a WebViewListener onRenderProcessGone if recovery is required. |
ANR in <appId> (logcat) | Main thread blocked > 5 s, often heavy plugin work on UI thread | Move native work off main thread in custom plugins; profile with Android Studio. |
Message from debugger: Terminated due to memory issue | iOS jetsam killed the whole app | Allocations instrument; reduce image decoding and caches. |
Logcat error about the WebView version being below minWebViewVersion | Device WebView too old | Ask user to update Android System WebView; show server.errorPath page. |
References
Only load when needed:
references/profiling.md: step-by-step traces (Safari Timelines, Chrome Performance, Instruments templates, Android Profiler, adb commands) and how to read them.
FAQ
What does the capacitor-performance skill do?
Diagnoses and fixes performance problems specific to Capacitor apps - slow cold start or long splash, white screen after camera/backgrounding (WKWebView "WebView process terminated" reload, Android onRenderProcessGone), large base64 payloads over the native bridge (Camera, Filesystem.readFile, CapacitorHttp), jank in the WebView, memory growth from unremoved plugin listeners, oversized Preferences storage, slow Android WebView versions, and debug logging left on in release. Covers profiling with Safari Web Inspector, chrome://inspect, Xcode Instruments, Android Studio Profiler, and adb timing commands. Do not use for crash/stack-trace debugging (use debugging-capacitor or capacitor-native-observability), device log capture (use ios-android-logs), offline data architecture (use capacitor-offline-first / sqlite-to-fast-sql), splash configuration details (use capacitor-splash-screen), or generic web performance unrelated to Capacitor.
How do I install capacitor-performance?
Run npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-performance 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-performance/ (personal) or .claude/skills/capacitor-performance/ (project).
Which AI agents can use capacitor-performance?
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-performance 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-performance?
It is published by cap-go in cap-go/capgo-skills. It has 1,188 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 code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.