cap-go/capgo-skills/capacitor-plugins

Capacitor Plugins

Choose the right plugin, install it correctly, and prove it is linked natively.

When to Use

TRIGGER when:

• User asks "which plugin should I use for X?" or compares plugin options.
• User needs a native capability (camera, files, location, biometrics, payments, auth, sensors, storage, media, calendar, contacts, health, on-device LLM).
• A plugin call fails after install: "X" plugin is not implemented on ios|android|web, UNIMPLEMENTED, unable to find plugin, or an OS-PLUG-* code.
• User needs the right Info.plist / AndroidManifest.xml / variables.gradle entries for a plugin.

Do not use (load the sibling skill instead):

• Push notification setup, FCM/APNs keys: capacitor-push-notifications
• Splash screen assets and timing: capacitor-splash-screen
• Keyboard overlap, accessory bar, resize: capacitor-keyboard
• Universal Links / App Links: capacitor-deep-linking
• OTA live updates: capgo-live-updates
• Migrating plugin source code across Capacitor majors: capacitor-plugin-upgrades (and capacitor-plugin-upgrade-v8-to-v9)
• Adding Swift Package Manager support to a plugin: capacitor-plugin-spm-support; moving an app to SPM: cocoapods-to-spm
• AppDelegate/SceneDelegate lifecycle changes: capacitor-uiscene-migration
• Upgrading the app's Capacitor major: capacitor-app-upgrades
• SQL storage migrations: sqlite-to-fast-sql

Version Facts (October 2026)

• Capacitor stable: 8.5.x (latest). Capacitor 9 is 9.0.0-alpha on the next dist-tag. Official plugins follow: most v8 plugins are 8.x on latest and 9.0.0-alpha on next.
• Plugin major must match the app's Capacitor major. Plugins for older majors use latest-<major> tags, e.g. npm install @capacitor/camera@latest-7.
• Some official plugins have independent versions (file-transfer 2.x, file-viewer 2.x, inappbrowser 4.x, privacy-screen 2.x, barcode-scanner 3.x, background-runner 3.x, calendar/contacts/health-fitness 1.x). Check npm view <pkg> peerDependencies instead of matching the number.
• @capgo/* plugins use the Capacitor major as their own major (8.x for Capacitor 8). LTS tags such as lts-v7 exist on some packages.
• Capacitor 9: iOS 16 min, Android minSdk 26. Plugins that previously needed minSdkVersion = 26 (inappbrowser, barcode-scanner) stop needing a bump.

Procedure

1. Inspect first. Read package.json (@capacitor/core version), capacitor.config.*, and check whether iOS uses SPM (ios/App/CapApp-SPM/Package.swift) or CocoaPods (ios/App/Podfile). Run npx cap ls to see what is already linked.
2. Pick the package.

• An official @capacitor/* package exists and covers the need: default to it. Load its reference from the index below.
• No official package, or it lacks a required feature: load references/capgo-plugin-index.md and pick the exact @capgo/* name. State why it fits better.
• Never recommend a package name that is not in a reference file without checking npm view <pkg> version first.

1. Install with the matching major:

``bash npm install @capacitor/<name> # or @capgo/<name> npx cap sync ``

1. Add native config from the reference: usage-description keys, manifest permissions, variables.gradle minSdk/library versions, capabilities/entitlements, AppDelegate hooks. Missing iOS usage strings crash the app on first access.
2. Ask the user before raising minSdkVersion, adding entitlements (HealthKit, Push), or enabling exact alarms: these affect store review and device reach.
3. Verify (next section), then run on a real device for anything involving camera, health, LLM, BLE, or push.

Capgo Plugin Index

references/capgo-plugin-index.md is the complete Capgo plugin source, generated from Cap-go GitHub package.json and src/definitions.ts: npm name, purpose, install command, platforms, key API methods, docs and repo links for every public non-archived package. references/capgo-plugin-catalog.md is the compact table of the same set. Load the index before recommending any @capgo/* package and use the exact name from it.

Regenerate both after Cap-go org changes (repository maintainers only):

GITHUB_TOKEN=$(gh auth token) node scripts/generate-capgo-plugin-index.mjs

Verification

npx cap sync              # must finish without "[error]" lines
npx cap ls                # lists "Found N Capacitor plugins for ios/android"; plugin must appear for each platform

• Android: android/app/capacitor.build.gradle contains implementation project(':capacitor-<name>') and android/capacitor.settings.gradle has the matching include. Then cd android && ./gradlew assembleDebug.
• iOS SPM: ios/App/CapApp-SPM/Package.swift lists the plugin package. iOS CocoaPods: ios/App/Podfile has the pod and pod install succeeded. Build in Xcode or npx cap run ios.
• Grep for leftovers when replacing a plugin: grep -rn "<old-package>" src android ios package.json.
• Feature-detect at runtime: Capacitor.isPluginAvailable('Camera') and Capacitor.getPlatform().

Error Handling

Reference Index

Only load a reference when its plugin is in play.

Official @capacitor/* packages (install, native config, usage, gotchas):

Capgo plugins: references/capgo-plugin-index.md (145 packages: install, platforms, key APIs, docs) and references/capgo-plugin-catalog.md (compact table).

Capgo Quick Picks

Traps:

• Do not install two plugins that own the same native surface (e.g. two in-app browsers or two biometric plugins) without a reason; they can conflict on delegates and manifest entries.
• Firebase: install the individual @capgo/capacitor-firebase-* packages; there is no umbrella @capgo/capacitor-firebase package on npm.
• Cordova plugins still work but on Capacitor 9 they pull in the Cordova runtime; prefer a Capacitor-native equivalent (cordova-to-capacitor).

Resources

• Official plugin docs: https://capacitorjs.com/docs/apis
• Capgo plugin docs: https://capgo.app/docs/plugins/
• Capgo GitHub: https://github.com/Cap-go