mcpField
C
capacitor-app-spm-migration

capacitor-app-spm-migration

github.com/capawesome-team開発52804 回インストール1 週間前に更新
リポジトリ

capacitor-app-spm-migration について

既存のCapacitorアプリのiOS依存関係をCocoaPodsからSwift Package Managerへ移行するスキルです。Capacitor 6以降のアプリを保守する開発者向けに、iOSプロジェクト再生成前後のファイルや設定の退避・復元手順を示します。

主な機能

  1. 01前提条件と作業ツリーの確認
  2. 02プラグインの一覧化と独自ファイルの退避
  3. 03SPMでiOSプロジェクトを再生成
  4. 04署名設定の復元とプラグイン同期
  5. 05Capabilityの確認とビルド検証

活用シーン

  1. 01既存のCapacitorアプリをSPMへ移行
  2. 02移行時に独自のiOSコードやアセットを保持
  3. 03プラグインのSPM互換性を確認
  4. 04移行後に署名とビルドを検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/capawesome-team/skills --skill capacitor-app-spm-migration

インストール後、Claude Code で/capacitor-app-spm-migrationを入力して読み込まれたか確認します。

詳細

Capacitor アプリ：CocoaPods → SPM 移行

既存の Capacitor アプリプロジェクトの iOS 依存関係管理を、CocoaPods から Swift Package Manager（SPM）に移行します。この移行は破壊的な操作です。既存の ios/ フォルダーを削除して再スキャフォールドし、一時バックアップからユーザー作成ファイルを復元します。

前提条件

要件バージョン
Capacitor6+
Node.js18+
Xcode15+
CocoaPodsインストール済み（削除前の確認にのみ使用）

プロジェクトは Capacitor アプリ（プラグインではない）であり、現在 CocoaPods を使用している必要があります（ios/App/Podfile が存在すること）。

手順

ステップ 1：プロジェクトの状態を確認する
  1. プロジェクトが Capacitor アプリであり、プラグインではないことを確認します。package.json の dependencies に @capacitor/ios が記載され、プロジェクトルートに capacitor.config.* ファイルがあることを確認します。
  2. プロジェクトが現在 CocoaPods を使用していることを確認します。ios/App/Podfile が存在する必要があります。存在せず、ios/App/CapApp-SPM/Package.swift が存在する場合、プロジェクトはすでに SPM を使用しています。処理を中止し、ユーザーに知らせます。
  3. package.json（dependencies または devDependencies）から @capacitor/core のバージョンを読み取ります。メジャーバージョンが 6 以上であることを確認します。それより低い場合は処理を中止し、まず capacitor-app-upgrades スキルを使うようユーザーに案内します。
  4. 作業ツリーがクリーンであることを確認します。git status --porcelain を実行し、出力が空でない場合は、先に変更をコミットするか stash するようユーザーに指示します。この移行は破壊的な操作であり、git checkout で元に戻せる必要があります。
ステップ 2：インストール済み Capacitor プラグインを一覧にする

