Capacitor Best Practices#

Review a Capacitor app for structural mistakes that cause broken builds, lost edits, production leaks, and plugin crashes. Route deep topics to the sibling skill that owns them.

When to Use#

TRIGGER when:

• The user asks for a general code/architecture review of a Capacitor or Ionic + Capacitor app.
• Setting up a new Capacitor project or adding iOS/Android to an existing web app.
• capacitor.config.ts|json review: webDir, server.url, cleartext, plugin config, env-specific config.
• Version drift between @capacitor/core, @capacitor/cli, @capacitor/ios, @capacitor/android, or plugin majors that do not match Capacitor's major.
• Plugin usage review: missing npx cap sync, no availability check, no permission flow, matching on error message strings.
• Errors such as "<Plugin>" plugin is not implemented on ios, Could not find the web assets directory, ios platform has not been added yet.
• Pre-release sanity checklist across config, native projects, and live updates.

Do not use:

• Security audit, secrets, storage, pinning, CSP -> capacitor-security; Xcode hardening -> capacitor-ios-security-hardening.
• Bundle size, startup time, memory, bridge profiling -> capacitor-performance.
• Unit/E2E test setup and plugin mocking -> capacitor-testing.
• Crashes, white screen, native logs -> debugging-capacitor, ios-android-logs.
• Major upgrades -> capacitor-app-upgrades (8 -> 9: capacitor-app-upgrade-v8-to-v9).
• CocoaPods -> SPM -> cocoapods-to-spm; UIScene adoption -> capacitor-uiscene-migration.
• Finding or installing a specific plugin -> capacitor-plugins.
• Store submission and review -> capacitor-app-store, capacitor-apple-review-preflight; CI -> capacitor-ci-cd; live updates -> capgo-live-updates.

Current baseline (October 2026)#

CocoaPods Trunk is expected to go read-only on December 2, 2026. Recommend SPM for every app still on CocoaPods. Install Capacitor 9 only with @next until it reaches GA, and do not recommend it for production apps.

Review workflow#

1. Inventory (read-only).
   shell

   npx cap doctor          # installed vs latest Capacitor packages
   npx cap ls              # plugins Capacitor detects per platform
   cat capacitor.config.ts 2>/dev/null || cat capacitor.config.json
   ls ios/App/Podfile ios/App/CapApp-SPM 2>/dev/null   # CocoaPods or SPM
   grep -nE "minSdkVersion|compileSdkVersion|targetSdkVersion" android/variables.gradle

2. For large codebases, write a TODO list of areas (config, versions, plugins, native iOS, native Android, live updates, release) and review one at a time.
3. Report findings before editing, grouped by severity, each with file:line and the fix. Ask before invasive changes (upgrading a major, migrating to SPM, enabling R8, changing appId).
4. Fix, loading the matching reference.
5. Run Verification.

Rules that matter most#

1. Keep Capacitor packages on one version. @capacitor/core, cli, ios, android must match. Plugin majors must match the Capacitor major (official and @capgo/* plugins follow it: v8 plugins for Capacitor 8).
2. npx cap sync after every plugin install/removal and every config change. Missing sync produces "<Plugin>" plugin is not implemented on <platform>.
3. Never edit generated web assets. android/app/src/main/assets/public/ and ios/App/App/public/ are overwritten by cap copy/sync. Edit src/ and rebuild.
4. Commit ios/ and android/. They are source code with your native customizations, not build output. Do commit capacitor.config.*; do not commit node_modules, Pods/, build dirs.
5. No dev settings in release config. server.url, server.cleartext, allowNavigation to dev hosts, webContentsDebuggingEnabled: true. Gate them on an env var (see references/config-and-project.md). On Capacitor 9, use npx cap run <platform> --url <dev-url> for live reload.
6. Feature-detect before calling plugins. Capacitor.isNativePlatform(), Capacitor.getPlatform(), Capacitor.isPluginAvailable('Name'). Provide a web fallback or hide the feature.
7. Use the permission API. Call checkPermissions() then requestPermissions() for official plugins that expose them, and handle denied with a path to Settings. Add the matching NS*UsageDescription keys / Android permissions.
8. Branch on error.code, not error.message. Messages change between versions and platforms. Official plugins expose structured codes (for example OS-PLUG-CAMR-0006 for a cancelled camera capture in @capacitor/camera 8.1+ new APIs); Capacitor core uses UNIMPLEMENTED / UNAVAILABLE.
9. Move large binary data as files, not base64. Pass file paths/URIs across the bridge and render with Capacitor.convertFileSrc().
10. iOS lifecycle is scene-based from Capacitor 8.5. After adopting UIScene, AppDelegate application(_:open:options:), continue userActivity, and foreground/background callbacks stop firing. Move custom native code to SceneDelegate (capacitor-uiscene-migration). Avoid UIScreen.main and idiom-based layout for resizable windows.
11. Live updates: call CapacitorUpdater.notifyAppReady() on every launch, and apply manual updates with next() (on background/relaunch) rather than set() mid-session. Details in capgo-live-updates.
12. Secrets never go in the app. Anything in the bundle or capacitor.config is extractable. Hand off to capacitor-security for anything beyond this rule.

References#

Only load a reference when its topic is in play.

Verification#

# Versions aligned (all @capacitor/* core packages show the same version)
npm ls @capacitor/core @capacitor/cli @capacitor/ios @capacitor/android
npx cap doctor

# Web build exists where webDir points, then sync succeeds without errors
npm run build && npx cap sync

# No dev server or debug flags in the synced native config
grep -nE "\"url\"|cleartext|webContentsDebuggingEnabled" \
  android/app/src/main/assets/capacitor.config.json ios/App/App/capacitor.config.json

# No hand edits in generated web assets (should show nothing)
git status --porcelain android/app/src/main/assets/public ios/App/App/public

# Error handling does not depend on message text
grep -rnE "error\.message\s*(===|==|\.includes)" src/

# Native builds
cd android && ./gradlew assembleRelease && cd ..
xcodebuild -project ios/App/App.xcodeproj -scheme App -configuration Release -destination 'generic/platform=iOS' build CODE_SIGNING_ALLOWED=NO

With CocoaPods, build ios/App/App.xcworkspace with -workspace instead of -project. Finally run on a real device and exercise each plugin-backed feature, including permission denial.

Error handling#

Resources#

• Capacitor docs: https://capacitorjs.com/docs
• Config reference: https://capacitorjs.com/docs/config
• Environment-specific configurations: https://capacitorjs.com/docs/guides/environment-specific-configurations
• Updating to 8.5 (UIScene): https://capacitorjs.com/docs/updating/8-5
• Capgo docs: https://capgo.app/docs/