capacitor-expert

Capacitor エキスパート

Capacitor を使ってクロスプラットフォームアプリを構築するための包括的なリファレンスです。アーキテクチャ、CLI、プラグイン、フレームワークとの統合、ベストプラクティス、Capawesome Cloud を扱います。

MCP サーバー

現在のドキュメントを提供するホスト型 MCP サーバーが 2 つあるため、どちらもこのスキルに含まれるガイダンスより常に最新です。

• Capawesome MCP server — Capawesome プラグイン、Capawesome CLI、Capawesome Cloud。
• Capacitor MCP server（非公式）— Capacitor 自体（CLI、capacitor.config ファイル、ネイティブの Android および iOS プロジェクト、公式プラグイン API）。

どちらも search_docs と get_doc_page を公開しているため、どちらかを呼び出す前にトピックに応じたサーバーを選んでください。

• MCP ツールが利用可能な場合は、トピックを担当するサーバーで search_docs を呼び出し、以下のガイダンスを適用する前に、該当するページを get_doc_page で確認してください。両者の内容が異なる場合は、ドキュメントに従ってください。
• 利用できない場合は、以下のコマンドでサーバーを追加できることを一度だけ伝えてから、このスキルを続行してください。決して作業を中断しないでください。

claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp"
claude mcp add --transport http capacitor "https://capacitor-mcp.capawesome.io/mcp"

どちらのサーバーも、ドキュメントの利用にアカウントやトークンは必要ありません。Capawesome Cloud ツールを含む完全なセットアップについては、capawesome-mcp と capacitor-mcp のスキルを参照してください。

コアコンセプト

Capacitor は、iOS、Android、Web 上でネイティブに動作するウェブアプリを構築するためのクロスプラットフォーム対応ネイティブランタイムです。ウェブアプリはネイティブ WebView 内で動作し、Capacitor はプラグインを介してネイティブ API へのブリッジを提供します。

アーキテクチャ

Capacitor アプリは、次の 3 つのレイヤーで構成されます。

1. Web レイヤー -- ネイティブ WebView 内で動作する HTML/CSS/JS アプリ（iOS では WKWebView、Android では Android System WebView）。
2. ネイティブブリッジ -- JS プラグインの呼び出しをシリアライズし、ネイティブコードにルーティングして、結果を Promise として返します。
3. ネイティブレイヤー -- ネイティブ機能を実装する Swift/ObjC（iOS）および Kotlin/Java（Android）コード。

ブリッジ経由で渡すデータは、JSON にシリアライズ可能でなければなりません。ファイルは base64 ではなく、パスとして渡してください。

プロジェクト構成

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

android/ および ios/ ディレクトリは完全なネイティブプロジェクトです。これらはバージョン管理にコミットされ、直接変更できます。

Capacitor の設定

capacitor.config.ts（推奨）または capacitor.config.json でアプリの動作を制御します。

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;

詳細については、アプリの設定を参照してください。

新しいアプリの作成

クイックスタート

# 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 アセットディレクトリ：

• Angular：dist/<project-name>/browser（application builder を使用する Angular 17 以降）
• React（Vite）：dist
• Vue（Vite）：dist
• Vanilla：www

ガイド付きの完全な作成手順については、capacitor-app-creationを参照してください。

Capacitor CLI

すべてのコマンド：npx cap <command>。特に重要なコマンドは次のとおりです。

コマンド	用途
npx cap init <name> <id>	プロジェクトで Capacitor を初期化する
npx cap add <platform>	Android または iOS プラットフォームを追加する
npx cap sync	Web アセットをコピーし、ネイティブの依存関係を更新する（プラグインのインストール、設定の変更、または Web ビルドのたびに実行）
npx cap copy	Web アセットのみをコピーする（より高速で、ネイティブの依存関係は更新しない）
npx cap run <platform>	ビルド、同期を行い、デバイス／エミュレーターにデプロイする
npx cap run <platform> -l --external	ライブリロードを有効にして実行する
npx cap open <platform>	IDE でネイティブプロジェクトを開く
npx cap build <platform>	ネイティブプロジェクトをビルドする
npx cap doctor	設定の問題を診断する
npx cap ls	インストール済みプラグインを一覧表示する

