capacitor-app-development

Capacitor アプリ開発

Capacitor を使用したクロスプラットフォームアプリの開発に関する一般的なガイダンスです。基本概念、CLI の使用方法、アプリの設定、プラットフォーム管理、トラブルシューティングを扱います。

前提条件

1. Capacitor 6、7、または 8 のアプリが作成され、初期化されていること。
2. Node.js と npm がインストールされていること（Cap 6 は Node 18 以降、Cap 7 は Node 20 以降、Cap 8 は Node 22 以降）。
3. Android の場合：Android Studio がインストールされていること。
4. iOS の場合：macOS に Xcode がインストールされていること。

エージェントの動作

• 質問する前に自動検出します。 プロジェクトを調べて、プラットフォーム（android/、ios/）、フレームワーク（vite.config.ts、angular.json、webpack.config.js、next.config.js）、Capacitor のバージョン（package.json 内の @capacitor/core）、iOS の依存関係マネージャー（CocoaPods と SPM のどちらかを ios/App/Podfile で確認）を特定します。
• 適切なリファレンスファイルに誘導します。 以下のトピック索引を使って適切なリファレンスファイルを特定し、ガイダンスを提供する前に読みます。
• 一度に扱うトピックは 1 つです。 ユーザーの具体的な質問に対応します。明示的に求められない限り、一般的な概要は提供しません。
• 実行可能な手順を優先します。 概念的な説明よりも、正確なファイルパス、コマンド、差分ブロックを提示します。

手順

ステップ 1：トピックを特定する

ユーザーのリクエストを、以下の索引にあるトピックに照らし合わせます。複数のトピックにまたがる場合は、順番に対応します。

リクエストが別のスキルで扱われているトピックに該当する場合は、そのスキルにユーザーを案内します（末尾の「関連スキル」を参照）。

ステップ 2：プロジェクトを分析する

プロジェクトファイルを読み、以下の項目を自動検出します。

1. Capacitor のバージョン：package.json から @capacitor/core のバージョンを読み取ります。
2. プラットフォーム：存在するディレクトリ（android/、ios/）を確認します。
3. フレームワーク：ビルドツールの設定ファイルを確認します。
4. Capacitor の設定形式：capacitor.config.ts または capacitor.config.json を確認します。
5. iOS の依存関係マネージャー：ios/App/Podfile（CocoaPods）または SPM の使用状況を確認します。

ステップ 3：リファレンスファイルを読み、ガイダンスを適用する

該当するトピックのリファレンスファイルを読み、ユーザーのプロジェクトにその指示を適用します。

トピック索引

トピック	リファレンス
基本概念（ネイティブブリッジ、Capacitor の仕組み）	references/core-concepts.md
Capacitor のプラットフォーム（Android、iOS、Electron、PWA）	references/platforms.md
Capacitor CLI コマンド	references/cli.md
アプリの設定（capacitor.config.ts）	references/app-configuration.md
スプラッシュ画面とアプリアイコン	references/splash-screens-and-icons.md
ディープリンクとユニバーサルリンク	references/deep-links.md
Android のエッジツーエッジ対応	references/edge-to-edge.md
Android のセーフエリア処理	references/safe-area.md
ライブリロードの設定	references/live-reload.md
ストレージの選択肢	references/storage.md
ファイル処理のベストプラクティス	references/file-handling.md
セキュリティのベストプラクティス	references/security.md
iOS のパッケージマネージャー（SPM、CocoaPods）	references/ios-package-managers.md
Capacitor アプリの CI/CD	references/ci-cd.md
テスト（ユニットテストと E2E テスト）	references/testing.md
クロスプラットフォーム開発のベストプラクティス	references/cross-platform-best-practices.md
Android のトラブルシューティング	references/troubleshooting-android.md
iOS のトラブルシューティング	references/troubleshooting-ios.md

エラー処理

• npx cap sync が失敗する：@capacitor/core と @capacitor/cli のバージョンが一致していることを確認してください。CocoaPods を使用する iOS では、cd ios/App && pod install を実行してください。Android では、Android Studio で Gradle ファイルを同期してください。
• 設定変更後に Android のビルドが失敗する：cd android && ./gradlew clean を実行してビルドをクリーンし、その後再ビルドしてください。
• 設定変更後に iOS のビルドが失敗する：Xcode でビルドフォルダーをクリーンする（Product > Clean Build Folder）か、ios/App/Pods を削除して cd ios/App && pod install を実行してください。
• 実行時にプラグインが見つからない：プラグインをインストールした後は、npx cap sync を実行してください。プラグインが capacitor.config またはネイティブプロジェクトに表示されることを確認してください。
• ライブリロードが接続されない：デバイスと開発用マシンが同じネットワーク上にあることを確認してください。capacitor.config のサーバー URL に正しい LAN IP アドレスが設定されていることを確認してください。
• ディープリンクが機能しない：サイト関連付けファイルが https://<domain>/.well-known/apple-app-site-association（iOS）または https://<domain>/.well-known/assetlinks.json（Android）でアクセス可能であることを確認してください。アプリが正しい証明書で署名されていることを確認してください。

関連スキル

• capacitor-app-creation — 新しい Capacitor アプリを作成します。
• capacitor-angular — Angular 固有の Capacitor 開発です。
• capacitor-react — React 固有の Capacitor 開発です。
• capacitor-vue — Vue 固有の Capacitor 開発です。
• capacitor-plugins — Capacitor プラグインをインストールして設定します。
• capacitor-plugin-development — カスタム Capacitor プラグインを作成します。
• capacitor-app-upgrades — Capacitor を新しいメジャーバージョンにアップグレードします。
• capacitor-in-app-purchases — アプリ内購入を設定します。
• capawesome-cloud — クラウドビルド、ライブアップデート、アプリストアへの公開です。
• capacitor-mcp — MCP クライアントを現在の Capacitor ドキュメントに接続します。