Capacitor App Development
General guidance for developing cross-platform apps with Capacitor, covering core concepts, CLI usage, app configuration, platform management, and troubleshooting.
Prerequisites
- Capacitor 6, 7, or 8 app already created and initialized.
- Node.js and npm installed (Node 18+ for Cap 6, Node 20+ for Cap 7, Node 22+ for Cap 8).
- For Android: Android Studio installed.
- For iOS: Xcode installed on macOS.
Agent Behavior
- Auto-detect before asking. Inspect the project for platforms (
android/,ios/), framework (vite.config.ts,angular.json,webpack.config.js,next.config.js), Capacitor version (@capacitor/coreinpackage.json), and iOS dependency manager (ios/App/Podfilefor CocoaPods vs. SPM). - Route to the right reference file. Use the topic index below to identify the correct reference file and read it before providing guidance.
- One topic at a time. Address the user's specific question. Do not provide a general overview unless explicitly requested.
- Prefer actionable instructions. Provide exact file paths, commands, and diff blocks rather than conceptual explanations.
Procedures
Step 1: Identify the Topic
Match the user's request to a topic from the index below. If the request spans multiple topics, address them sequentially.
If the request matches a topic covered by a different skill, redirect the user to that skill (see Related Skills at the bottom).
Step 2: Analyze the Project
Auto-detect the following by reading project files:
- Capacitor version: Read
@capacitor/coreversion frompackage.json. - Platforms: Check which directories exist (
android/,ios/). - Framework: Check for build tool config files.
- Capacitor config format: Check for
capacitor.config.tsorcapacitor.config.json. - iOS dependency manager: Check for
ios/App/Podfile(CocoaPods) or SPM usage.
Step 3: Read the Reference File and Apply Guidance
Read the reference file for the matched topic and apply the instructions to the user's project.
Topic Index
| Topic | Reference |
|---|---|
| Core concepts (native bridge, how Capacitor works) | references/core-concepts.md |
| Capacitor platforms (Android, iOS, Electron, PWA) | references/platforms.md |
| Capacitor CLI commands | references/cli.md |
App configuration (capacitor.config.ts) | references/app-configuration.md |
| Splash screens and app icons | references/splash-screens-and-icons.md |
| Deep links and universal links | references/deep-links.md |
| Android edge-to-edge support | references/edge-to-edge.md |
| Android safe area handling | references/safe-area.md |
| Live reload setup | references/live-reload.md |
| Storage solutions | references/storage.md |
| File handling best practices | references/file-handling.md |
| Security best practices | references/security.md |
| iOS package managers (SPM, CocoaPods) | references/ios-package-managers.md |
| CI/CD for Capacitor apps | references/ci-cd.md |
| Testing (unit and E2E) | references/testing.md |
| Cross-platform best practices | references/cross-platform-best-practices.md |
| Android troubleshooting | references/troubleshooting-android.md |
| iOS troubleshooting | references/troubleshooting-ios.md |
Error Handling
npx cap syncfails: Verify@capacitor/coreand@capacitor/cliversions match. On iOS with CocoaPods, runcd ios/App && pod install. On Android, sync Gradle files in Android Studio.- Android build fails after configuration changes: Clean the build with
cd android &&./gradlew clean, then rebuild. - iOS build fails after configuration changes: Clean the build folder in Xcode (Product > Clean Build Folder) or delete
ios/App/Podsand runcd ios/App && pod install. - Plugin not found at runtime: Run
npx cap syncafter any plugin installation. Verify the plugin appears incapacitor.configor the native project. - Live reload not connecting: Verify the device and development machine are on the same network. Check that the server URL in
capacitor.configuses the correct LAN IP address. - Deep links not working: Verify the site association file is accessible at
https://<domain>/.well-known/apple-app-site-association(iOS) orhttps://<domain>/.well-known/assetlinks.json(Android). Verify the app is signed with the correct certificate.
Related Skills
capacitor-app-creation— Create a new Capacitor app.capacitor-angular— Angular-specific Capacitor development.capacitor-react— React-specific Capacitor development.capacitor-vue— Vue-specific Capacitor development.capacitor-plugins— Install and configure Capacitor plugins.capacitor-plugin-development— Create custom Capacitor plugins.capacitor-app-upgrades— Upgrade Capacitor to a newer major version.capacitor-in-app-purchases— Set up in-app purchases.capawesome-cloud— Cloud builds, live updates, and app store publishing.