跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
安全

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_docs for 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 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:

  1. Web layer -- HTML/CSS/JS app running inside a native WebView (WKWebView on iOS, Android System WebView on Android).
  2. Native bridge -- Serializes JS plugin calls, routes them to native code, and returns results as Promises.
  3. 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:

CommandPurpose
npx cap init <name> <id>Initialize Capacitor in a project
npx cap add <platform>Add Android or iOS platform
npx cap syncCopy web assets + update native dependencies (run after every plugin install, config change, or web build)
npx cap copyCopy web assets only (faster, no native dependency update)
npx cap run <platform>Build, sync, and deploy to device/emulator
npx cap run <platform> -l --externalRun with live reload
npx cap open <platform>Open native project in IDE
npx cap build <platform>Build native project
npx cap doctorDiagnose configuration issues
npx cap lsList 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](https://github.com/capawesome-team/skills/blob/main/skills/capacitor-r

阅读完整来源 ↗