Cap-go avatar

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-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add Cap-go/capgo-skills.

Contents

Discovered from source

Skills 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-reader or @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.

  1. Inventory screens into a TODO list (auth, main tabs, forms, modals, media, settings). Audit one at a time.
  2. Automated pass on the web build: run axe (@axe-core/playwright in tests, or npx @axe-core/cli@latest http://localhost:5173) and fix violations first (names, roles, contrast, labels).
  3. 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.
  4. Fix Capacitor-specific traps below.
  5. Report findings per screen with WCAG criterion, severity, and fix before large refactors; ask before changing design tokens (colors, font sizes).

Capacitor-Specific Traps

  1. iOS Dynamic Type is ignored by default. WKWebView renders px/rem text at fixed size regardless of Settings > Accessibility > Larger Text. Options:
    • CSS: html { font: -apple-system-body; } and size everything else in rem/em (WebKit maps this to the user's content size category; updates live).
    • Or TextZoom.getPreferred() then TextZoom.set({ value }) from @capacitor/text-zoom on launch and on resume. On iPad this requires ios.preferredContentMode: 'mobile' in capacitor.config.*. Pick one, not both, or text scales twice.
  2. 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 with adb shell settings put system font_scale 2.0 and design for reflow (WCAG 1.4.4, 1.4.10).
  3. Pinch zoom. zoomEnabled defaults to false and many templates ship user-scalable=no. Users can still scale text via traps 1/2; if you rely on zoom instead, set zoomEnabled: true and drop user-scalable=no.
  4. 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 use ScreenReader.speak as the primary mechanism: it only speaks when a screen reader is active and bypasses the user's verbosity settings.
  5. Native views under or over the WebView. @capacitor/google-maps renders 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.
  6. 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 (see references/native.md).
  7. 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.
  8. Motion and contrast. prefers-reduced-motion and prefers-contrast media queries work in both WebViews. Disable parallax/auto-playing transitions under reduce motion; test Increase Contrast.
  9. Status changes. Toasts (@capacitor/toast is native and announced), inline errors, spinners: use role="status" / aria-live="polite" for web toasts and aria-busy on loading regions; use role="alert" only for errors.
  10. 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 on appStateChange/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-large and adb 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/ and grep -rn "outline: *none\|outline: *0" src/ (each must have a :focus-visible replacement).
  • Reset after testing: adb shell settings put system font_scale 1.0, xcrun simctl ui booted content_size large.

Error Handling

Symptom / messageFix
ScreenReader.isEnabled rejects/unavailable on webNot supported on web (screen readers cannot be detected); guard with Capacitor.isNativePlatform().
speak throws on webBrowser lacks SpeechSynthesis; only call on native or feature-detect 'speechSynthesis' in window.
"TextZoom" plugin is not implemented on webtext-zoom is native only; skip on web.
Text zoom has no effect on iPadSet ios.preferredContentMode: 'mobile'.
Text scaled twice on iOSUsing both -apple-system-body and TextZoom; keep one.
VoiceOver reads "button" with no nameIcon-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 analyze in 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 that npx cap sync generates. 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, .c or .cpp files. 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 arm64e slice to device builds. Every binary linked into the app must also have arm64e, 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/** and ios/debug.xcconfig (SPM template, Debug only, CLI-managed) are rewritten by CocoaPods or npx cap sync. Put settings in the App project (Xcode Build Settings, which writes project.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.

FileLoad when
references/settings-catalog.mdBuilding the audit table: every tracked setting, its hardened value, language scope, risk
references/reading-build-settings.mdRunning xcodebuild -showBuildSettings, using the audit script, telling "explicitly disabled" from "default off"
references/enhanced-security.mdEnabling the Enhanced Security capability, entitlements, pointer authentication with CocoaPods/SPM/binary SDKs, memory tagging
references/plugin-authors.mdHardening plugin code: podspec pod_target_xcconfig, Package.swift warning settings, analyzing a plugin repo, shipping arm64e xcframeworks
references/decision-log.mdCreating 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)

  1. Confirm the iOS project: ios/App/App.xcodeproj exists. Note SPM (ios/App/CapApp-SPM/) vs CocoaPods (ios/App/Podfile, App.xcworkspace).
  2. Read the Capacitor version from package.json (@capacitor/ios). Capacitor 8 deploys to iOS 15, Capacitor 9 to iOS 16 and needs Xcode 27.
  3. Detect languages in the App target folder: find ios/App/App -name '*.m' -o -name '*.mm' -o -name '*.c' -o -name '*.cpp'. Also run grep -E 'sourcecode\.cpp\.' ios/App/App.xcodeproj/project.pbxproj to catch files whose type was overridden to C++/ObjC++.
  4. List native dependencies that ship binaries: xcframeworks in node_modules/**/ios/**, binaryTarget in plugin Package.swift files, vendored_frameworks in podspecs.
  5. Look for an existing decision document (ios/xcode-security-settings.md or similar) and read prior decisions.
  6. 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
  1. Read the entitlements file at the evaluated CODE_SIGN_ENTITLEMENTS path. 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:

StageItemsDefault
A. Compiler warningsThe five security warnings, only if C/ObjC/C++ is present in the targeton
B. Static analyzerThe security checkers plus the clang-tidy check; analyzer runs only on Analyze, so no build riskon
C. Enhanced SecurityCapability at project level, entitlements on the App target, pointer authentication with the dependency planon, after the dependency check
D. Memory taggingchecked-allocations + soft-modeoff, offer
E. Extra diagnosticsThe noisier warningsoff, offer
F. Disabled settingsAsk about each explicit = NO that has no documented reasonon

Ask the user to approve, edit or cancel. Real judgement calls to put to the user:

  • A binary SDK with no arm64e slice: turn pointer authentication off on the App target (keeps the rest of Enhanced Security) or wait for the vendor.
  • CocoaPods: add a post_install hook 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.xcodeproj so 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 grep on project.pbxproj. If you edit project.pbxproj yourself, edit only the buildSettings dictionaries of the project's own Debug and Release XCBuildConfiguration entries (the ones listed by the PBXProject buildConfigurationList), keep the KEY = VALUE; syntax, and re-run -showBuildSettings to confirm.
  • Add Enhanced Security through Signing & Capabilities > + Capability > Enhanced Security on the App target. This creates or updates App.entitlements and wires CODE_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 / resume events. 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

SymptomCauseFix
Link fails with messages that mention arm64e after enabling Enhanced SecurityA pod, SPM package or xcframework was built without arm64eFind 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 FrameworksENABLE_USER_SCRIPT_SANDBOXING = YES with CocoaPods script phasesKeep 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 AWarnings were off beforeFix 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 valueSet on the wrong level, or a target-level value overrides the projectCheck the target column in Xcode; remove the target override if it has no reason
App crashes at launch only on newer devices after memory taggingSoft mode was turned off too early, or a native library has a memory bugRe-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 installA generated file was editedMove 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 security
  • cocoapods-to-spm: SPM removes most pod-related hardening friction
  • capacitor-plugin-spm-support: Package.swift layout for plugins
  • ios-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

  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

QuestionTool
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 timeadb shell am force-stop <appId> && adb shell am start -W -n <appId>/.MainActivity (read TotalTime).
Android frame statsadb shell dumpsys gfxinfo <appId> (janky frames %).
Android WebView versionadb 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 / symptomMeaningFix
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 pageRenderer crashed or killedReduce 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 threadMove native work off main thread in custom plugins; profile with Android Studio.
Message from debugger: Terminated due to memory issueiOS jetsam killed the whole appAllocations instrument; reduce image decoding and caches.
Logcat error about the WebView version being below minWebViewVersionDevice WebView too oldAsk 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 as SEC001, STO002, NET003, CAP004, AND004, IOS001.
  • API keys, service-role keys, or .env values appear in src/, dist/, www/, or capacitor.config.*.
  • Auth tokens are stored with Preferences.set, localStorage, IndexedDB, or plain SQLite.
  • capacitor.config.* contains server.cleartext: true, server.url, broad server.allowNavigation, android.allowMixedContent, or webContentsDebuggingEnabled: 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

  1. 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, and index.html.
  2. Scan. Run the Capgo scanner from the project root (Node 18+):
    npx @capgo/capgo-sec@latest scan --severity medium
    
    The npm package is @capgo/capgo-sec; it installs a capsec binary. npx capsec does not work because no package named capsec exists on npm.
  3. Grep for what scanners miss (see Verification). Build the web app first and also grep dist/ or www/: bundlers inline import.meta.env.* and process.env.* values.
  4. 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 allowNavigation hosts, a strict CSP.
  5. Fix by area, loading the matching reference below.
  6. Re-run the scan and Verification checks, then npx cap sync and 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.json is copied into native assets. Values in plugins.* config (including @capgo/capacitor-env) are extractable. Move secret-bearing calls to a backend.
  • allowNavigation grants bridge access. On Android, every allowNavigation entry 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/browser or @capgo/inappbrowser instead.
  • server.url and server.cleartext are 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.webContentsDebuggingEnabled default to on only in debug builds. A hardcoded true exposes the WebView to Safari / chrome://inspect on any release build.
  • CapacitorHttp is not pinning. plugins.CapacitorHttp.enabled only routes fetch/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 behind accessControl (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.

ReferenceLoad when
references/capsec-scanner.mdRunning the scanner, reading rule IDs, CI gating, JSON/HTML reports
references/secrets-and-storage.mdHardcoded keys, .env leakage, token storage, Keychain/Keystore, encrypted SQLite, logging
references/network.mdHTTPS/ATS/cleartext, network_security_config.xml, certificate pinning, CORS vs CapacitorHttp
references/webview-and-bridge.mdCSP, allowNavigation, iframes, postMessage, eval, deep link/OAuth validation
references/platform-hardening.mdAndroidManifest 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

ErrorCauseFix
net::ERR_CLEARTEXT_NOT_PERMITTED (Android)HTTP request blocked; cleartext is off by default since API 28Use 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 ATSUse 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 presentBackend does not allow the WebView originAllow 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 directiveCSP connect-src missing a hostAdd the exact API origin to connect-src. Do not fall back to *.
Pinned requests fail after a certificate renewalPin matched only the old leaf certPin the CA or intermediate plus a backup cert; ship the backup before rotating.
npm error 404 Not Found - GET https://registry.npmjs.org/capsecWrong package nameUse 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 changeTreat as "logged out": re-authenticate against the server, then store again with AccessControl.BIOMETRY_CURRENT_SET or BIOMETRY_ANY.

Resources

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 changedTest withReference
Business logic, state, services that call pluginsVitest with mocked pluginsreferences/web-unit-tests.md
Components (React, Vue, Angular, Svelte)Testing Library on Vitestreferences/web-unit-tests.md
Web flows (routing, forms)Playwright against the dev server or distreferences/e2e.md
Plugin native code (Swift / Kotlin)Swift Testing or XCTest; JUnitreferences/native-plugin-tests.md
Full app on device, native UI, permissions, deep linksAgent verification loop; Appium or Maestro for repeatable suitesreferences/device-verification-loop.md, references/e2e.md
CI jobsGitHub Actions matrixreferences/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 unimplemented when there is none. Capacitor.isNativePlatform() returns false in 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 set ios.webContentsDebuggingEnabled / android.webContentsDebuggingEnabled in capacitor.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 test because they depend on UIKit and Capacitor. Run xcodebuild 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 or CAPPlugin(bridge:pluginId:pluginName:) must move to CAPPluginCall(callbackId:methodName:options:success:error:) and a plain init().
  • 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's ionic cap run ios -l --external is a different tool.

Workflow

  1. Inspect. Read package.json (test runner, framework, @capacitor/* versions), capacitor.config.*, existing test config (vitest.config.*, playwright.config.*, wdio.conf.*, .maestro/), and for plugins Package.swift, the podspec, ios/Tests/, android/src/test/.
  2. Ask which layer the user wants if the request is general. Suggest the cheapest one that covers the risk.
  3. Write tests using the matching reference. Follow the project's existing runner and style; do not add a second runner.
  4. Run them and show the output. A test that was never run is not done.
  5. 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

SymptomCauseFix
"<Plugin>" plugin is not implemented on web in VitestReal plugin running in jsdomvi.mock('<plugin package>') in the setup file
Mock ignored, real plugin still calledMock path differs from the import path, or the mock is registered after importMock the exact specifier the app imports. Put vi.mock in setupFiles or at the top of the test file
Appium cannot find data-testid elementsStill in the NATIVE_APP contextawait driver.switchContext(webviewContext) after waiting for getContexts() to list a WEBVIEW_* entry
No WEBVIEW_* contextWebView not inspectable (release build)Use a debug build, or enable webContentsDebuggingEnabled for the test build only
Android WebView context fails with a chromedriver version errorChromedriver does not match the device WebViewEnable Appium's chromedriver autodownload (an insecure feature flag) or pin a matching chromedriver; check the Appium UiAutomator2 docs
No such module 'Testing'Old XcodeSwift Testing needs the Xcode 16+ toolchain. Capacitor 9 needs Xcode 27 anyway
error: no such module 'UIKit' from swift testmacOS host build of an iOS packageUse xcodebuild test with an iOS Simulator destination
'init(callbackId:options:success:error:)' is deprecated / unavailableOld test helperAdd methodName:
Live reload: error: unknown option '-l'Capacitor 9 CLIUse --url http://<lan-ip>:<port>
Live reload app shows a blank pageDev server bound to localhost, or wrong IPBind to 0.0.0.0 (Vite: --host), use the LAN IP, same Wi-Fi

Related Skills

  • debugging-capacitor: inspect the WebView and native debuggers
  • ios-android-logs: stream logs during device runs
  • capacitor-ci-cd: build and release pipelines
  • capacitor-ios-resizability: what to check in resized windows during device runs
  • capacitor-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|android or "<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: appUrlOpen silent, universal links open the app but do nothing, JS pause/resume or 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

  1. 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.
  2. Classify the layer:
    • JS exception, failed fetch, bad route -> web layer: open the WebView inspector (Safari / chrome://inspect). See references/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. See references/native-debugging.md.
    • Works on Android but not iOS after 8.5/Xcode 27, link/lifecycle related -> UIScene. See references/uiscene-regressions.md.
  3. Reproduce with a fresh sync: npm run build && npx cap sync then rebuild native. Stale public/ assets and un-synced plugins cause most "works in browser, broken on device" reports.
  4. 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 tag Capacitor and JS console under Capacitor/Console. Log commands live in ios-android-logs.
  5. Report the root cause and proposed fix to the user before invasive changes (deleting ios//android/, editing project.pbxproj, disabling ATS globally).
  6. Apply the fix, then run the Verification steps.

Tool Matrix

NeediOSAndroid
Inspect DOM/JS/networkSafari > Develop > device > appchrome://inspect/#devices
Native breakpointsXcode (npx cap open ios), LLDBAndroid Studio debugger (npx cap open android)
Run on target from CLInpx cap run ios --target <id>npx cap run android --target <id>
List targetsnpx cap run ios --listnpx cap run android --list
Open URL / deep linkxcrun 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.jsonsend a real FCM message
Launch with stdoutxcrun simctl launch --console-pty booted <appId>; device: xcrun devicectl device process launch --console --device <id> <appId>adb logcat
ProfileInstruments / 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, --https flags are removed.
  • Capacitor 8.5 (stable): npx cap run ios -l --host 192.168.1.68 --port 5173 (add --https for an https dev server).
  • Android emulator/USB: --forwardPorts 5173:5173 runs adb reverse so http://localhost:5173 works.
  • 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.cleartext in capacitor.config.*; grep before release.

Error Handling

Error / symptomLikely causeFix
"Foo" plugin is not implemented on iosPlugin not in native project, or JS injection blockednpm 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 androidGradle not synced, or a service worker intercepts the pagenpx cap sync android, then File > Sync Project with Gradle Files. Disable/unregister service workers in the native build.
"Foo.bar()" is not implemented on webCalling a native-only method in the browserGuard with Capacitor.isNativePlatform() / Capacitor.isPluginAvailable('Foo').
⚡️ ERROR: Unable to load .../index.html / white screenwebDir wrong or never copiedBuild web, verify webDir matches output folder, npx cap copy.
White screen, no native errorJS crash before first render, or bad <base href> / absolute asset pathsInspect WebView console; use relative/root paths that resolve under capacitor://localhost / https://localhost.
net::ERR_CLEARTEXT_NOT_PERMITTEDAndroid 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 ATSUse HTTPS. For dev only: NSExceptionDomains for the dev host, not global NSAllowsArbitraryLoads.
CORS error from API on device onlyOrigin 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*UsageDescriptionAdd the key to ios/App/App/Info.plist.
Permission always denied on AndroidMissing <uses-permission> or user chose "Don't allow" twiceAdd to AndroidManifest.xml; guide user to settings.
No such module 'Capacitor' (Xcode)Opened .xcodeproj with CocoaPods, or SPM packages not resolvedPods: open App.xcworkspace, npx cap sync ios. SPM: File > Packages > Reset Package Caches. Deeper -> cocoapods-to-spm.
Unable to boot device in current state: BootedSimulator already runningNot an error; use booted as the device id.
appUrlOpen / universal links silent on iOS only after 8.5AppDelegate open url / continue userActivity no longer calledSee references/uiscene-regressions.md.
JS pause/resume stop firingCustom SceneDelegate missing proxy forwarding, or logic left in applicationDidEnterBackgroundSee references/uiscene-regressions.md.

More symptom-specific fixes: references/common-failures.md.

Verification

After any fix, prove it:

  1. npx cap doctor shows matching @capacitor/core, cli, ios, android versions.
  2. npm run build && npx cap sync completes with no warnings about missing plugins.
  3. Native console shows ⚡️ Loading app at capacitor://localhost... (iOS) / no Capacitor/Console errors (Android).
  4. WebView inspector console is clean on launch.
  5. 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 run builds Debug by default; iOS accepts --configuration Release, Android release builds go through Android Studio or Gradle).
  6. 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 see pause and resume.
  7. Before shipping: grep -n "server" capacitor.config.* shows no url/cleartext left over.

References

Only load a reference when its topic is in play.

FileLoad when
references/webview-inspection.mdAttaching Safari/Chrome inspectors, inspector shows no app, debugging release builds, early-startup JS errors
references/native-debugging.mdNative crash, breakpoints in plugins, LLDB, Android Studio debugger, Instruments/xctrace, memory leaks
references/device-cli.mdDriving simulators/devices from the terminal: install, launch, open URLs, permissions, push, app containers
references/uiscene-regressions.mdiOS deep links, universal links, cold-start URL, pause/resume, or AppDelegate code broken after Capacitor 8.5 / Xcode 27
references/common-failures.mdDetailed 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.log output 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 error still 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)

SourceiOSAndroid
Capacitor bridge messages (⚡️ Loading app at ..., ⚡️ To Native ->, errors)stdout only (print)logcat tag Capacitor and Capacitor/<Sub>
JS console.log/warn/error mirrored nativelystdout as ⚡️ [log] - ...logcat tag Capacitor/Console as File: ... - Line N - Msg: ...
JS console, full fidelity (objects, stack traces)Safari Web Inspectorchrome://inspect
Plugin/app code using os.Logger / NSLogunified log (Console.app, log stream)n/a
Plugin code using android.util.Log / Capacitor Loggern/alogcat
Native crash.ips crash reportFATAL EXCEPTION in logcat + crash buffer; tombstone for native code

Consequences:

  • On iOS, Console.app and log stream will not show Capacitor's ⚡️ lines or mirrored JS console. Use Xcode's console, xcrun simctl launch --console-pty, or xcrun devicectl device process launch --console.
  • Mirroring obeys loggingBehavior (none | debug | production, default debug): Release builds produce no Capacitor logs unless set to production.
  • The iOS process name is the executable (App in the Capacitor template), not the display name. Filter with process == "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

  1. Identify target: Simulator/emulator vs physical device; Debug vs Release; which layer emitted the message (table above).
  2. Check connectivity: xcrun simctl list devices booted, xcrun devicectl list devices (device must be unlocked, trusted, Developer Mode on), adb devices -l.
  3. Clear and reproduce: adb logcat -c on Android; on iOS start the stream before relaunching the app.
  4. Filter early by process/PID, then by subsystem/tag, then by text. Never paste unfiltered system logs into a conversation.
  5. 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.
  6. Hand off the relevant lines to debugging-capacitor for root-cause work.

Error Handling

MessageFix
--level error still shows every messagelog 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 errorRun 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 / unauthorizedEnable USB debugging, accept the RSA prompt, adb kill-server && adb start-server.
adb logcat --pid= prints everything / errorsApp not running so pidof returned nothing. Launch the app first.
No Capacitor/Console lines on AndroidloggingBehavior: '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://localhost and a test console.log('log-check') as ⚡️ [log] - log-check.
  • iOS device: same via devicectl device process launch --console.
  • Android: adb logcat -s Capacitor/Console:V shows Msg: 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.

FileLoad when
references/ios-logs.mdUnified log predicates, Console.app, log collect/log show, iOS crash reports via devicectl/Xcode, adding os.Logger to a plugin
references/android-logs.mdlogcat 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

More from Cap-go/capgo-skills

All 11