capacitor-performance ยท diff
git:20260501.ed3e92e to git:20261011.86834d4
61 added, 152 removed. Audit A to A.
---
name: capacitor-performance
- description: Performance optimization guide for Capacitor apps covering bundle size, rendering, memory, native bridge, and profiling. Use this skill when users need to optimize their app performance.
+ description: 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.
---
- # Performance Optimization for Capacitor
-
- Make your Capacitor apps fast and responsive.
-
- ## When to Use This Skill
-
- - User has slow app
- - User wants to optimize
- - User has memory issues
- - User needs profiling
- - User has janky animations
-
- ## Quick Wins
-
- ### 1. Lazy Load Plugins
-
- ```typescript
- // BAD - All plugins loaded at startup
- import { Camera } from '@capacitor/camera';
- import { Filesystem } from '@capacitor/filesystem';
- import { Geolocation } from '@capacitor/geolocation';
-
- // GOOD - Load when needed
- async function takePhoto() {
- const { Camera } = await import('@capacitor/camera');
- return Camera.getPhoto({ quality: 90 });
- }
- ```
-
- ### 2. Reduce Bundle Size
-
- ```bash
- # Analyze bundle
- npx vite-bundle-visualizer
-
- # Tree-shake imports
- import { specific } from 'large-library'; // Good
- import * as everything from 'large-library'; // Bad
- ```
-
- ### 3. Optimize Images
-
- ```typescript
- // Use appropriate quality
- const photo = await Camera.getPhoto({
- quality: 80, // Not 100
- width: 1024, // Limit size
- resultType: CameraResultType.Uri, // Not Base64
- });
-
- // Lazy load images
- <img loading="lazy" src={url} />
- ```
-
- ### 4. Minimize Bridge Calls
-
- ```typescript
- // BAD - Multiple bridge calls
- for (const item of items) {
- await Storage.set({ key: item.id, value: item.data });
- }
-
- // GOOD - Single call with batch
- await Storage.set({
- key: 'items',
- value: JSON.stringify(items),
- });
- ```
-
- ## Rendering Performance
-
- ### Use CSS Transforms
-
- ```css
- /* GPU accelerated */
- .animated {
- transform: translateX(100px);
- will-change: transform;
- }
-
- /* Avoid - triggers layout */
- .animated {
- left: 100px;
- }
- ```
-
- ### Virtual Scrolling
-
- ```typescript
- // Use virtual list for long lists
- import { VirtualScroller } from 'your-framework';
-
- <VirtualScroller
- items={items}
- itemHeight={60}
- renderItem={(item) => <ListItem item={item} />}
- />
- ```
-
- ### Debounce Events
-
- ```typescript
- import { debounce } from 'lodash-es';
-
- const handleScroll = debounce((e) => {
- // Handle scroll
- }, 16); // ~60fps
- ```
-
- ## Memory Management
+ # Capacitor Performance
- ### Cleanup Listeners
+ 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.
- ```typescript
- import { App } from '@capacitor/app';
+ ## When to Use
- // Store listener handle
- const handle = await App.addListener('appStateChange', callback);
+ 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.
- // Cleanup on unmount
- onUnmount(() => {
- handle.remove();
- });
- ```
+ 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`.
- ### Avoid Memory Leaks
+ ## Procedure
- ```typescript
- // Clear large data when done
- let largeData = await fetchLargeData();
- processData(largeData);
- largeData = null; // Allow GC
- ```
+ 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
+ ## Profiling Quick Reference
- ### Chrome DevTools
+ | 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). |
- 1. Connect via chrome://inspect
- 2. Performance tab > Record
- 3. Analyze flame chart
+ Details and recipes: `references/profiling.md`.
- ### Xcode Instruments
+ ## Capacitor-Specific Traps
- 1. Product > Profile
- 2. Choose Time Profiler
- 3. Analyze hot paths
+ 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.
- ### Android Profiler
+ ## Verification
- 1. View > Tool Windows > Profiler
- 2. Select CPU/Memory/Network
- 3. Record and analyze
+ - 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).
- ## Metrics to Track
+ ## Error Handling
- | Metric | Target |
- |--------|--------|
- | First Paint | < 1s |
- | Time to Interactive | < 3s |
- | Frame Rate | 60fps |
- | Memory | Stable, no growth |
- | Bundle Size | < 500KB gzipped |
+ | 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. |
- ## Resources
+ ## References
- - Chrome DevTools: https://developer.chrome.com/docs/devtools
- - Xcode Instruments: https://developer.apple.com/instruments
+ 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.