capacitor-expert

name capacitor-expert description A comprehensive starting point for AI agents to work with Capacitor. Covers core concepts, CLI, app creation, plugins, framework integration, best practices, storage, security, testing, troubleshooting, upgrading, and Capawesome Cloud (live updates, native builds, app store publishing). Pair with the other Capacitor skills in this collection for deeper topic-specific guidance. license MIT compatibility Requires Node.js and npm. Xcode on macOS is required for iOS and Android Studio for Android. metadata {"author":"capawesome-team","source":"https://github.com/capawesome-team/skills/tree/main/skills/capacitor-expert"} Capacitor Expert Comprehensive reference for building cross-platform apps with Capacitor. Covers architecture, CLI, plugins, framework integration, best practices, and Capawesome Cloud. MCP Servers Two hosted MCP servers serve the current documentation, so both are always ahead of the guidance bundled with this skill: Capawesome MCP server — the Capawesome plugins, the Capawesome CLI, and Capawesome Cloud. Capacitor MCP server (unofficial) — Capacitor itself: the CLI, the capacitor.config file, the native Android and iOS projects, and the official plugin APIs. Both expose search_docs and get_doc_page , so pick the server by topic before calling either. If the MCP tools are available , call search_docs on the server that owns the topic and read the matching page with get_doc_page before applying the guidance below. Where the two disagree, follow the documentation. If they are not available , mention once that the servers can be added with the commands below, then continue with this skill. Never block on it. claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp" claude mcp add --transport http capacitor "https://capacitor-mcp.capawesome.io/mcp" Neither server needs an account or a token for documentation. See the capawesome-mcp and capacitor-mcp skills for full setup, including the Capawesome Cloud tools. Core Concepts Capacitor is a cross-platform native runtime for building web apps that run natively on iOS, Android, and the web. The web app runs in a native WebView, and Capacitor provides a bridge to native APIs via plugins. Architecture A Capacitor app has three layers: Web layer -- HTML/CSS/JS app running inside a native WebView (WKWebView on iOS, Android System WebView on Android). Native bridge -- Serializes JS plugin calls, routes them to native code, and returns results as Promises. Native layer -- Swift/ObjC (iOS) and Kotlin/Java (Android) code implementing native functionality. Data passed across the bridge must be JSON-serializable. Pass files as paths, not base64. Project Structure my-app/ android/ # Native Android project (committed to VCS) ios/ # Native iOS project (committed to VCS) App/ App/ # iOS app source files App.xcodeproj/ src/ # Web app source code dist/ or www/ or build/ # Built web assets capacitor.config.ts # Capacitor configuration package.json The android/ and ios/ directories are full native projects -- they are committed to version control and can be modified directly. Capacitor Config capacitor.config.ts (preferred) or capacitor.config.json controls app behavior: import type { CapacitorConfig } from '@capacitor/cli' ; const config : CapacitorConfig = { appId : 'com.example.app' , appName : 'My App' , webDir : 'dist' , server : { // androidScheme: 'https', // default in Cap 6+ }, }; export default config; For details, see App Configuration . Creating a New App Quick Start # 1. Create a web app (React example with Vite) npm create vite@latest my-app -- --template react-ts cd my-app && npm install # 2. Install Capacitor npm install @capacitor/core npm install -D @capacitor/cli # 3. Initialize Capacitor npx cap init "My App" com.example.myapp --web-dir dist # 4. Build web assets npm run build # 5. Add platforms npm install @capacitor/android @capacitor/ios npx cap add android npx cap add ios # 6. Sync and run npx cap sync npx cap run android npx cap run ios Web asset directories by framework: Angular: dist/<project-name>/browser (Angular 17+ with application builder) React (Vite): dist Vue (Vite): dist Vanilla: www For the full guided creation flow, see capacitor-app-creation . Capacitor CLI All commands: npx cap <command> . Most important commands: Command Purpose npx cap init <name> <id> Initialize Capacitor in a project npx cap add <platform> Add Android or iOS platform npx cap sync Copy web assets + update native dependencies (run after every plugin install, config change, or web build) npx cap copy Copy web assets only (faster, no native dependency update) npx cap run <platform> Build, sync, and deploy to device/emulator npx cap run <platform> -l --external Run with live reload npx cap open <platform> Open native project in IDE npx cap build <platform> Build native project npx cap doctor Diagnose configuration issues npx cap ls List installed plugins For the full CLI reference, see CLI Reference . Framework Integration Capacitor works with any web framework. Framework-specific patterns: Angular Wrap Capacitor plugins in Angular services for DI and testability. Plugin event listeners run outside NgZone -- always wrap callbacks in NgZone.run() . Register listeners in ngOnInit , remove in ngOnDestroy . For details, see capacitor-angular . React Create custom hooks ( useCamera , useNetwork ) that wrap Capacitor plugins. Use useEffect for listener registration with cleanup to prevent memory leaks. React 18 strict mode double-mounts -- ensure cleanup functions work correctly. For details, see capacitor-react . Vue Create composables ( useCamera , useNetwork ) using Vue 3 Composition API. Register listeners in onMounted , remove in onUnmounted . Vue reactivity picks up ref changes automatically (no NgZone equivalent needed). For details, see capacitor-vue . Plugins Plugins are Capacitor's extension mechanism. Each plugin exposes a JS API backed by native implementations. Plugin Sources Official ( @capacitor/* ) -- Camera, Filesystem, Geolocation, Preferences, etc. Capawesome ( @capawesome/* , @capawesome-team/* ) -- SQLite, NFC, Biometrics, Live Update, etc. Community ( @capacitor-community/* ) -- AdMob, BLE, SQLite, Stripe, etc. Firebase ( @capacitor-firebase/* ) -- Analytics, Auth, Messaging, Firestore, etc. MLKit ( @capacitor-mlkit/* ) -- Barcode scanning, face detection, translation. RevenueCat ( @revenuecat/purchases-capacitor ) -- In-app purchases. Installing a Plugin npm install @capacitor/camera npx cap sync After installation, apply any required platform configuration (permissions in AndroidManifest.xml , Info.plist entries, etc.) as documented by the plugin. Using a Plugin import { Camera , CameraResultType } from '@capacitor/camera' ; const photo = await Camera . getPhoto ({ quality : 90 , resultType : CameraResultType . Uri , }); For the full plugin index (160+ plugins) and setup guides, see capacitor-plugins . Plugin Development Create custom Capacitor plugins with native iOS (Swift) and Android (Java/Kotlin) implementations: Scaffold with npm init @capacitor/plugin@latest . Define the TypeScript API in src/definitions.ts . Implement the web layer in src/web.ts . Implement iOS plugin in ios/Sources/ . Implement Android plugin in android/src/main/java/ . Verify with npm run verify . Key rules: The registerPlugin() name in src/index.ts must match jsName on iOS and @CapacitorPlugin(name = "...") on Android. iOS methods need @objc and must be listed in pluginMethods (CAPBridgedPlugin). Android methods need @PluginMethod() annotation and must be public . For full details, see capacitor-plugin-development . Cross-Platform Best Practices Platform Detection import { Capacitor } from '@capacitor/core' ; const platform = Capacitor . getPlatform (); // 'android' | 'ios' | 'web' if ( Capacitor . isNativePlatform ()) { /* native-only code */ } if ( Capacitor . isPluginAvailable ( 'Camera' )) { /* plugin available */ } Permissions Follow the check-then-request pattern: const status = await Camera . checkPermissions (); if (status. camera !== 'granted' ) { const requested = await Camera . requestPermissions (); if (requested. camera === 'denied' ) { // Guide user to app settings -- cannot re-request on iOS return ; } } const photo = await Camera . getPhoto ({ ... }); Performance Minimize bridge calls -- batch operations instead of many individual calls. Use file paths over base64 for binary data. Lazy-load plugins with dynamic imports for code splitting. Error Handling Always wrap plugin calls in try-catch: try { const photo = await Camera . getPhoto ({ resultType : CameraResultType . Uri }); } catch (error) { if (error. message === 'User cancelled photos app' ) { // Not an error } else { console . error ( 'Camera error:' , error); } } For full details, see Cross-Platform Best Practices . Deep Links Deep links open specific content in the app from external URLs. iOS : Universal Links via apple-app-site-association hosted at https://<domain>/.well-known/ . Android : App Links via assetlinks.json hosted at https://<domain>/.well-known/ . Listener Setup import { App } from '@capacitor/app' ; App . addListener ( 'appUrlOpen' , ( event ) => { const path = new URL (event. url ). pathname ; // Route to the appropriate page }); Platform Configuration iOS : Add applinks:<domain> to Associated Domains capability in ios/App/App/App.entitlements . Android : Add <intent-filter android:autoVerify="true"> to android/app/src/main/AndroidManifest.xml . For full setup, see Deep Links . Storage Requirement Solution App settings, preferences @capacitor/preferences (native key-value, persists reliably) Sensitive data (tokens, credentials) @capawesome-team/capacitor-secure-preferences (Keychain/Keystore) Relational data, offline-first SQLite ( @capawesome-team/capacitor-sqlite or @capacitor-community/sqlite ) Files, images, documents @capacitor/filesystem Do NOT use localStorage , IndexedDB , or cookies for persistent data -- the OS can evict them (especially on iOS). For details, see Storage . Security Never embed secrets (API keys with write access, OAuth secrets, DB credentials) in client code -- move to a server API. Use secure storage ( @capawesome-team/capacitor-secure-preferences ) for tokens and credentials, not localStorage or @capacitor/preferences . HTTPS only -- never allow cleartext HTTP in production. Content Security Policy -- add a <meta> CSP tag in index.html . Disable WebView debugging in production: set webContentsDebuggingEnabled: false in capacitor.config.ts . Prefer Universal/App Links over custom URL schemes (verified via HTTPS). iOS Privacy Manifest ( PrivacyInfo.xcprivacy ) -- required for iOS 17+ when using privacy-sensitive APIs. For details, see Security . Testing Unit Testing Mock Capacitor plugins in Jest/Vitest since tests run in Node.js, not a WebView: vi. mock ( '@capacitor/camera' , () => ({ Camera : { getPhoto : vi. fn (). mockResolvedValue ({ webPath : 'https://example.com/photo.jpg' , }), }, })); E2E Testing