
capacitor-quality
Capacitor quality skills for testing, debugging, logs, performance, accessibility, security, and Xcode build hardening.
- version
- 1.1.0
- GitHub stars
- 79
Install
/plugin install capacitor-quality@capgo-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add Cap-go/capgo-skills.
Contents
Discovered from sourceSkills 7
Accessibility in Capacitor Apps
The UI is web content inside WKWebView / Android WebView, so standard semantic HTML and ARIA do most of the work. This skill covers where the WebView and native layers behave differently from a browser.
When to Use
TRIGGER when:
- User asks for VoiceOver/TalkBack support, an accessibility audit, WCAG 2.2 / EAA / ADA compliance.
- Text does not grow with iOS Larger Text, or the layout breaks at large Android font sizes.
- Screen reader does not announce page changes, toasts, or loading states.
- A native view (map, camera preview, video player) cannot be reached by the screen reader.
- User wants
@capacitor/screen-readeror@capacitor/text-zoom.
Do not use:
- Ionic component APIs/theming ->
ionic-design; Konsta/Tailwind ->konsta-ui,tailwind-capacitor. - Content under notch/home indicator ->
safe-area-handling. - Keyboard covering inputs ->
capacitor-keyboard. - E2E test infrastructure ->
capacitor-testing.
Procedure
Use a user-selected test device and local web build. Prefer the project-installed axe dependency. Installing or running an npm tool downloads executable code; do so only as part of the requested audit, and preserve the lockfile. Restore device settings after testing.
- Inventory screens into a TODO list (auth, main tabs, forms, modals, media, settings). Audit one at a time.
- Automated pass on the web build: run axe (
@axe-core/playwrightin tests, ornpx @axe-core/cli@latest http://localhost:5173) and fix violations first (names, roles, contrast, labels). - Device pass per screen with VoiceOver and TalkBack, largest text size, Reduce Motion, and a Bluetooth keyboard (iPad). Use the checks in
references/testing.md. - Fix Capacitor-specific traps below.
- Report findings per screen with WCAG criterion, severity, and fix before large refactors; ask before changing design tokens (colors, font sizes).
Capacitor-Specific Traps
- iOS Dynamic Type is ignored by default. WKWebView renders
px/remtext at fixed size regardless of Settings > Accessibility > Larger Text. Options:- CSS:
html { font: -apple-system-body; }and size everything else inrem/em(WebKit maps this to the user's content size category; updates live). - Or
TextZoom.getPreferred()thenTextZoom.set({ value })from@capacitor/text-zoomon launch and onresume. On iPad this requiresios.preferredContentMode: 'mobile'incapacitor.config.*. Pick one, not both, or text scales twice.
- CSS:
- Android font scale applies automatically. Android WebView scales text with the system font size, so fixed-height containers,
line-clamp, and absolute layouts overflow at 200%. Test withadb shell settings put system font_scale 2.0and design for reflow (WCAG 1.4.4, 1.4.10). - Pinch zoom.
zoomEnableddefaults tofalseand many templates shipuser-scalable=no. Users can still scale text via traps 1/2; if you rely on zoom instead, setzoomEnabled: trueand dropuser-scalable=no. - SPA navigation is silent. Route changes do not trigger a page-load announcement. After navigation set
document.title, move focus to the main heading (<h1 tabindex="-1">), or update a polite live region. Do not useScreenReader.speakas the primary mechanism: it only speaks when a screen reader is active and bypasses the user's verbosity settings. - Native views under or over the WebView.
@capacitor/google-mapsrenders a native map behind a transparent WebView region; camera preview plugins do the same. The screen reader sees the WebView, not the native view. Provide an accessible alternative (list of markers, text summary, capture button with label) in HTML. - Native plugin UI. Dialogs, action sheets, share sheets, pickers from official plugins are native and accessible by default; custom native screens in your own plugins need
accessibilityLabel/contentDescription(seereferences/native.md). - Touch targets. Apple HIG minimum 44x44 pt; Material 48x48 dp; WCAG 2.2 2.5.8 minimum 24x24 CSS px. Icon buttons need padding, not just a small SVG.
- Motion and contrast.
prefers-reduced-motionandprefers-contrastmedia queries work in both WebViews. Disable parallax/auto-playing transitions under reduce motion; test Increase Contrast. - Status changes. Toasts (
@capacitor/toastis native and announced), inline errors, spinners: userole="status"/aria-live="polite"for web toasts andaria-busyon loading regions; userole="alert"only for errors. - Focus after native round-trips. After a native modal (camera, share, auth browser) closes, focus may land on
<body>. Restore focus to the triggering control onappStateChange/promise resolution.
Verification
- axe: zero critical/serious violations on each audited route.
- VoiceOver (iOS) and TalkBack (Android): every control has a spoken name, role, and state; swipe order follows visual order; route change is announced or focus moves to heading.
- Largest text:
xcrun simctl ui booted content_size accessibility-extra-extra-extra-largeandadb shell settings put system font_scale 2.0; no clipped or overlapping text, no horizontal scroll on body. - Grep:
grep -rnE "user-scalable=no|maximum-scale=1" index.html src/andgrep -rn "outline: *none\|outline: *0" src/(each must have a:focus-visiblereplacement). - Reset after testing:
adb shell settings put system font_scale 1.0,xcrun simctl ui booted content_size large.
Error Handling
| Symptom / message | Fix |
|---|---|
ScreenReader.isEnabled rejects/unavailable on web | Not supported on web (screen readers cannot be detected); guard with Capacitor.isNativePlatform(). |
speak throws on web | Browser lacks SpeechSynthesis; only call on native or feature-detect 'speechSynthesis' in window. |
"TextZoom" plugin is not implemented on web | text-zoom is native only; skip on web. |
| Text zoom has no effect on iPad | Set ios.preferredContentMode: 'mobile'. |
| Text scaled twice on iOS | Using both -apple-system-body and TextZoom; keep one. |
| VoiceOver reads "button" with no name | Icon-only control missing aria-label or visible text. |
References
Only load when the topic is in play:
references/testing.md: VoiceOver/TalkBack gestures, Accessibility Inspector, Android Accessibility Scanner, adb/simctl setting commands, axe in Playwright, per-screen checklist.references/native.md: Swift/Kotlin accessibility APIs for custom native plugin views, posting announcements from native code.
Capacitor iOS Security Hardening
Audit the security-relevant Xcode build settings of a Capacitor app and its native plugins, then enable them in stages the user approves. This skill changes build settings and entitlements only. It never touches web code, ATS, signing, or secrets.
When to Use
TRIGGER when:
- The user wants to audit or harden the iOS build configuration of a Capacitor app
- The user asks about Enhanced Security,
ENABLE_ENHANCED_SECURITY, hardened-process entitlements, pointer authentication, arm64e, or memory tagging - After enabling Enhanced Security, the link step fails with errors that mention
arm64e - A plugin author wants stricter warnings or static analysis for plugin Swift/ObjC/C code
- The user wants "Build and Analyze" /
xcodebuild analyzein CI
Do not use:
- ATS, TLS pinning, signing, secrets, WebView config, Capsec scans:
capacitor-security - App Store privacy manifest and review checklist:
capacitor-apple-review-preflight - The AppDelegate to SceneDelegate migration:
capacitor-uiscene-migration - Android R8, network security config:
capacitor-security
Facts that change the plan
- Build settings do not cross project boundaries. Settings on the App target do not apply to Pods (
ios/App/Pods/Pods.xcodeproj), to SPM packages (plugins,CapApp-SPM), or to the Cordova plugin package thatnpx cap syncgenerates. Hardening plugin code is done in the plugin repo (podspec / Package.swift), not in the app. - The App target of a stock Capacitor app is pure Swift (
AppDelegate.swift,SceneDelegate.swift). Clang warnings and analyzer checkers only matter if the app target has.m,.mm,.cor.cppfiles. Detect languages before proposing them. - The Capacitor 8 templates already set three Stage A warnings at project level (
GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR,GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE,GCC_WARN_64_TO_32_BIT_CONVERSION = YES). Report them as already hardened. Do not re-add them. - WKWebView content is not affected. JavaScript and JIT run in WebKit's own processes. Enhanced Security entitlements apply to the app process and the native code linked into it (Capacitor runtime, plugins, SDKs).
- Pointer authentication adds an
arm64eslice to device builds. Every binary linked into the app must also havearm64e, or the link fails. This is the main breakage risk in Capacitor apps. See references/enhanced-security.md. - Do not edit generated files.
ios/App/Pods/**,Pods-App.*.xcconfig,ios/App/CapApp-SPM/Package.swift,ios/capacitor-cordova-ios-plugins/**andios/debug.xcconfig(SPM template, Debug only, CLI-managed) are rewritten by CocoaPods ornpx cap sync. Put settings in the App project (Xcode Build Settings, which writesproject.pbxproj) or in an xcconfig the team already owns. - The user owns the result. Enhanced Security turns latent memory bugs into crashes. Report findings and get approval before changing anything. Test on real hardware before shipping.
References
Only load a reference when its topic is in play.
| File | Load when |
|---|---|
| references/settings-catalog.md | Building the audit table: every tracked setting, its hardened value, language scope, risk |
| references/reading-build-settings.md | Running xcodebuild -showBuildSettings, using the audit script, telling "explicitly disabled" from "default off" |
| references/enhanced-security.md | Enabling the Enhanced Security capability, entitlements, pointer authentication with CocoaPods/SPM/binary SDKs, memory tagging |
| references/plugin-authors.md | Hardening plugin code: podspec pod_target_xcconfig, Package.swift warning settings, analyzing a plugin repo, shipping arm64e xcframeworks |
| references/decision-log.md | Creating or updating the team's decision document |
Script: scripts/audit-build-settings.mjs filters xcodebuild -showBuildSettings -json output to the tracked settings and marks each as hardened, default, or explicitly set (when given the pbxproj).
Workflow
1. Brief and check source control
Tell the user in two or three sentences: you will audit first, write a plan, and change nothing until they approve. If the project has no git, recommend committing first. Stop if they decline.
2. Discover (read-only)
- Confirm the iOS project:
ios/App/App.xcodeprojexists. Note SPM (ios/App/CapApp-SPM/) vs CocoaPods (ios/App/Podfile,App.xcworkspace). - Read the Capacitor version from
package.json(@capacitor/ios). Capacitor 8 deploys to iOS 15, Capacitor 9 to iOS 16 and needs Xcode 27. - Detect languages in the App target folder:
find ios/App/App -name '*.m' -o -name '*.mm' -o -name '*.c' -o -name '*.cpp'. Also rungrep -E 'sourcecode\.cpp\.' ios/App/App.xcodeproj/project.pbxprojto catch files whose type was overridden to C++/ObjC++. - List native dependencies that ship binaries: xcframeworks in
node_modules/**/ios/**,binaryTargetin pluginPackage.swiftfiles,vendored_frameworksin podspecs. - Look for an existing decision document (
ios/xcode-security-settings.mdor similar) and read prior decisions. - Read evaluated settings for Debug and Release (see references/reading-build-settings.md):
xcodebuild -showBuildSettings -json -project ios/App/App.xcodeproj -target App -configuration Release > /tmp/app-release.json
node <skill>/scripts/audit-build-settings.mjs /tmp/app-release.json --pbxproj ios/App/App.xcodeproj/project.pbxproj
- Read the entitlements file at the evaluated
CODE_SIGN_ENTITLEMENTSpath. The stock template has none; that is normal.
3. Build the plan and ask
Write the plan into the chat (or a file the user names). Group it by stage. Show only items that apply:
| Stage | Items | Default |
|---|---|---|
| A. Compiler warnings | The five security warnings, only if C/ObjC/C++ is present in the target | on |
| B. Static analyzer | The security checkers plus the clang-tidy check; analyzer runs only on Analyze, so no build risk | on |
| C. Enhanced Security | Capability at project level, entitlements on the App target, pointer authentication with the dependency plan | on, after the dependency check |
| D. Memory tagging | checked-allocations + soft-mode | off, offer |
| E. Extra diagnostics | The noisier warnings | off, offer |
| F. Disabled settings | Ask about each explicit = NO that has no documented reason | on |
Ask the user to approve, edit or cancel. Real judgement calls to put to the user:
- A binary SDK with no
arm64eslice: turn pointer authentication off on the App target (keeps the rest of Enhanced Security) or wait for the vendor. - CocoaPods: add a
post_installhook that enables pointer authentication on pod targets, or turn it off on the App target. - Memory tagging: only with a plan to test on capable hardware.
4. Apply, one stage at a time
- Apply settings at the project level of
App.xcodeprojso every target inherits them, unless the setting is per target (entitlements, pointer-authentication opt-out). - Best path: ask the user to set them in Xcode (project > Build Settings > All). Then verify with
greponproject.pbxproj. If you editproject.pbxprojyourself, edit only thebuildSettingsdictionaries of the project's own Debug and ReleaseXCBuildConfigurationentries (the ones listed by the PBXProjectbuildConfigurationList), keep theKEY = VALUE;syntax, and re-run-showBuildSettingsto confirm. - Add Enhanced Security through Signing & Capabilities > + Capability > Enhanced Security on the App target. This creates or updates
App.entitlementsand wiresCODE_SIGN_ENTITLEMENTS. Details: references/enhanced-security.md. - After each stage, build (step 5) before starting the next one. If a stage breaks the build, revert that stage, record why in the decision log, and continue.
5. Verify
# Sync, then build for a device (arm64e only exists for device SDKs)
npx cap sync ios
xcodebuild -project ios/App/App.xcodeproj -scheme App -configuration Release \
-destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO build
# CocoaPods projects: use -workspace ios/App/App.xcworkspace instead of -project
# Static analyzer
xcodebuild -project ios/App/App.xcodeproj -scheme App -configuration Debug \
-destination 'generic/platform=iOS Simulator' analyze
# Confirm the slices of the built app binary
lipo -archs ~/Library/Developer/Xcode/DerivedData/App-*/Build/Products/Release-iphoneos/App.app/App
- Re-run the audit script. Every approved setting shows as hardened.
- Simulator builds keep working: simulator SDKs have no
arm64e, and the build system drops it. Do not add a simulator-only opt-out. - Run the app on a real device. Check launch, plugin calls, and the JS
pause/resumeevents. With memory tagging in soft mode, collect the simulated crash reports from Xcode Organizer or the device logs (ios-android-logs).
6. Report and record
Report: what was enabled, what was already hardened, what was skipped and why, which dependencies block arm64e, and the action item to test on hardware before release. Then update the decision document (references/decision-log.md).
Error Handling
| Symptom | Cause | Fix |
|---|---|---|
Link fails with messages that mention arm64e after enabling Enhanced Security | A pod, SPM package or xcframework was built without arm64e | Find it with lipo -archs. Source pods: post_install hook. SPM source packages: workspace setting iOSPackagesShouldBuildARM64e. Binary with no slice: ENABLE_POINTER_AUTHENTICATION = NO on the App target and ask the vendor. See references/enhanced-security.md |
Sandbox: rsync(...) deny(1) file-write-create in [CP] Embed Pods Frameworks | ENABLE_USER_SCRIPT_SANDBOXING = YES with CocoaPods script phases | Keep it NO on the App target while on CocoaPods, record the reason, revisit after the SPM migration (cocoapods-to-spm) |
| New warnings flood after Stage A | Warnings were off before | Fix real bugs first. If a warning is in generated or vendored code, keep it on and defer that code; never flip -Werror for the whole project |
Settings changed but -showBuildSettings shows the old value | Set on the wrong level, or a target-level value overrides the project | Check the target column in Xcode; remove the target override if it has no reason |
| App crashes at launch only on newer devices after memory tagging | Soft mode was turned off too early, or a native library has a memory bug | Re-enable soft mode, collect reports, fix or update the library (often bundled C code such as zip or SQLite) |
Edits vanished after npx cap sync or pod install | A generated file was edited | Move the setting to the App project or to the plugin's own podspec / Package.swift |
Related Skills
capacitor-security: ATS, signing, secrets, WebView and storage securitycocoapods-to-spm: SPM removes most pod-related hardening frictioncapacitor-plugin-spm-support: Package.swift layout for pluginsios-android-logs: capture crash and memory-tagging reports from devices
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.
Capacitor Security
Audit and harden the app layer of a Capacitor app: secrets in the bundle, on-device storage, network transport, WebView and native bridge exposure, and platform manifests.
When to Use
TRIGGER when:
- The user asks for a security audit, OWASP Mobile Top 10 / MASVS review, or wants to fix pentest findings.
- The user wants to run or interpret
@capgo/capgo-sec(capsec) results, rule IDs such asSEC001,STO002,NET003,CAP004,AND004,IOS001. - API keys, service-role keys, or
.envvalues appear insrc/,dist/,www/, orcapacitor.config.*. - Auth tokens are stored with
Preferences.set,localStorage, IndexedDB, or plain SQLite. capacitor.config.*containsserver.cleartext: true,server.url, broadserver.allowNavigation,android.allowMixedContent, orwebContentsDebuggingEnabled: true.- Native files contain
NSAllowsArbitraryLoads,android:usesCleartextTraffic="true",android:allowBackup="true",android:debuggable, or exported components without permissions. - The user needs certificate pinning, a Content Security Policy, screenshot protection, or root/jailbreak detection.
Do not use:
- Xcode build settings, Enhanced Security, pointer authentication, stack/heap hardening ->
capacitor-ios-security-hardening. - Universal Links / App Links setup ->
capacitor-deep-linking(this skill only covers validating incoming URLs). - Privacy manifests, App Review rejections ->
capacitor-apple-review-preflight; store listing ->capacitor-app-store. - Pipeline structure and signing secrets in CI ->
capacitor-ci-cd. - Live update installation and channels ->
capgo-live-updates(this skill covers only bundle encryption). - Runtime crashes and WebView inspection ->
debugging-capacitor.
Workflow
- Inspect before editing. Read
capacitor.config.ts|json,package.json(Capacitor major, installed plugins),android/app/src/main/AndroidManifest.xml,android/app/src/main/res/xml/network_security_config.xml(if any),ios/App/App/Info.plist,*.entitlements, andindex.html. - Scan. Run the Capgo scanner from the project root (Node 18+):
The npm package isnpx @capgo/capgo-sec@latest scan --severity medium@capgo/capgo-sec; it installs acapsecbinary.npx capsecdoes not work because no package namedcapsecexists on npm. - Grep for what scanners miss (see Verification). Build the web app first and also grep
dist/orwww/: bundlers inlineimport.meta.env.*andprocess.env.*values. - Triage and report before invasive changes. Group findings by Critical/High/Medium/Low with file and line. Ask the user before changes that alter behavior: certificate pinning (can lock out users when certs rotate), blocking rooted devices, removing
allowNavigationhosts, a strict CSP. - Fix by area, loading the matching reference below.
- Re-run the scan and Verification checks, then
npx cap syncand test a release build on a device.
Capacitor-specific traps
- Nothing in the bundle is secret. Web assets ship inside the IPA/APK and
capacitor.config.jsonis copied into native assets. Values inplugins.*config (including@capgo/capacitor-env) are extractable. Move secret-bearing calls to a backend. allowNavigationgrants bridge access. On Android, everyallowNavigationentry is added to the bridge's allowed origin rules, so pages from those hosts can call your native plugins. Only list hosts you control. Open third-party pages with@capacitor/browseror@capgo/inappbrowserinstead.server.urlandserver.cleartextare dev-only. Capacitor documents both as "not intended for use in production." A committed LAN IP ships a WebView that loads remote code over HTTP.- Debuggable WebView in release.
ios.webContentsDebuggingEnabled/android.webContentsDebuggingEnableddefault to on only in debug builds. A hardcodedtrueexposes the WebView to Safari /chrome://inspecton any release build. - CapacitorHttp is not pinning.
plugins.CapacitorHttp.enabledonly routesfetch/XHR through native networking. Pinning requires@capgo/capacitor-ssl-pinning, which hooks into CapacitorHttp. - Biometric prompt is not authentication.
verifyIdentity()can be hooked on rooted/jailbroken devices. Keep secrets behindaccessControl(hardware-bound Keychain/Keystore item) and validate sessions server-side. - OAuth via custom schemes needs PKCE. Any app can register
myapp://. Use PKCE and prefer Universal/App Links for redirects. - Live update bundles are public unless encrypted. Private channels limit who receives a bundle. They do not make it confidential.
References
Only load a reference when its topic is in play.
| Reference | Load when |
|---|---|
| references/capsec-scanner.md | Running the scanner, reading rule IDs, CI gating, JSON/HTML reports |
| references/secrets-and-storage.md | Hardcoded keys, .env leakage, token storage, Keychain/Keystore, encrypted SQLite, logging |
| references/network.md | HTTPS/ATS/cleartext, network_security_config.xml, certificate pinning, CORS vs CapacitorHttp |
| references/webview-and-bridge.md | CSP, allowNavigation, iframes, postMessage, eval, deep link/OAuth validation |
| references/platform-hardening.md | AndroidManifest flags, R8, iOS Info.plist/entitlements, screenshot protection, root/jailbreak detection, live update encryption |
Xcode compiler/linker hardening is not covered here: use capacitor-ios-security-hardening.
Verification
Run from the project root. Each grep should return nothing for a release build, or only intentional, documented hits.
# 1. Scanner gate (exit code 1 on high/critical)
npx @capgo/capgo-sec@latest scan --ci
# 2. Dev-only config left in capacitor.config
grep -nE "cleartext|server:\s*\{|\"url\"|url:|allowMixedContent|webContentsDebuggingEnabled" capacitor.config.*
# 3. Secrets in the built bundle (filenames only; never print matching values)
npm run build
grep -rlE "sk_live_|sk-ant-|sk-proj-|AKIA[0-9A-Z]{16}|service_role|-----BEGIN (RSA |EC )?PRIVATE KEY" dist/ www/ 2>/dev/null
# 4. Tokens in plain storage
grep -rnE "(Preferences\.set|localStorage\.setItem)\(.*(token|password|secret|jwt)" -i src/
# 5. Android manifest flags
grep -nE "usesCleartextTraffic|allowBackup|debuggable|exported=\"true\"" android/app/src/main/AndroidManifest.xml
# 6. iOS transport and file sharing
plutil -p ios/App/App/Info.plist | grep -E "NSAllowsArbitraryLoads|NSExceptionAllowsInsecureHTTPLoads|UIFileSharingEnabled|LSSupportsOpeningDocumentsInPlace"
# 7. Native projects pick up config changes
npx cap sync
Then install a release build on a device and confirm: login works, API calls succeed (pinning did not break them), Safari Web Inspector / chrome://inspect cannot attach.
Error handling
| Error | Cause | Fix |
|---|---|---|
net::ERR_CLEARTEXT_NOT_PERMITTED (Android) | HTTP request blocked; cleartext is off by default since API 28 | Use HTTPS. For dev live reload only, use server.cleartext: true in a dev-only config. Never ship usesCleartextTraffic="true". |
The resource could not be loaded because the App Transport Security policy requires the use of a secure connection. (iOS, NSURLError -1022) | HTTP URL under ATS | Use HTTPS. If a legacy host is unavoidable, add a narrow NSExceptionDomains entry, never NSAllowsArbitraryLoads. |
... has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present | Backend does not allow the WebView origin | Allow capacitor://localhost (iOS) and https://localhost (Android default) on the server, or enable CapacitorHttp. Do not add Access-Control-Allow-Origin: * to authenticated endpoints. |
Refused to connect to '<url>' because it violates the following Content Security Policy directive | CSP connect-src missing a host | Add the exact API origin to connect-src. Do not fall back to *. |
| Pinned requests fail after a certificate renewal | Pin matched only the old leaf cert | Pin the CA or intermediate plus a backup cert; ship the backup before rotating. |
npm error 404 Not Found - GET https://registry.npmjs.org/capsec | Wrong package name | Use npx @capgo/capgo-sec@latest scan. |
No protected credentials found / No protected data found (code 21, @capgo/capacitor-native-biometric) | Nothing stored with accessControl, fresh install, or the item was invalidated by a biometric enrollment change | Treat as "logged out": re-authenticate against the server, then store again with AccessControl.BIOMETRY_CURRENT_SET or BIOMETRY_ANY. |
Resources
- Capacitor security guide: https://capacitorjs.com/docs/guides/security
- Capgo security scanner: https://capgo.app/security-scanner/ (source: https://github.com/Cap-go/capgo-sec)
- OWASP Mobile Top 10: https://owasp.org/www-project-mobile-top-10/
- OWASP MASVS / MASTG: https://mas.owasp.org/
Testing Capacitor Apps and Plugins
A Capacitor app has three layers to test: the web app (most logic), the native bridge and plugins (Swift/Kotlin), and the running app on a device. Pick the cheapest layer that can catch the bug.
When to Use
TRIGGER when:
- Adding unit, component or E2E tests to a Capacitor app
- Mocking Capacitor or plugin APIs in Vitest / Jest
- Writing or modernizing native unit tests for a plugin (Swift Testing, XCTest, JUnit)
- Verifying a change on a simulator, emulator or device ("test this", "does it work", "check on device")
- E2E tests that cannot find web elements in the app (WebView context)
- Setting up test jobs in CI
Do not use:
- Reading device or crash logs:
ios-android-logs - Safari Web Inspector / Chrome DevTools debugging:
debugging-capacitor - Build, signing and release pipelines:
capacitor-ci-cd - App Intents tests:
capacitor-app-intents(AppIntentsTesting)
Choose the layer
| What changed | Test with | Reference |
|---|---|---|
| Business logic, state, services that call plugins | Vitest with mocked plugins | references/web-unit-tests.md |
| Components (React, Vue, Angular, Svelte) | Testing Library on Vitest | references/web-unit-tests.md |
| Web flows (routing, forms) | Playwright against the dev server or dist | references/e2e.md |
| Plugin native code (Swift / Kotlin) | Swift Testing or XCTest; JUnit | references/native-plugin-tests.md |
| Full app on device, native UI, permissions, deep links | Agent verification loop; Appium or Maestro for repeatable suites | references/device-verification-loop.md, references/e2e.md |
| CI jobs | GitHub Actions matrix | references/ci.md |
Only load a reference when its layer is in play.
Facts that save time
- Plugins in jsdom run their web implementation, or throw
unimplementedwhen there is none.Capacitor.isNativePlatform()returnsfalsein tests unless you mock@capacitor/core. Mock at the plugin package boundary, not deep inside the app. - E2E tools see the WebView as one native element. Appium must switch to the
WEBVIEW_*context to find DOM elements. Capacitor makes the WebView inspectable in debug builds; for release builds setios.webContentsDebuggingEnabled/android.webContentsDebuggingEnabledincapacitor.config. Never ship release builds with it on by accident. - Detox is not an option. It targets React Native and does not drive Capacitor WebView content.
- Swift Testing cannot replace all XCTest. UI tests (XCUIApplication) and
measure {}performance tests stay XCTest. Unit tests can migrate one class at a time; a file can hold both. - iOS-only plugin packages cannot use
swift testbecause they depend on UIKit and Capacitor. Runxcodebuild test -scheme <Package> -destination 'platform=iOS Simulator,...'. - Capacitor 9 removed the deprecated Swift APIs. Tests that build calls with the old
CAPPluginCall(callbackId:options:success:error:)initializer orCAPPlugin(bridge:pluginId:pluginName:)must move toCAPPluginCall(callbackId:methodName:options:success:error:)and a plaininit(). - Live reload flags changed in Capacitor 9. Capacitor 9:
npx cap run ios --url http://<lan-ip>:5173. Capacitor 8:npx cap run ios -l --host <lan-ip> --port 5173. The Ionic CLI'sionic cap run ios -l --externalis a different tool.
Workflow
- Inspect. Read
package.json(test runner, framework,@capacitor/*versions),capacitor.config.*, existing test config (vitest.config.*,playwright.config.*,wdio.conf.*,.maestro/), and for pluginsPackage.swift, the podspec,ios/Tests/,android/src/test/. - Ask which layer the user wants if the request is general. Suggest the cheapest one that covers the risk.
- Write tests using the matching reference. Follow the project's existing runner and style; do not add a second runner.
- Run them and show the output. A test that was never run is not done.
- For UI-affecting changes, run the device verification loop (references/device-verification-loop.md) and report screenshots and findings.
Verify
# Web layer
npx vitest run
npx playwright test
# Plugin, iOS (from the plugin repo)
xcodebuild test -scheme <PluginPackageName> \
-destination "platform=iOS Simulator,name=$(xcrun simctl list devices available | grep -m1 -o 'iPhone [^(]*' | sed 's/ *$//')"
# Plugin, Android (from the plugin repo)
cd android && ./gradlew test
# App native tests, if the app has a test target
xcodebuild test -project ios/App/App.xcodeproj -scheme App -destination 'platform=iOS Simulator,name=<device>'
# CocoaPods projects: -workspace ios/App/App.xcworkspace
Report: tests added, command run, pass/fail counts, and anything that could not run locally (no simulator, no device, missing Android SDK).
Error Handling
| Symptom | Cause | Fix |
|---|---|---|
"<Plugin>" plugin is not implemented on web in Vitest | Real plugin running in jsdom | vi.mock('<plugin package>') in the setup file |
| Mock ignored, real plugin still called | Mock path differs from the import path, or the mock is registered after import | Mock the exact specifier the app imports. Put vi.mock in setupFiles or at the top of the test file |
Appium cannot find data-testid elements | Still in the NATIVE_APP context | await driver.switchContext(webviewContext) after waiting for getContexts() to list a WEBVIEW_* entry |
No WEBVIEW_* context | WebView not inspectable (release build) | Use a debug build, or enable webContentsDebuggingEnabled for the test build only |
| Android WebView context fails with a chromedriver version error | Chromedriver does not match the device WebView | Enable Appium's chromedriver autodownload (an insecure feature flag) or pin a matching chromedriver; check the Appium UiAutomator2 docs |
No such module 'Testing' | Old Xcode | Swift Testing needs the Xcode 16+ toolchain. Capacitor 9 needs Xcode 27 anyway |
error: no such module 'UIKit' from swift test | macOS host build of an iOS package | Use xcodebuild test with an iOS Simulator destination |
'init(callbackId:options:success:error:)' is deprecated / unavailable | Old test helper | Add methodName: |
Live reload: error: unknown option '-l' | Capacitor 9 CLI | Use --url http://<lan-ip>:<port> |
| Live reload app shows a blank page | Dev server bound to localhost, or wrong IP | Bind to 0.0.0.0 (Vite: --host), use the LAN IP, same Wi-Fi |
Related Skills
debugging-capacitor: inspect the WebView and native debuggersios-android-logs: stream logs during device runscapacitor-ci-cd: build and release pipelinescapacitor-ios-resizability: what to check in resized windows during device runscapacitor-plugin-upgrade-v8-to-v9: plugin API removals that affect test helpers
Debugging Capacitor Apps
Find which layer is broken (web, bridge, native, OS config), prove it with the right inspector, then fix the smallest thing.
When to Use
TRIGGER when:
- App shows a white/blank screen, crashes on launch, or freezes after a native call.
- Error
"<Name>" plugin is not implemented on ios|androidor"<Name>.<method>()" is not implemented on .... - Network calls fail on device only:
net::ERR_CLEARTEXT_NOT_PERMITTED, ATS "requires the use of a secure connection", CORS errors. - Permission prompts never appear or always deny.
- Live reload (
cap run --url,server.url) shows a blank page or "Webpage not available". - After updating to Capacitor 8.5+ / Xcode 27:
appUrlOpensilent, universal links open the app but do nothing, JSpause/resumeor custom AppDelegate code no longer runs. - User asks "how do I debug / inspect my Capacitor app".
Do not use:
- Only need to stream, filter, or save logs or crash reports ->
ios-android-logs. - Performing the AppDelegate -> SceneDelegate migration itself ->
capacitor-uiscene-migration. - Setting up deep links, AASA, assetlinks from scratch ->
capacitor-deep-linking. - Jank, slow startup, bundle size, memory tuning ->
capacitor-performance. - Sentry / Crashlytics / Datadog in production ->
capacitor-native-observability. - Writing unit/E2E tests ->
capacitor-testing. AI/MCP device automation ->capacitor-mcp. - Gradle/Xcode build failures from version bumps ->
capacitor-app-upgrades; Pods/SPM resolution ->cocoapods-to-spm. - Push token/delivery issues ->
capacitor-push-notifications; keyboard overlap ->capacitor-keyboard; notch/insets ->safe-area-handling.
Triage Workflow
- Collect facts before touching code: platform(s), simulator vs device, debug vs release, Capacitor version (
npx cap doctor), what changed last (upgrade, plugin added, config edit), exact error text. - Classify the layer:
- JS exception, failed fetch, bad route -> web layer: open the WebView inspector (Safari /
chrome://inspect). Seereferences/webview-inspection.md. plugin is not implemented-> bridge/registration: the native code is not in the binary or JS cannot be injected. See Error Handling below.- Process dies /
EXC_BAD_ACCESS/FATAL EXCEPTION-> native layer: run from Xcode / Android Studio with the debugger attached. Seereferences/native-debugging.md. - Works on Android but not iOS after 8.5/Xcode 27, link/lifecycle related -> UIScene. See
references/uiscene-regressions.md.
- JS exception, failed fetch, bad route -> web layer: open the WebView inspector (Safari /
- Reproduce with a fresh sync:
npm run build && npx cap syncthen rebuild native. Stalepublic/assets and un-synced plugins cause most "works in browser, broken on device" reports. - Read the native console for Capacitor's own messages. iOS prints
⚡️ Loading app at ...,⚡️ [log] - ...,⚡️ ERROR: Unable to load ...to stdout (visible in Xcode's console,simctl launch --console-pty,devicectl ... launch --console; not in Console.app). Android logs under tagCapacitorand JS console underCapacitor/Console. Log commands live inios-android-logs. - Report the root cause and proposed fix to the user before invasive changes (deleting
ios//android/, editingproject.pbxproj, disabling ATS globally). - Apply the fix, then run the Verification steps.
Tool Matrix
| Need | iOS | Android |
|---|---|---|
| Inspect DOM/JS/network | Safari > Develop > device > app | chrome://inspect/#devices |
| Native breakpoints | Xcode (npx cap open ios), LLDB | Android Studio debugger (npx cap open android) |
| Run on target from CLI | npx cap run ios --target <id> | npx cap run android --target <id> |
| List targets | npx cap run ios --list | npx cap run android --list |
| Open URL / deep link | xcrun simctl openurl booted <url>; device: xcrun devicectl device process openURL --device <id> <url> | adb shell am start -W -a android.intent.action.VIEW -d "<url>" <appId> |
| Reset/grant permissions (sim) | xcrun simctl privacy booted reset all <appId> | adb shell pm revoke <appId> android.permission.CAMERA / adb shell pm clear <appId> |
| Fake push (sim) | xcrun simctl push booted <appId> payload.json | send a real FCM message |
| Launch with stdout | xcrun simctl launch --console-pty booted <appId>; device: xcrun devicectl device process launch --console --device <id> <appId> | adb logcat |
| Profile | Instruments / xcrun xctrace record --template 'Time Profiler' | Android Studio Profiler |
Details and caveats: references/device-cli.md.
Live Reload Quick Path
- Capacitor 9 (
@next):npx cap run ios --url http://192.168.1.68:5173. The old-l/--live-reload,--host,--port,--httpsflags are removed. - Capacitor 8.5 (stable):
npx cap run ios -l --host 192.168.1.68 --port 5173(add--httpsfor an https dev server). - Android emulator/USB:
--forwardPorts 5173:5173runsadb reversesohttp://localhost:5173works. - Dev server must bind to
0.0.0.0; phone and Mac on the same Wi-Fi; iOS may ask for Local Network access; if denied the page never loads (re-enable in Settings > Privacy & Security > Local Network). - Never ship
server.url/server.cleartextincapacitor.config.*; grep before release.
Error Handling
| Error / symptom | Likely cause | Fix |
|---|---|---|
"Foo" plugin is not implemented on ios | Plugin not in native project, or JS injection blocked | npm i <plugin> -> npx cap sync ios. SPM: check ios/App/CapApp-SPM/Package.swift lists it; CocoaPods: check ios/App/Podfile. Remove WKAppBoundDomains from Info.plist or set ios.limitsNavigationsToAppBoundDomains: true. |
"Foo" plugin is not implemented on android | Gradle not synced, or a service worker intercepts the page | npx cap sync android, then File > Sync Project with Gradle Files. Disable/unregister service workers in the native build. |
"Foo.bar()" is not implemented on web | Calling a native-only method in the browser | Guard with Capacitor.isNativePlatform() / Capacitor.isPluginAvailable('Foo'). |
⚡️ ERROR: Unable to load .../index.html / white screen | webDir wrong or never copied | Build web, verify webDir matches output folder, npx cap copy. |
| White screen, no native error | JS crash before first render, or bad <base href> / absolute asset paths | Inspect WebView console; use relative/root paths that resolve under capacitor://localhost / https://localhost. |
net::ERR_CLEARTEXT_NOT_PERMITTED | Android blocks HTTP (API 28+) | Use HTTPS. For dev only: server.cleartext: true or a network_security_config.xml scoped to the dev host. |
| "The resource could not be loaded because the App Transport Security policy requires the use of a secure connection." | iOS ATS | Use HTTPS. For dev only: NSExceptionDomains for the dev host, not global NSAllowsArbitraryLoads. |
| CORS error from API on device only | Origin is capacitor://localhost (iOS) / https://localhost (Android) | Allow those origins server-side, or enable CapacitorHttp (plugins.CapacitorHttp.enabled: true) to route fetch/XHR natively. |
Crash on permission request (iOS, This app has crashed because it attempted to access privacy-sensitive data without a usage description) | Missing NS*UsageDescription | Add the key to ios/App/App/Info.plist. |
Permission always denied on Android | Missing <uses-permission> or user chose "Don't allow" twice | Add to AndroidManifest.xml; guide user to settings. |
No such module 'Capacitor' (Xcode) | Opened .xcodeproj with CocoaPods, or SPM packages not resolved | Pods: open App.xcworkspace, npx cap sync ios. SPM: File > Packages > Reset Package Caches. Deeper -> cocoapods-to-spm. |
Unable to boot device in current state: Booted | Simulator already running | Not an error; use booted as the device id. |
appUrlOpen / universal links silent on iOS only after 8.5 | AppDelegate open url / continue userActivity no longer called | See references/uiscene-regressions.md. |
JS pause/resume stop firing | Custom SceneDelegate missing proxy forwarding, or logic left in applicationDidEnterBackground | See references/uiscene-regressions.md. |
More symptom-specific fixes: references/common-failures.md.
Verification
After any fix, prove it:
npx cap doctorshows matching@capacitor/core,cli,ios,androidversions.npm run build && npx cap synccompletes with no warnings about missing plugins.- Native console shows
⚡️ Loading app at capacitor://localhost...(iOS) / noCapacitor/Consoleerrors (Android). - WebView inspector console is clean on launch.
- Re-run the exact repro on both a simulator/emulator and a physical device, in a release build if the bug was release-only (
cap runbuilds Debug by default; iOS accepts--configuration Release, Android release builds go through Android Studio or Gradle). - For link/lifecycle fixes: test cold (app killed) and warm (app backgrounded) launch with
simctl openurl/adb shell am start, and background/foreground once to seepauseandresume. - Before shipping:
grep -n "server" capacitor.config.*shows nourl/cleartextleft over.
References
Only load a reference when its topic is in play.
| File | Load when |
|---|---|
references/webview-inspection.md | Attaching Safari/Chrome inspectors, inspector shows no app, debugging release builds, early-startup JS errors |
references/native-debugging.md | Native crash, breakpoints in plugins, LLDB, Android Studio debugger, Instruments/xctrace, memory leaks |
references/device-cli.md | Driving simulators/devices from the terminal: install, launch, open URLs, permissions, push, app containers |
references/uiscene-regressions.md | iOS deep links, universal links, cold-start URL, pause/resume, or AppDelegate code broken after Capacitor 8.5 / Xcode 27 |
references/common-failures.md | Detailed fixes for white screen, plugin not implemented, networking, permissions, live reload |
Resources
iOS and Android Logs for Capacitor Apps
Pick the log channel that actually carries the message you need, filter to the app, capture to a file, hand off to diagnosis.
When to Use
TRIGGER when:
- User asks how to view, stream, filter, or save device/simulator logs.
console.logoutput or⚡️Capacitor lines are missing on iOS/Android.- User needs a crash report (
.ips, tombstone, ANR) from a device or simulator. - Logcat or the unified log is too noisy; user wants only their app or plugin.
- A log command fails or misbehaves:
--level errorstill shows everything,unable to find utility "devicectl",Error: Unexpected argument 'log',adb: no devices/emulators found.
Do not use:
- Interpreting the error and fixing the app ->
debugging-capacitor. - Production crash/ANR reporting (Sentry, Crashlytics, Datadog) ->
capacitor-native-observability. - AI agent log streaming via MCP servers ->
capacitor-mcp. - CPU/memory profiling ->
capacitor-performance. - UIScene lifecycle migration ->
capacitor-uiscene-migration.
Where Capacitor Output Goes (the main trap)
| Source | iOS | Android |
|---|---|---|
Capacitor bridge messages (⚡️ Loading app at ..., ⚡️ To Native ->, errors) | stdout only (print) | logcat tag Capacitor and Capacitor/<Sub> |
JS console.log/warn/error mirrored natively | stdout as ⚡️ [log] - ... | logcat tag Capacitor/Console as File: ... - Line N - Msg: ... |
| JS console, full fidelity (objects, stack traces) | Safari Web Inspector | chrome://inspect |
Plugin/app code using os.Logger / NSLog | unified log (Console.app, log stream) | n/a |
Plugin code using android.util.Log / Capacitor Logger | n/a | logcat |
| Native crash | .ips crash report | FATAL EXCEPTION in logcat + crash buffer; tombstone for native code |
Consequences:
- On iOS, Console.app and
log streamwill not show Capacitor's⚡️lines or mirrored JS console. Use Xcode's console,xcrun simctl launch --console-pty, orxcrun devicectl device process launch --console. - Mirroring obeys
loggingBehavior(none|debug|production, defaultdebug): Release builds produce no Capacitor logs unless set toproduction. - The iOS process name is the executable (
Appin the Capacitor template), not the display name. Filter withprocess == "App".
Quick Commands
# iOS Simulator: Capacitor + JS console (stdout), relaunching the app
xcrun simctl launch --console-pty --terminate-running-process booted com.example.app
# iOS Simulator: unified log for the app (os_log / NSLog / system messages)
xcrun simctl spawn booted log stream --level debug --predicate 'process == "App"'
# iPhone: install + launch with stdout attached (Xcode 15+ devicectl)
xcrun devicectl list devices
xcrun devicectl device process launch --console --terminate-existing --device <id> com.example.app
# iPhone: unified log snapshot of the last 10 minutes
sudo log collect --device-udid <udid> --last 10m --output /tmp/iphone.logarchive
log show /tmp/iphone.logarchive --predicate 'process == "App"' --info --debug
# Android: only this app (re-run after each app restart, PID changes)
adb logcat --pid="$(adb shell pidof -s com.example.app)"
# Android: Capacitor + JS console only
adb logcat -s Capacitor:V Capacitor/Console:V
# Android: crashes only
adb logcat -b crash
Procedure
- Identify target: Simulator/emulator vs physical device; Debug vs Release; which layer emitted the message (table above).
- Check connectivity:
xcrun simctl list devices booted,xcrun devicectl list devices(device must be unlocked, trusted, Developer Mode on),adb devices -l. - Clear and reproduce:
adb logcat -con Android; on iOS start the stream before relaunching the app. - Filter early by process/PID, then by subsystem/tag, then by text. Never paste unfiltered system logs into a conversation.
- Save to a file (
> app.log,.logarchive,adb bugreport) when the user needs to share it; redact tokens, emails, and auth headers before sharing outside the team. - Hand off the relevant lines to
debugging-capacitorfor root-cause work.
Error Handling
| Message | Fix |
|---|---|
--level error still shows every message | log stream --level only understands default, info, debug (it sets the floor, not a ceiling). Filter errors with --predicate 'messageType == error OR messageType == fault'. |
xcrun: error: unable to find utility "devicectl" | Active dev dir is Command Line Tools. sudo xcode-select -s /Applications/Xcode.app/Contents/Developer. |
Error: Unexpected argument 'log' (devicectl) | devicectl has no log streaming subcommand. Use --console for stdout, Console.app or log collect --device-udid for unified logs. |
log collect fails with a permission error | Run with sudo; device must be unlocked and trusted. |
No devices are booted. (simctl) | xcrun simctl boot "<device name>" or open Simulator. |
adb: no devices/emulators found / unauthorized | Enable USB debugging, accept the RSA prompt, adb kill-server && adb start-server. |
adb logcat --pid= prints everything / errors | App not running so pidof returned nothing. Launch the app first. |
No Capacitor/Console lines on Android | loggingBehavior: 'none', or Release build with default debug. |
JS logs show but objects print as [object Object] | Native mirroring stringifies; use the WebView inspector for structured output. |
Verification
- iOS sim: launch with
--console-pty, see⚡️ Loading app at capacitor://localhostand a testconsole.log('log-check')as⚡️ [log] - log-check. - iOS device: same via
devicectl device process launch --console. - Android:
adb logcat -s Capacitor/Console:VshowsMsg: log-check. - Unified log: a plugin
Logger(subsystem: "com.example.app", category: "test").info("log-check")appears with--predicate 'subsystem == "com.example.app"' --level info.
References
Only load a reference when its topic is in play.
| File | Load when |
|---|---|
references/ios-logs.md | Unified log predicates, Console.app, log collect/log show, iOS crash reports via devicectl/Xcode, adding os.Logger to a plugin |
references/android-logs.md | logcat buffers/formats/filters, Android Studio Logcat queries, ANRs, tombstones, bugreports, WebView (chromium) noise |
Resources
Sponsors
Details
- Marketplace
- Cap-go/capgo-skills
- Source
- plugins/capacitor-quality
- Author
- Capgo
- Category
- Development
- License
- MIT
- Keywords
- capacitor, testing, debugging, performance, security, xcode-hardening