CLI の詳細については、CLI リファレンスを参照してください。

フレームワークとの統合

Capacitor はあらゆる Web フレームワークで動作します。フレームワーク固有のパターン：

Angular

• DI とテスト容易性を高めるため、Capacitor プラグインを Angular サービスでラップします。
• プラグインのイベントリスナーは NgZone の外で実行されるため、コールバックは必ず NgZone.run() でラップします。
• リスナーは ngOnInit で登録し、ngOnDestroy で削除します。

詳細は、capacitor-angular を参照してください。

React

• Capacitor プラグインをラップするカスタムフック（useCamera、useNetwork）を作成します。
• メモリリークを防ぐため、リスナーの登録にはクリーンアップ処理を含む useEffect を使用します。
• React 18 の Strict Mode ではコンポーネントが二重にマウントされるため、クリーンアップ関数が正しく動作することを確認します。

詳細は、capacitor-react を参照してください。

Vue

• Vue 3 Composition API を使用してコンポーザブル（useCamera、useNetwork）を作成します。
• リスナーは onMounted で登録し、onUnmounted で削除します。
• Vue のリアクティビティは ref の変更を自動的に検知するため、NgZone に相当する仕組みは不要です。

詳細は、capacitor-vue を参照してください。

プラグイン

プラグインは Capacitor の拡張機能です。各プラグインは、ネイティブ実装を基盤とする JS API を公開します。

プラグインのソース

• 公式（@capacitor/*）-- Camera、Filesystem、Geolocation、Preferences など
• Capawesome（@capawesome/*、@capawesome-team/*）-- SQLite、NFC、Biometrics、Live Update など
• コミュニティ（@capacitor-community/*）-- AdMob、BLE、SQLite、Stripe など
• Firebase（@capacitor-firebase/*）-- Analytics、Auth、Messaging、Firestore など
• MLKit（@capacitor-mlkit/*）-- バーコードスキャン、顔検出、翻訳
• RevenueCat（@revenuecat/purchases-capacitor）-- アプリ内購入

プラグインのインストール

npm install @capacitor/camera
npx cap sync

インストール後、プラグインのドキュメントに記載されている必要なプラットフォーム設定（AndroidManifest.xml の権限、Info.plist のエントリーなど）を適用します。

プラグインの使用

import { Camera, CameraResultType } from '@capacitor/camera';

const photo = await Camera.getPhoto({
  quality: 90,
  resultType: CameraResultType.Uri,
});

プラグインの全一覧（160 件以上）とセットアップガイドについては、capacitor-plugins を参照してください。

プラグインの開発

ネイティブの iOS（Swift）および Android（Java/Kotlin）実装を備えたカスタム Capacitor プラグインを作成します。

1. npm init @capacitor/plugin@latest でひな形を作成します。
2. src/definitions.ts で TypeScript API を定義します。
3. src/web.ts で Web レイヤーを実装します。
4. ios/Sources/ で iOS プラグインを実装します。
5. android/src/main/java/ で Android プラグインを実装します。
6. npm run verify で検証します。

主なルール：

• src/index.ts の registerPlugin() の名前は、iOS の jsName および Android の @CapacitorPlugin(name = "...") と一致させる必要があります。
• iOS のメソッドには @objc が必要で、pluginMethods（CAPBridgedPlugin）に記載する必要があります。
• Android のメソッドには @PluginMethod() アノテーションが必要で、public でなければなりません。

詳細については、capacitor-plugin-development を参照してください。

クロスプラットフォーム開発のベストプラクティス

プラットフォームの検出

import { Capacitor } from '@capacitor/core';

const platform = Capacitor.getPlatform(); // 'android' | 'ios' | 'web'
if (Capacitor.isNativePlatform()) { /* native-only code */ }
if (Capacitor.isPluginAvailable('Camera')) { /* plugin available */ }