package.json を読み取り、dependencies にある、インストール済みの Capacitor プラグインをすべて記録します。次のプレフィックスに一致するものを確認します。

  • @capacitor/*（公式プラグイン）
  • @capawesome/* および @capawesome-team/*
  • @capacitor-community/*
  • @capacitor-firebase/*
  • @capacitor-mlkit/*
  • @revenuecat/*
  • その他、package.json の keywords 配列に "capacitor" が含まれるパッケージ

各プラグインのパッケージ名とインストール済みバージョンを記録します。この一覧は、再同期後にすべてのプラグインが SPM で解決されることを確認するため、ステップ 8 で使用します。

ステップ 3：保持するファイルを特定する

再スキャフォールド後も残す必要がある、ユーザー作成コンテンツを含む ios/ 内のファイルのチェックリストを作成します。以下の各パスについて、ファイルが存在するか確認します。存在するパスのみを記録します。

パス（プロジェクトルートからの相対パス）用途
ios/App/App/Info.plistアプリの権限、URL スキーム、バンドル設定、カスタムキー
ios/App/App/AppDelegate.swiftカスタムのアプリライフサイクルコード
ios/App/App/SceneDelegate.swiftカスタムのシーンライフサイクルコード（存在する場合）
ios/App/App/Assets.xcassets/アプリアイコン、スプラッシュ素材、カラーセット
ios/App/App/Base.lproj/LaunchScreen および Main ストーリーボード
ios/App/App/App.entitlementsプッシュ通知、App Groups、Associated Domains、Keychain Sharing
ios/App/App/GoogleService-Info.plistFirebase 設定（Firebase プラグインがインストールされている場合）
ios/App/App/*.xcconfigビルド設定のオーバーライド
ios/App/App.xcodeproj/project.pbxprojステップ 5 で署名値を抽出するためのソース

さらに、ios/App/App/ をスキャンし、AppDelegate.swift と SceneDelegate.swift 以外の 他の .swift ファイルを探します。これらはユーザー作成の Swift ソース（例：カスタムの Notification Service Extension、カスタムのビューコントローラー）であり、これらも保持する必要があります。

プロジェクトに Notification Service Extension や、ios/App/ 配下の他の Xcode ターゲット（例：ios/App/NotificationService/）がある場合は、それらのディレクトリも記録します。

ステップ 4：保持するファイルをバックアップする

  1. バックアップディレクトリを作成します：

    mkdir -p .spm-migration-backup

  2. .gitignore に .spm-migration-backup/ を追加して、誤ってコミットされないようにします：

     # iOS files
+.spm-migration-backup/

  3. ステップ 3 で記録した各ファイルを、相対パスを維持したまま .spm-migration-backup/ にコピーします。例：

    mkdir -p .spm-migration-backup/ios/App/App
cp ios/App/App/Info.plist .spm-migration-backup/ios/App/App/Info.plist
cp ios/App/App/AppDelegate.swift .spm-migration-backup/ios/App/App/AppDelegate.swift
cp -R ios/App/App/Assets.xcassets .spm-migration-backup/ios/App/App/Assets.xcassets
cp -R ios/App/App/Base.lproj .spm-migration-backup/ios/App/App/Base.lproj

    ステップ 3 で特定したすべてのファイル／ディレクトリについて、同じ操作を繰り返します。ディレクトリには cp -R を使用します。

  4. ファイル自体は復元しませんが、必ず ios/App/App.xcodeproj/project.pbxproj 全体を .spm-migration-backup/ios/App/App.xcodeproj/project.pbxproj にコピーします。ステップ 5 で署名値を抽出するために読み込み、ステップ 11 でケイパビリティの再設定時に参照する場合があります。

ステップ 5：署名とバンドルの設定を抽出する

.spm-migration-backup/ios/App/App.xcodeproj/project.pbxproj を読み込み、App ターゲットの XCBuildConfiguration ブロック（Debug と Release の両方）から、以下のビルド設定の値を抽出します。各キーを検索し、割り当てられている値を記録します。

  • PRODUCT_BUNDLE_IDENTIFIER
  • DEVELOPMENT_TEAM
  • CODE_SIGN_STYLE（例：Automatic または Manual）
  • PROVISIONING_PROFILE_SPECIFIER（CODE_SIGN_STYLE = Manual の場合のみ）
  • CODE_SIGN_IDENTITY（CODE_SIGN_STYLE = Manual の場合のみ）
  • MARKETING_VERSION
  • CURRENT_PROJECT_VERSION
  • IPHONEOS_DEPLOYMENT_TARGET
  • SWIFT_VERSION

また、.spm-migration-backup/ios/App/App/App.entitlements（存在する場合）を読み込み、ケイパビリティの一覧を記録します。すべてのトップレベルキーを記録してください（例：aps-environment、com.apple.security.application-groups、com.apple.developer.associated-domains）。

抽出した値をステップ 9 で使用できるよう、メモリに保存します。

ステップ 6：ios/ フォルダを削除する

作業ツリーがコミット済みであること（必要に応じて git status --porcelain を再実行）と、.spm-migration-backup/ にステップ 3 のすべてのファイルが含まれていることをユーザーに確認します。その後、次を実行します：

rm -rf ios
ステップ 7：SPM で iOS を再生成する

次を実行します：

npx cap add ios --packagemanager SPM

これにより、SPM ベースのスキャフォールドを含む新しい ios/ ディレクトリが作成されます。新しい構成には、ios/App/Podfile の代わりに ios/App/CapApp-SPM/Package.swift が含まれます。

ステップ 8：保持したファイルを復元する

バックアップした各ファイルを .spm-migration-backup/ から ios/ 配下の元のパスにコピーし、スキャフォールドのデフォルトを上書きします。例：

cp .spm-migration-backup/ios/App/App/Info.plist ios/App/App/Info.plist
cp .spm-migration-backup/ios/App/App/AppDelegate.swift ios/App/App/AppDelegate.swift
cp -R .spm-migration-backup/ios/App/App/Assets.xcassets ios/App/App/Assets.xcassets
cp -R .spm-migration-backup/ios/App/App/Base.lproj ios/App/App/Base.lproj

ステップ 4 でバックアップしたすべてのファイル／ディレクトリについて、ios/App/App.xcodeproj/project.pbxproj を除き、同じ操作を繰り返します。このファイルは復元しません。SPM 統合には新しい project.pbxproj が必要です。古いファイルの署名値はステップ 9 で再適用します。

保持したファイルが新しいスキャフォールドに存在しない場合（例：App.entitlements、GoogleService-Info.plist、カスタム Swift ファイル）、ステップ 10 でそのファイルを Xcode プロジェクトのメンバーシップに追加する必要があります。

ステップ 9：署名とバンドルの設定を再適用する

新しい ios/App/App.xcodeproj/project.pbxproj を編集し、ステップ 5 で抽出した値を再適用します。各設定について、App ターゲットの XCBuildConfiguration ブロック内にあるすべての出現箇所を探し、スキャフォールドの値を記録した値に置き換えます。

各設定に次の差分パターンを適用します（PRODUCT_BUNDLE_IDENTIFIER の例）：

-				PRODUCT_BUNDLE_IDENTIFIER = com.example.app;
+				PRODUCT_BUNDLE_IDENTIFIER = <RECORDED_BUNDLE_ID>;

再適用する設定（replace_all のセマンティクスを使用し、Debug と Release の両方の構成にあるすべての出現箇所を更新します）：

  • PRODUCT_BUNDLE_IDENTIFIER
  • DEVELOPMENT_TEAM
  • CODE_SIGN_STYLE
  • PROVISIONING_PROFILE_SPECIFIER（手動署名の場合のみ）
  • CODE_SIGN_IDENTITY（手動署名の場合のみ）
  • MARKETING_VERSION
  • CURRENT_PROJECT_VERSION

記録した値の IPHONEOS_DEPLOYMENT_TARGET がスキャフォールドの値より高い場合は、更新します。低い場合は、スキャフォールドの値を維持します（新しいスキャフォールドは、サポート対象の最低値を指定します）。

ステップ 10：復元したカスタムファイルを Xcode プロジェクトに追加する

新しい project.pbxproj が参照するのは、スキャフォールドによって作成されたファイルのみです。ステップ 8 で復元したファイルのうち、スキャフォールドに存在しなかったもの（例：App.entitlements、GoogleService-Info.plist、カスタム Swift ファイル、Notification Service Extension ターゲット）はディスク上にありますが、プロジェクトの PBXBuildFile、PBXFileReference、PBXGroup エントリーに追加されるまでは Xcode に表示されません。

スキャフォールドに含まれていなかったカスタムファイルごとに、Xcode で次の操作を一度だけ行うようユーザーに案内してください（SPM スキャフォールドには App.xcworkspace がありません。App.xcodeproj を直接開いてください）。

  1. プロジェクトを開きます：npx cap open ios（または open ios/App/App.xcodeproj）。
  2. Xcode のプロジェクトナビゲーターで App グループを右クリックし、Add Files to "App"… を選択します。
  3. 復元したカスタムファイル（例：App.entitlements、GoogleService-Info.plist、カスタム .swift ファイル）をそれぞれ選択します。
  4. Copy items if needed のチェックを外し、App ターゲットにチェックが入っていることを確認します。

App.entitlements ファイルについては、ios/App/App.xcodeproj/project.pbxproj のビルド設定 CODE_SIGN_ENTITLEMENTS も設定します。App ターゲットの Debug と Release の XCBuildConfiguration ブロックの両方に、次の差分パターンを適用します。

 				CODE_SIGN_STYLE = Automatic;
+				CODE_SIGN_ENTITLEMENTS = App/App.entitlements;
 				CURRENT_PROJECT_VERSION = 1;

プロジェクトに追加の Xcode ターゲット（例：ios/App/NotificationService/ にある Notification Service Extension）があった場合、ユーザーは Xcode でこれらのターゲットを再作成する必要があります。SPM スキャフォールディングでは、App 以外のターゲットは再生成されません。このことをユーザーに明示してください。

ステップ 11：ケイパビリティを再設定する

ステップ 5 で App.entitlements から記録した各ケイパビリティキーについて、対応するケイパビリティが Xcode で有効になっていることを確認します。

  1. npx cap open ios で ios/App/App.xcodeproj を開きます。
  2. App ターゲットを選択し、Signing & Capabilities タブを開きます。
  3. 各 Entitlement キーに対応するケイパビリティを、+ Capability ボタンから追加します。
    • aps-environment → Push Notifications
    • com.apple.security.application-groups → App Groups
    • com.apple.developer.associated-domains → Associated Domains
    • keychain-access-groups → Keychain Sharing
    • com.apple.developer.in-app-payments → Apple Pay
    • com.apple.developer.icloud-services → iCloud

Xcode での操作が必要なのはこのステップのみです。このステップは手動で行う必要があることを、ユーザーに明示してください。

ステップ 12：プラグインを再同期する

次を実行します。

npm install
npx cap sync ios

npx cap sync ios を実行すると、ステップ 2 で記録したすべての Capacitor プラグインが ios/App/CapApp-SPM/Package.swift に追加されます。警告に注意してください。SPM に対応していないプラグインは、ここで報告されます。

プラグインが incompatible with SPM と報告された場合は、ユーザーに知らせてください。ユーザーは次のいずれかを行う必要があります。

  • プラグインのメンテナーによる SPM 対応を待つ、または
  • プラグインをフォークし、capacitor-plugin-spm-support スキルを使って SPM 対応を追加する、または
  • プロジェクトからプラグインを削除する。
ステップ 13：ビルドを検証する

  1. Xcode でプロジェクトを開き、SPM パッケージを解決します。

    npx cap open ios

    Xcode で File → Packages → Resolve Package Versions を選択します（または、起動時に自動で解決されるのを待ちます）。

  2. コマンドラインからシミュレーター向けにビルドし、すべてがコンパイルできることを確認します。

    npx cap run ios

  3. アプリが起動することと、以前動作していた機能（プッシュ通知、ディープリンク、Firebase など）が引き続き機能することを確認します。

ステップ 14：クリーンアップ

ビルドが検証され、アプリが正しく動作したら、次の操作を行います。

  1. バックアップディレクトリを削除します。

    rm -rf .spm-migration-backup

  2. .gitignore から .spm-migration-backup/ のエントリーを削除します。

  3. CocoaPods の生成物が残っていないことを確認します。

    find ios -name 'Podfile*' -o -name 'Pods' -o -name '*.xcworkspace'

    結果が表示された場合は、削除してください。SPM のワークフローでは App.xcodeproj を直接使用するため、App.xcworkspace はありません。

  4. 移行をコミットします。

    git add -A
git commit -m "chore(ios): migrate from CocoaPods to Swift Package Manager"

エラー処理

  • npx cap add ios --packagemanager SPM が「ios platform already exists」で失敗する — 手順 6 が完了していません。rm -rf ios を再実行してから、もう一度試してください。
  • npx cap sync ios で SPM に対応していないプラグインが報告される — そのプラグインは Package.swift が提供されるまで SPM では使用できません。ユーザーに伝え、移行を中断してください。プラグインを黙って削除しないでください。
  • 「Module 'X' not found」でビルドが失敗する — プラグインの SPM パッケージが解決されていません。Xcode で File → Packages → Reset Package Caches を実行し、その後 File → Packages → Resolve Package Versions を実行してください。
  • コード署名エラーでビルドが失敗する — 手順 9 で再適用した値が不足しているか、誤っています。.spm-migration-backup/ios/App/App.xcodeproj/project.pbxproj を再度読み込み、DEVELOPMENT_TEAM と PRODUCT_BUNDLE_IDENTIFIER が Debug と Release の両方の構成に適用されていることを確認してください。
  • 移行後にプッシュ通知が機能しなくなる — 手順 11 で Push Notifications 機能が再追加されていないか、App.entitlements が CODE_SIGN_ENTITLEMENTS でリンクされていません（手順 10）。
  • Firebase は初期化されるが、データが表示されない — GoogleService-Info.plist はディスクに復元されていますが、手順 10 で Xcode プロジェクトのターゲットメンバーシップに追加されていません。
  • カスタム Notification Service Extension ターゲットが見つからない — App 以外のターゲットは npx cap add ios では再生成されません。Xcode でターゲットを手動で再作成し、ソースファイルを再追加してください。
  • ユーザーが元に戻したいと報告する — 手順 1 でクリーンな作業ツリーを確認しているため、git checkout -- . に続けて git clean -fd ios .spm-migration-backup を実行すれば、移行全体を元に戻せます。

関連スキル

  • capacitor-plugin-spm-support — Capacitor プラグイン（アプリではありません）に SPM サポートを追加する場合に使用します。手順 12 で SPM に対応していないプラグインが報告され、ユーザーがそのプラグインのソースを管理している場合に使用してください。
  • capacitor-plugins — 移行後に Capacitor プラグインをインストールまたは再設定する場合に使用します。
  • capacitor-app-upgrades — プロジェクトが Capacitor 5 以前の場合は、まずこのスキルを使って Capacitor 6 以降にアップグレードしてから、ここに戻ってください。
  • capacitor-app-development — 移行後の Capacitor アプリ開発全般のトピック、トラブルシューティング、ベストプラクティスについて説明します。

コメント

Markdown 対応