capacitor-best-practices

Capacitor のベストプラクティス

Capacitor アプリをレビューし、ビルドの失敗、編集内容の消失、本番環境への漏えい、プラグインのクラッシュにつながる構造上の問題を見つけます。詳細なトピックは、担当する関連スキルに案内します。

使用するタイミング

次の場合に使用します：

• Capacitor または Ionic + Capacitor アプリの一般的なコード／アーキテクチャレビューをユーザーが依頼した場合。
• 新しい Capacitor プロジェクトのセットアップ、または既存の Web アプリへの iOS／Android の追加。
• capacitor.config.ts|json のレビュー：webDir、server.url、cleartext、プラグイン設定、環境固有の設定。
• @capacitor/core、@capacitor/cli、@capacitor/ios、@capacitor/android 間のバージョンのずれ、または Capacitor のメジャーバージョンと一致しないプラグインのメジャーバージョン。
• プラグインの使用状況レビュー：npx cap sync の未実行、利用可能性の確認漏れ、権限取得フローの欠如、エラーメッセージ文字列による判定。
• "<Plugin>" plugin is not implemented on ios、Could not find the web assets directory、ios platform has not been added yet などのエラー。
• 設定、ネイティブプロジェクト、ライブアップデートを対象とするリリース前の確認リスト。

使用しない場合：

• セキュリティ監査、シークレット、ストレージ、ピンニング、CSP → capacitor-security；Xcode の強化 → capacitor-ios-security-hardening。
• バンドルサイズ、起動時間、メモリ、ブリッジのプロファイリング → capacitor-performance。
• ユニット／E2E テストのセットアップ、プラグインのモック → capacitor-testing。
• クラッシュ、白い画面、ネイティブログ → debugging-capacitor、ios-android-logs。
• メジャーアップグレード → capacitor-app-upgrades（8 → 9：capacitor-app-upgrade-v8-to-v9）。
• CocoaPods → SPM → cocoapods-to-spm；UIScene への移行 → capacitor-uiscene-migration。
• 特定のプラグインの検索やインストール → capacitor-plugins。
• ストアへの提出と審査 → capacitor-app-store、capacitor-apple-review-preflight；CI → capacitor-ci-cd；ライブアップデート → capgo-live-updates。

現在の基準（2026年10月）

	Capacitor 8（安定版、latest 8.5.x）	Capacitor 9（next、アルファ版）
Node	22+	24+
iOS 最小バージョン／Xcode	iOS 15／Xcode 26（8.5 は UIScene を採用しているため、Xcode 27 でのビルドに対応）	iOS 16／Xcode 27+
Android	minSdk 24、compile／target 36、AGP 8.13、Gradle 8.14.3	minSdk 26、compile／target 37、AGP 9.2.1、Gradle 9.5.1
iOS の依存関係	新規プロジェクトでは SPM がデフォルト	SPM がデフォルト

CocoaPods Trunk は2026年12月2日に読み取り専用になる見込みです。CocoaPods を使用しているすべてのアプリに SPM を推奨してください。Capacitor 9 は GA に到達するまで @next でのみインストールし、本番アプリには推奨しないでください。

レビューワークフロー

1. インベントリ（読み取り専用）。

   npx cap doctor          # installed vs latest Capacitor packages
   npx cap ls              # plugins Capacitor detects per platform
   cat capacitor.config.ts 2>/dev/null || cat capacitor.config.json
   ls ios/App/Podfile ios/App/CapApp-SPM 2>/dev/null   # CocoaPods or SPM
   grep -nE "minSdkVersion|compileSdkVersion|targetSdkVersion" android/variables.gradle
   

2. 大規模なコードベースでは TODO リストを作成し、対象領域（設定、バージョン、プラグイン、ネイティブ iOS、ネイティブ Android、ライブアップデート、リリース）を一つずつレビューします。
3. 編集する前に指摘事項を報告し、重大度ごとに、ファイルと行番号、および修正方法を示します。影響の大きい変更（メジャーバージョンのアップグレード、SPM への移行、R8 の有効化、appId の変更）は、実行前に確認を求めます。
4. 修正し、対応するリファレンスを読み込みます。
5. 検証を実行します。