権限

確認してからリクエストするパターンに従います。

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({ ... });

パフォーマンス

• ブリッジ呼び出しを最小限にする -- 個別に何度も呼び出すのではなく、操作をまとめます。
• バイナリデータには base64 ではなくファイルパスを使用します。
• 動的インポートでプラグインを遅延読み込みし、コード分割します。

エラー処理

プラグインの呼び出しは必ず 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);
  }
}

詳細については、クロスプラットフォーム開発のベストプラクティス を参照してください。

ディープリンク

ディープリンクを使用すると、外部 URL からアプリ内の特定のコンテンツを開けます。

• iOS：https://<domain>/.well-known/ でホストされる apple-app-site-association を使用したユニバーサルリンク。
• Android：https://<domain>/.well-known/ でホストされる assetlinks.json を使用したアプリリンク。

リスナーの設定

import { App } from '@capacitor/app';

App.addListener('appUrlOpen', (event) => {
  const path = new URL(event.url).pathname;
  // Route to the appropriate page
});

プラットフォームの設定

• iOS：ios/App/App/App.entitlements の Associated Domains 機能に applinks:<domain> を追加します。
• Android：android/app/src/main/AndroidManifest.xml に <intent-filter android:autoVerify="true"> を追加します。

セットアップの詳細は、ディープリンクを参照してください。

ストレージ

要件	解決策
アプリの設定、環境設定	@capacitor/preferences（ネイティブのキーと値のストレージ。確実に保持されます）
機密データ（トークン、認証情報）	@capawesome-team/capacitor-secure-preferences（Keychain/Keystore）
リレーショナルデータ、オフラインファースト	SQLite（@capawesome-team/capacitor-sqlite または @capacitor-community/sqlite）
ファイル、画像、ドキュメント	@capacitor/filesystem

永続データには、localStorage、IndexedDB、Cookie を使用しないでください。OS によって消去される可能性があります（特に iOS）。

詳細は、ストレージを参照してください。

セキュリティ

• シークレットを埋め込まないでください（書き込み権限のある API キー、OAuth シークレット、DB 認証情報など）。サーバー API に移してください。
• トークンや認証情報には、localStorage や @capacitor/preferences ではなく、セキュアストレージ（@capawesome-team/capacitor-secure-preferences）を使用してください。
• HTTPS のみを使用してください。本番環境で平文 HTTP を許可しないでください。
• コンテンツセキュリティポリシー：index.html に <meta> CSP タグを追加してください。
• 本番環境ではWebView のデバッグを無効にしてください：capacitor.config.ts で webContentsDebuggingEnabled: false を設定します。
• カスタム URL スキームよりも、Universal Links/App Links（HTTPS による検証済み）を優先してください。
• iOS プライバシーマニフェスト（PrivacyInfo.xcprivacy）：プライバシーに関わる API を使用する場合、iOS 17 以降で必要です。

詳細は、セキュリティを参照してください。

テスト

単体テスト

テストは WebView ではなく Node.js で実行されるため、Jest/Vitest では Capacitor プラグインをモックします。

vi.mock('@capacitor/camera', () => ({
  Camera: {
    getPhoto: vi.fn().mockResolvedValue({
      webPath: 'https://example.com/photo.jpg',
    }),
  },
}));

E2E テスト

• Web E2E：Cypress または Playwright（Web レイヤーをテストします。プラグインはモックする必要があります）。
• ネイティブ E2E：Appium（クロスプラットフォーム）または Detox（iOS 向け）。

デバッグ

• Android：webContentsDebuggingEnabled: true を有効にし、Chrome で chrome://inspect を開きます。
• iOS：webContentsDebuggingEnabled: true を有効にし、Safari の「開発」メニューからデバイスを選択します。

