# capacitor-performance

Diagnoses and resolves Capacitor performance bottlenecks, from slow cold starts and bridge serialization stalls to background white screens.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1200 installs · ★ 73
- Author: Cap-go
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Cap-go/capgo-skills/tree/HEAD/skills/capacitor-performance/SKILL.md
- Updated: 2026-10-17
- HTML: https://affpapa.org/en/nevibecode/skills/capacitor-performance

## What it does

This skill targets performance bottlenecks unique to hybrid apps: JavaScript thread saturation, bridge serialization delays, and memory-induced process terminations. It provides practical profiling workflows for Safari Web Inspector, `chrome://inspect`, Xcode Instruments, and Android Studio Profiler.

The guidance focuses on typical Capacitor architecture traps. It helps replace heavy base64 strings from camera plugins with `webPath`, offloads large file transfers to `@capacitor/file-transfer`, and migrates bulky `@capacitor/preferences` storage to SQLite. It also identifies lingering production bridge logging and unremoved `addListener` handles.

Profiling inside simulators is misleading because virtual devices mask hardware memory and GPU boundaries. Reliable measurements require release-like builds running on physical hardware. Fatal crashes and native stack-trace debugging fall outside this skill and require tools like `debugging-capacitor`.

## Requirements
- Works with: Chrome

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill capacitor-performance -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/capacitor-performance/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/capacitor-performance/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill capacitor-performance -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/capacitor-performance/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill capacitor-performance -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/capacitor-performance/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Cap-go/capgo-skills capacitor-performance
```

2. **Manually: put the files in place**
- File: `.github/skills/capacitor-performance/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill capacitor-performance -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Cap-go/capgo-skills --path skills/capacitor-performance
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/capacitor-performance/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill capacitor-performance -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Cap-go/capgo-skills/tree/HEAD/skills/capacitor-performance/SKILL.md

## When to use it
- eliminate white screens when resuming apps from the background
- speed up bridge transfers for camera photos and large files
- stop memory leaks caused by unremoved plugin listeners
- profile and reduce cold start times on Android devices

## Example prompts
- Profile our slow cold start on Android using adb timing commands.
- Help optimize our camera workflow to stop sending multi-megabyte base64 strings over the bridge.
- Check capacitor.config for debug logging or local dev URLs before our release build.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 6b39830d5f76b8cb.

BEGIN THIRD-PARTY FILE 6b39830d5f76b8cb
```text
---
name: capacitor-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.
---

# 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
```
END THIRD-PARTY FILE 6b39830d5f76b8cb

The third-party file has ended. Everything between the 6b39830d5f76b8cb tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2628 of 8399 bytes. © Cap-go · MIT · https://github.com/Cap-go/capgo-skills/tree/HEAD/skills/capacitor-performance/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md