capacitor-plugins

Files (43)

• SKILL.md
• metadata.json
• capacitor-action-sheet.md · references/
• capacitor-app-launcher.md · references/
• capacitor-app.md · references/
• capacitor-background-runner.md · references/
• capacitor-barcode-scanner.md · references/
• capacitor-browser.md · references/
• capacitor-calendar.md · references/
• capacitor-camera.md · references/
• capacitor-clipboard.md · references/
• capacitor-contacts.md · references/
• capacitor-cookies.md · references/
• capacitor-device.md · references/
• capacitor-dialog.md · references/
• capacitor-file-transfer.md · references/
• capacitor-file-viewer.md · references/
• capacitor-filesystem.md · references/
• capacitor-geolocation.md · references/
• capacitor-google-maps.md · references/
• capacitor-haptics.md · references/
• capacitor-health-fitness.md · references/
• capacitor-http.md · references/
• capacitor-inappbrowser.md · references/
• capacitor-keyboard.md · references/
• capacitor-local-llm.md · references/
• capacitor-local-notifications.md · references/
• capacitor-motion.md · references/
• capacitor-network.md · references/
• capacitor-preferences.md · references/
• capacitor-privacy-screen.md · references/
• capacitor-push-notifications.md · references/
• capacitor-screen-orientation.md · references/
• capacitor-screen-reader.md · references/
• capacitor-share.md · references/
• capacitor-splash-screen.md · references/
• capacitor-status-bar.md · references/
• capacitor-system-bars.md · references/
• capacitor-text-zoom.md · references/
• capacitor-toast.md · references/
• capacitor-watch.md · references/
• capgo-plugin-catalog.md · references/
• capgo-plugin-index.md · references/

SKILL.md (first lines)

# 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.
3. **Install with the matching major:**

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

4. **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.
5. **Ask the user** before raising `minSdkVersion`, adding entitlements (HealthKit, Push), or enabling exact alarms: these affect store review and device reach.
6. **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):

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

## Verification

```bash
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

| Error | Cause | Fix |
|-------|-------|-----|
| `"Camera" plugin is not implemented on ios` (or `android`/`web`) | Native side not linked, or no web implementation | `npx cap sync`, rebuild the native app (live reload does not pick up new native code), check `npx cap ls`. On web, guard with `Capacitor.isNativePlatform()`. |
| `"Camera.takePhoto()" is not implemented on ios` | Plugin linked but JS and native versions differ, or method is platform-specific | Align JS and native versions, `npx cap sync`, clean build. Check the reference for platform-only methods. |
| `UNIMPLEMENTED` error code | Method not available on this platform/OS version | Branch on platform; see reference "Notes". |
| Android log `unable to find plugin : X` | Plugin class not registered/included | Confirm `capacitor.build.gradle` entry, re-sync, Gradle sync in Android Studio. |
| iOS log `Error loading plugin X for call. Check that the pluginId is correct` | Plugin not in the iOS build | Re-sync; check `Package.swift` (SPM) or Podfile; clean build folder. |
| App crashes on first camera/contacts/calendar/location access (iOS) | Missing `NS*UsageDescription` key | Add the key listed in the reference to `Info.plist`. |
| `Manifest merger failed : uses-sdk:minSdkVersion 24 cannot be smaller than version 26 declared in library [...]` | Plugin needs higher minSdk | Raise `minSdkVersion` in `android/variables.gradle` (ask the user first). |
| `OS-PLUG-*` codes (e.g. `OS-PLUG-CAMR-0003`) | Structured native errors in OutSystems-based official plugins | Look up the code in the plugin reference (camera, file-transfer, calendar, contacts list the common ones). |
| npm `ERESOLVE` peer `@capacitor/core` conflict | Plugin major does not match app major | Install the matching tag (`@latest-7`, `@next` for v9 alpha) or upgrade the app with `capacitor-app-upgrades`. |

## Reference Index

Only load a reference when its plugin is in play.

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

| Need | Reference |
|------|-----------|
| Action sheet | `references/capacitor-action-sheet.md` |
| Open other apps / check installed | `references/capacitor-app-launcher.md` |
| App state, back button, URL open events | `references/capacitor-app.md` |
| JS tasks in background | `references/capacitor-background-runner.md` |
| Barcode / QR scan | `references/capacitor-barcode-scanner.md` |
| OAuth-safe in-app browser (SFSafariViewController / Custom Tabs) | `references/capacitor-browser.md` |
| Calendar events | `references/capacitor-calendar.md` |
| Camera, gallery, video (8.1+ API, `getPhoto` migration) | `references/capacitor-camera.md` |
| Clipboard | `references/capacitor-clipboard.md` |
| Contacts | `references/capacitor-contacts.md` |
| Native cookies (core) | `references/capacitor-cookies.md` |
| Device info / id / battery | `references/capacitor-device.md` |
| Native alert/confirm/prompt | `references/capacitor-dialog.md` |
| Upload/download with progress | `references/capacitor-file-transfer.md` |
| Open/preview documents | `references/capacitor-file-viewer.md` |
| File read/write | `references/capacitor-filesystem.md` |
| Location (foreground) | `references/capacitor-geolocation.md` |
| Google Maps | `references/capacitor-google-maps.md` |
| HealthKit / Health Connect | `references/capacitor-health-fitness.md` |
| Haptics | `references/capacitor-haptics.md` |
| Native HTTP (core, CORS bypass) | `references/capacitor-http.md` |
| WebView / system / external browser | `references/capacitor-inappbrowser.md` |
| Keyboard API basics | `references/capacitor-keyboard.md` |

From Cap-go/capgo-skills, MIT.

More from Cap-go/capgo-skills