詳細は、テストを参照してください。

トラブルシューティング

Android

• npx cap sync が失敗する：@capacitor/core と @capacitor/cli のバージョンが一致していることを確認してください。cd android && ./gradlew clean を実行します。
• 設定変更後にビルドが失敗する：cd android && ./gradlew clean でクリーンアップしてから、再ビルドします。
• 実行時にプラグインが見つからない：プラグインのインストール後に npx cap sync を実行してください。Gradle の同期が完了したことを確認します。
• SDK エラー：ANDROID_HOME が設定されていることを確認してください。不足している SDK バージョンは、Android Studio の SDK Manager からインストールします。
• 通知アイコンが白い四角になる：プッシュ通知アイコンは、透明な背景に白いピクセルを使用する必要があります。

iOS

• 「no such module」でビルドが失敗する：npx cap sync ios を実行してください。CocoaPods の場合は、cd ios/App && pod install --repo-update を実行します。
• 設定変更後にビルドが失敗する：ビルドフォルダーをクリーンアップする（Xcode の「Product」>「Clean Build Folder」）か、ios/App/Pods を削除して pod install を再実行します。
• シミュレーターでプッシュ通知を受信できない：プッシュ通知のテストには実機を使用してください。
• 権限が恒久的に拒否された：iOS では再度リクエストできません。「設定」>「アプリ」>「権限」へ案内してください。
• WebView が読み込まれない：capacitor.config.ts の webDir が実際のビルド出力ディレクトリと一致していることを確認してください。

全般

• ライブリロードが接続されない：デバイスと開発マシンが同じネットワーク上にあることを確認してください。--external フラグを使用してください。
• プラグインが見つからない：npx cap sync を実行してください。プラグインが package.json の依存関係に含まれていることを確認してください。
• Capacitor is not defined：@capacitor/core をインストールしてください（npm install @capacitor/core）。

詳しいトラブルシューティングについては、Android のトラブルシューティングおよびiOS のトラブルシューティングを参照してください。

アップグレード

Capacitor はメジャーバージョン間（4 から 8）でのアップグレードをサポートしています。各メジャーバージョンへの移行は順番に適用し、中間バージョンを飛ばさないでください。

現在のバージョンから対象バージョン	Node.js	Xcode	Android Studio
5 へ	16+	14.1+	Flamingo 2022.2.1+
6 へ	18+	15.0+	Hedgehog 2023.1.1+
7 へ	20+	16.0+	Ladybug 2024.2.1+
8 へ	22+	26.0+	Otter 2025.2.1+

npx cap migrate は実行しないでください。これはエージェントから呼び出せない対話型コマンドです。バージョンごとのリファレンスファイルを使って、すべてのアップグレード手順を手動で適用してください。

アプリのアップグレードについては、capacitor-app-upgradesを参照してください。 プラグインのアップグレードについては、capacitor-plugin-upgradesを参照してください。

Capawesome Cloud

Capawesome Cloud は、Capacitor アプリ向けに、ネイティブビルド、ライブアップデート、自動アプリストア公開のためのクラウドインフラストラクチャを提供します。

ウェブサイト：capawesome.io | クラウドサービス：capawesome.io/cloud/

はじめに

# Install and authenticate
npx @capawesome/cli login

# Create an app
npx @capawesome/cli apps:create

ライブアップデート

アプリストアを経由せずに、Capacitor アプリへ OTA（Over-The-Air）ウェブアップデートをデプロイできます。ユーザーは次回のアプリ起動時にすぐにアップデートを受け取ります。

セットアップ：

# Install the live update plugin
npm install @capawesome/capacitor-live-update
npx cap sync

capacitor.config.ts で設定します：

const config: CapacitorConfig = {
  plugins: {
    LiveUpdate: {
      appId: '<APP_ID>',
      autoUpdate: true,
    },
  },
};

