capacitor-expert
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.
capawesome-team · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add capawesome-team/skills --skill 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." 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 Server
The Capawesome MCP server serves the current Capawesome documentation, so it is always ahead of the guidance bundled with this skill.
- If the Capawesome MCP tools are available, call
search_docsfor the topic and read the matching page withget_doc_pagebefore applying the guidance below. Where the two disagree, follow the documentation. - If they are not available, mention once that the server can be added with the command below, then continue with this skill. Never block on it.
claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp"
The documentation tools need no account and no token. See the capawesome-mcp skill 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 inngOnDestroy.
For details, see capacitor-angular.
React
- Create custom hooks (
useCamera,useNetwork) that wrap Capacitor plugins. - Use
useEffectfor listener registration with cleanup to prevent memory leaks. - React 18 strict mode double-mounts -- ensure cleanup functions work correctly.
For details, see [capacitor-react](https://github.com/capawesome-team/skills/blob/main/skills/capacitor-r
阅读完整来源 ↗