capacitor-performance

Files (3)

• SKILL.md
• metadata.json
• profiling.md · references/

SKILL.md (first lines)

# 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

1. **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.
2. **Classify** with the profiling table below: JS main thread busy, bridge payloads large, native thread busy, or waiting on network.
3. **Check the traps** list. Most Capacitor-specific regressions are one of these.
4. **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

1. **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/camera` 8.1+ API): use `takePhoto` / `chooseFromGallery` and display `result.webPath`; set `targetWidth`/`targetHeight`/`quality`. Avoid reading full-resolution base64 unless uploading. The older `getPhoto` / `pickImages` are deprecated.
   - Files: pass paths, use `Capacitor.convertFileSrc(uri)` for `<img>/<video>` src, `Filesystem.readFileInChunks` for large reads, `@capacitor/file-transfer` for uploads/downloads.
2. **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 calls `onRenderProcessGone`; unless handled, the app is killed. Reduce peak memory (trap 1, large canvases, decoded images), persist critical state, restore on load.
3. **CapacitorHttp for large responses.** With `plugins.CapacitorHttp.enabled: true`, `fetch`/`XMLHttpRequest` are routed through native and bodies cross the bridge. Great for CORS/cookies, slower for big downloads or streaming. Use file-transfer for big files.
4. **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`).
5. **Logging in release.** `loggingBehavior` defaults to `debug` (logs only in debug builds). If it was set to `production`, every bridge call is logged in release; set it back to `debug` or `none`.
6. **Dev server left in config.** `server.url` pointing to a LAN/live-reload server in a shipped build loads over network and fails offline. Remove before release; in Capacitor 9 use `npx cap run <platform> --url` for live reload instead of editing config.
7. **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`, large `box-shadow`/`filter` on scrolling content) janks on low-end WebViews.
8. **Listener leaks.** `addListener` returns `Promise<PluginListenerHandle>`; await it and call `remove()` on unmount. Re-registering on every route change multiplies native callbacks (`appStateChange`, `keyboardWillShow`, geolocation `watchPosition` - clear with `clearWatch`).
9. **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 Android `launchFadeOutDuration` default from 200 to 0.
10. **Plugin imports are not the startup cost.** Importing `@capacitor/*` packages creates lightweight proxies; their web implementations are already lazy-loaded via `registerPlugin`. 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 dev `server.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.

From Cap-go/capgo-skills, MIT.

More from Cap-go/capgo-skills