アップデートのデプロイ：

npm run build
npx @capawesome/cli apps:liveupdates:upload --app-id <APP_ID>

ネイティブビルド

ローカルのビルド環境なしで、iOS および Android アプリをクラウド上でビルドできます。署名証明書、環境、ビルド設定をサポートしています。

# Trigger a build
npx @capawesome/cli apps:builds:create --app-id <APP_ID> --platform android

# Download the artifact
npx @capawesome/cli apps:builds:download --app-id <APP_ID> --build-id <BUILD_ID>

アプリストアへの公開

Apple App Store（TestFlight）および Google Play Store への申請を自動化します。

# Create a deployment destination
npx @capawesome/cli apps:destinations:create --app-id <APP_ID>

# Deploy a build
npx @capawesome/cli apps:deployments:create --app-id <APP_ID> --build-id <BUILD_ID>

CI/CD 統合

CI/CD パイプラインでトークンベース認証を使用します：

npx @capawesome/cli login --token <TOKEN>
npx @capawesome/cli apps:builds:create --app-id <APP_ID> --platform ios --detached

Capawesome Cloud の詳しいセットアップについては、capawesome-cloudを参照してください。 Capawesome CLI のリファレンスについては、capawesome-cliを参照してください。

プッシュ通知

@capacitor-firebase/messaging を使って Firebase Cloud Messaging（FCM）によるプッシュ通知を設定します：

npm install @capacitor-firebase/messaging firebase
npx cap sync

Firebase プロジェクトのセットアップ、プラットフォーム固有の設定（iOS の APNs、Android の google-services.json）、および権限の処理が必要です。

詳しいセットアップガイドについては、capacitor-push-notificationsを参照してください。

アプリ内課金

次のいずれかを使ってアプリ内課金とサブスクリプションを設定します：

• Capawesome Purchases（@capawesome-team/capacitor-purchases）-- 軽量で、サードパーティのバックエンドは不要ですが、Capawesome Insiders ライセンスが必要です。
• RevenueCat（@revenuecat/purchases-capacitor）-- レシート検証、分析、連携機能を備えたフルマネージドのバックエンドです。

どちらも、App Store Connect（iOS）および／または Google Play Console（Android）での商品設定が必要です。

詳しいセットアップガイドについては、capacitor-in-app-purchasesを参照してください。

関連スキル

• capacitor-app-creation -- Capacitor アプリをゼロから作成します。
• capacitor-app-development -- Capacitor の一般的な開発トピック、設定、トラブルシューティングについて説明します。
• capacitor-angular -- Angular 固有の Capacitor パターンについて説明します。
• capacitor-react -- React 固有の Capacitor パターンについて説明します。
• capacitor-vue -- Vue 固有の Capacitor パターンについて説明します。
• capacitor-plugins -- 160 以上の Capacitor プラグインをインストールして設定します。
• capacitor-plugin-development -- カスタム Capacitor プラグインを作成します。
• capacitor-app-upgrades -- メジャーバージョンをまたいで Capacitor アプリをアップグレードします。
• capacitor-plugin-upgrades -- メジャーバージョンをまたいで Capacitor プラグインをアップグレードします。
• capacitor-push-notifications -- FCM を使用したプッシュ通知について説明します。
• capacitor-in-app-purchases -- アプリ内購入とサブスクリプションについて説明します。
• capawesome-cloud -- ライブアップデート、ネイティブビルド、アプリストアへの公開について説明します。
• capawesome-cli -- Capawesome CLI のリファレンスです。
• capawesome-mcp -- MCP クライアントをホストされた Capawesome MCP サーバーに接続し、常に最新のドキュメントと Capawesome Cloud の管理機能を利用します。
• capacitor-mcp -- MCP クライアントをホストされた Capacitor MCP サーバーに接続し、最新の Capacitor ドキュメントとプラグイン一覧を利用します。