重要なルール

1. Capacitor のパッケージはすべて同じバージョンにします。 @capacitor/core、cli、ios、android のバージョンを一致させる必要があります。プラグインのメジャーバージョンは Capacitor のメジャーバージョンと一致させてください（公式プラグインと @capgo/* プラグインはこれに従います。Capacitor 8 には v8 のプラグインを使用します）。
2. プラグインをインストールまたは削除するたびに、また設定を変更するたびに npx cap sync を実行します。 sync が不足すると、"<Plugin>" plugin is not implemented on <platform> が発生します。
3. 生成された Web アセットは編集しないでください。 android/app/src/main/assets/public/ と ios/App/App/public/ は cap copy／sync によって上書きされます。src/ を編集して再ビルドしてください。
4. ios/ と android/ をコミットします。 これらはネイティブのカスタマイズを含むソースコードであり、ビルド出力ではありません。capacitor.config.* もコミットします。node_modules、Pods/、ビルドディレクトリはコミットしないでください。
5. リリース設定に開発用の設定を含めないでください。 server.url、server.cleartext、開発ホストへの allowNavigation、webContentsDebuggingEnabled: true が該当します。これらは環境変数で制御してください（references/config-and-project.md を参照）。Capacitor 9 では、ライブリロードに npx cap run <platform> --url <dev-url> を使用します。
6. プラグインを呼び出す前に、機能の有無を確認してください。 Capacitor.isNativePlatform()、Capacitor.getPlatform()、Capacitor.isPluginAvailable('Name') を使用します。Web の代替手段を用意するか、その機能を非表示にしてください。
7. 権限 API を使用してください。 権限 API を公開している公式プラグインでは、checkPermissions() を呼び出してから requestPermissions() を呼び出し、denied の場合は設定画面に移動する方法を案内してください。対応する NS*UsageDescription キー／Android 権限も追加してください。
8. error.message ではなく error.code に基づいて分岐してください。 メッセージはバージョンやプラットフォームによって変わります。公式プラグインは構造化されたコードを公開します（例：@capacitor/camera 8.1+ の新しい API では、カメラ撮影がキャンセルされた場合に OS-PLUG-CAMR-0006 が返されます）。Capacitor コアでは UNIMPLEMENTED／UNAVAILABLE が使用されます。
9. 大きなバイナリデータは base64 ではなくファイルとして扱います。 ブリッジを介してファイルパス／URI を渡し、Capacitor.convertFileSrc() で表示してください。
10. Capacitor 8.5 以降、iOS のライフサイクルはシーンベースです。 UIScene に移行すると、AppDelegate の application(_:open:options:)、continue userActivity、フォアグラウンド／バックグラウンドのコールバックは呼び出されなくなります。独自のネイティブコードは SceneDelegate に移してください（capacitor-uiscene-migration）。サイズ変更可能なウィンドウでは、UIScreen.main とデバイスの種類に基づくレイアウトを避けてください。
11. ライブアップデートでは、起動のたびに CapacitorUpdater.notifyAppReady() を呼び出し、手動アップデートはセッション中に set() を使わず、バックグラウンド移行時または再起動時に next() で適用します。 詳細は capgo-live-updates を参照してください。
12. シークレットをアプリに含めないでください。 バンドル内や capacitor.config 内の情報は抽出できます。このルールを超える内容については capacitor-security を参照してください。

参考資料

トピックが該当する場合にのみ、参考資料を読み込んでください。

参考資料	読み込むタイミング
references/config-and-project.md	capacitor.config、環境別ビルド、リポジトリの構成、.gitignore、バージョンの整合性を確認するとき
references/plugins.md	プラグインのインストール／同期、利用可否の確認、権限、エラーコード、Web の代替手段、遅延読み込み、モックについて確認するとき
references/native-projects.md	iOS の SPM と CocoaPods、UIScene、デプロイメントターゲット、Android の variables.gradle、R8、Capacitor 9 の Gradle の変更について確認するとき
references/release-checklist.md	リリースビルドの準備、またはリリース準備状況の確認を行うとき

検証

# Versions aligned (all @capacitor/* core packages show the same version)
npm ls @capacitor/core @capacitor/cli @capacitor/ios @capacitor/android
npx cap doctor

# Web build exists where webDir points, then sync succeeds without errors
npm run build && npx cap sync

# No dev server or debug flags in the synced native config
grep -nE "\"url\"|cleartext|webContentsDebuggingEnabled" \
  android/app/src/main/assets/capacitor.config.json ios/App/App/capacitor.config.json

# No hand edits in generated web assets (should show nothing)
git status --porcelain android/app/src/main/assets/public ios/App/App/public

# Error handling does not depend on message text
grep -rnE "error\.message\s*(===|==|\.includes)" src/

# Native builds
cd android && ./gradlew assembleRelease && cd ..
xcodebuild -project ios/App/App.xcodeproj -scheme App -configuration Release -destination 'generic/platform=iOS' build CODE_SIGNING_ALLOWED=NO

CocoaPods を使用する場合は、-project の代わりに -workspace を指定して ios/App/App.xcworkspace をビルドしてください。最後に実機で実行し、権限が拒否された場合も含め、プラグインを使用する各機能を確認してください。

エラー処理

エラー	原因	解決方法
"<Plugin>" plugin is not implemented on ios（または android）	プラグインはインストールされていますが同期されていない、プラグインにそのプラットフォーム向けの実装がない、またはプラグインのメジャーバージョンが Capacitor と一致していません	npx cap sync を実行します。npx cap ls で確認します。Capacitor のメジャーバージョンに合ったプラグインのバージョンをインストールし、ネイティブアプリを再ビルドします
"<Plugin>.<method>()" is not implemented on web	ブラウザーでネイティブ専用のメソッドを呼び出しています	Capacitor.isNativePlatform() または isPluginAvailable で判定し、Web 用の代替処理を用意します
Could not find the web assets directory: ./dist.	webDir が間違っているか、Web アプリがビルドされていません	先にビルドします。webDir を実際の出力フォルダー（dist、www、build、out）に設定します
ios platform has not been added yet.	ネイティブプロジェクトがありません	npx cap add ios（デフォルトは SPM）を実行するか、コミット済みの ios/ フォルダーを復元します
Invalid App ID "<id>"	appId が逆ドメイン形式ではないか、無効な文字が含まれています	com.company.app の形式を使います。公開済みアプリで変更すると、新しいストア掲載が作成されます
本番環境でアプリが LAN IP を読み込む、または画面が空白になる	開発用設定の server.url が含まれています	これを削除して再ビルドし、npx cap sync を実行してからネイティブアプリを再ビルドします
net::ERR_CLEARTEXT_NOT_PERMITTED	Android で HTTP リクエストを行っています	HTTPS を使います。cleartext は開発用設定でのみ使用します（capacitor-security を参照）
pod install が失敗する／CocoaPods の spec エラー	CocoaPods trunk の非推奨化、spec の古さ	cocoapods-to-spm で移行します
8.5 以降、iOS でディープリンクまたは resume の処理が機能しなくなった	UIScene の採用後もカスタムコードが AppDelegate に残っています	SceneDelegate に移します（capacitor-uiscene-migration）

リソース

• Capacitor のドキュメント：https://capacitorjs.com/docs
• 設定リファレンス：https://capacitorjs.com/docs/config
• 環境別の設定：https://capacitorjs.com/docs/guides/environment-specific-configurations
• 8.5（UIScene）へのアップデート：https://capacitorjs.com/docs/updating/8-5
• Capgo のドキュメント：https://capgo.app/docs/