How to Migrate Your Capacitor App to Swift Package Manager

Swift Package Manager is the default direction for Capacitor iOS projects. If your app still uses CocoaPods, you can migrate the app itself to SPM without rebuilding your JavaScript code, Android project, or release workflow from scratch.

This guide is for app teams. It explains how to migrate a Capacitor iOS app from CocoaPods to SPM, what the migration assistant changes, what you still need to check in Xcode, and how to clean up CI after the app builds.

アプリ内での変更

A CocoaPods-based Capacitor app depends on files such as:

ios/App/Podfile
ios/App/Podfile.lock
ios/App/Pods/
ios/App/App.xcworkspace

An SPM-based Capacitor app moves iOS dependency wiring into Swift Package Manager. During migration, Capacitor creates a local package named CapApp-SPM and uses it to connect the app target with Capacitor and installed native dependencies.

The web build still works the same way. You still run a web build, sync Capacitor, open Xcode, and archive the app. The main difference is that CocoaPods no longer owns the iOS dependency graph.

移行する前に

新しいブランチから始めて、現在のアプリがビルドされることを確認してください。依存関係管理者を変更する前に依存関係が正しく設定されていることを確認してください。

git status
npm run build
npx cap sync ios

次に、現在の状態をコミットしてください。iOSプロジェクトファイルが生成されるため、ロールバックポイントがきれいであることが重要です。

次に、以下のファイルと設定を確認してください。 ios/App/、もし存在する場合

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift、Firebaseを使用する場合
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plistカスタム
ファイル .xcconfig files
と
CapacitorアプリをSPMに移行する方法

Also check your installed Capacitor and Cordova dependencies. An app-level SPM migration can be blocked by a native dependency that has no SPM-compatible path. Update those packages before migrating when possible.

CapacitorアプリをSPMに移行する方法

Capacitor アプリを SPM に移行するには、公式の Capacitor マイグレーションアシスタントから始めます。

npx cap spm-migration-assistant

Run it from the root of your Capacitor project. The assistant removes CocoaPods integration, creates the local CapApp-SPM CapacitorアプリをSPMに移行する方法

CapacitorアプリをSPMに移行する方法

npx cap open ios

CapacitorアプリをSPMに移行する方法

Confirm CapApp-SPM CapacitorアプリをSPMに移行する方法
アプリのターゲットが生成されたパッケージ製品を確認する。
生成されたものをプロジェクト設定に追加するようにアシスタントが求める場合は、追加する。 debug.xcconfig Xcodeでパッケージ警告を解決する。
Xcodeからアプリを一度ビルドする。
Xcodeがパッケージを解決できない場合は、ファイル > パッケージ > パッケージキャッシュをリセット

を実行し、パッケージを再度解決する。 Xcodeが設定された後、ターミナルに戻り、__CAPGO_KEEP_0__を同步する:そしてXcodeからビルドする。Xcodeからクリーンビルドが正常に動作するまで、リリース署名、特権、アプリ拡張、パッケージ解決はXcodeで検証されるため、移行を完了したと考えるのは間違いである。

アプリがプッシュ通知、関連ドメイン、バックグラウンドモード、アプリグループ、Firebase、またはネイティブ__CAPGO_KEEP_0__設定を使用している場合は、ビルドが成功した後、シミュレーターまたはデバイスでそれらのフローを実行する。

Xcodeを設定したら、ターミナルに戻って Capacitor を同步してください。

npx cap sync ios

ビルドが正常に動作するまで、移行を完了したと考えるのは間違いである。

If the app uses push notifications, associated domains, background modes, app groups, Firebase, or any native SDK configuration, run those flows on a simulator or device after the build succeeds.

Alternative: iOS を SPM で再作成

アプリが ios/ フォルダがデフォルトの Capacitor テンプレートに近い場合、SPM で再作成する方が、インプレースの移行よりも速い場合があります。

すべてのネイティブファイルと署名設定をコミットまたはバックアップした後、このパスを使用してください。

rm -rf ios
npx cap add ios --packagemanager SPM
npx cap sync ios
npx cap open ios

次に、App の特有のネイティブファイルと設定を復元します。このパスは、SPM プロジェクトをクリーンにしますが、カスタム Xcode 変更を失う可能性が高いため、最初にその変更をインベントリに記録することをお勧めします。

Capacitor アプリを SPM に移行する方法 For new Capacitor apps, Capacitor 8 creates iOS projects with SPM by default:

npx cap add ios

SPM で iOS プロジェクトを作成することもできます。

npx cap add ios --packagemanager SPM

You can still be explicit:

CocoaPods の残骸を整理する

SPM アプリがビルドされた後、ローカルスクリプトと CI から CocoaPods の仮定を削除する

pod install

Remove steps like:

ios/App/Pods
ios/App/Podfile.lock
CocoaPods のキャッシュを削除する (CocoaPods のみに存在するキャッシュを含む):
CIキャッシュキーはPodfileに基づく

migration後の基本的なCIフローは、JavaScript依存関係をインストールし、Webアプリケーションをビルドし、Capacitorをsyncし、Xcodeでビルドする

npm ci
npm run build
npx cap sync ios

CIがまだビルドしている場合 App.xcworkspace__CAPGO_KEEP_0__がmigration後のプロジェクトまたはワークスペースパスに更新されるようにします。古いジョブが使用していたCocoaPodsパスを残すのではなく。

トラブルシューティング

依存関係が不相応であることを警告するアシスタント

アシスタントは不互換の依存関係を警告する

依存関係を更新し、アシスタントを再実行してください。SPM互換のバージョンが存在しない場合は、依存関係を置き換えるか、メンテナーがSPMサポートを追加するまで、CocoaPodsでアプリを維持してください。

Xcodeがパッケージを解決できない CapApp-SPM Xcodeのパッケージキャッシュをリセットし、ローカルパッケージとして npx cap sync ios again.

アプリがローカルでビルドできるがCIが失敗する

Capgo pod install, Pods/ Capacitor Podfile.lock Live Update .xcworkspace.

Cloudflare

GitHub

code

API

移行中:

Capacitor

Capacitor
Capacitor
CIのCocoaPodsコマンドを削除する。
CocoaPodsのみのキャッシュを削除する。
アーカイブとリリース署名を検証する。

SPMへの移行に使用するCapgoスキルを使用する。

AIエージェントを使用して移行を実行する場合、__CAPGO_KEEP_0__スキルから始めてください。 Capgoスキルアプリ構造を変更する前にアプリ構造をレビューする。

capacitor-best-practices SPMへの移行とXcodeの後続ステップを計画する。 ios/.
cocoapods-to-spm ビルドパイプラインからCocoaPodsの仮定を削除する。
capacitor-ci-cd そして
debugging-capacitor and ios-android-logs 移行後、デバイスのみの問題を調査する。

iOSプロジェクトを変更する前に、エージェントはネイティブファイル、CI、依存性の互換性をチェックするように使用してください。ただし、のみのマイグレーションコマンドを実行するのではなく。

まとめ

Migrating a Capacitor app to Swift Package Manager is mostly an iOS dependency-management change. The safest path is to start from a clean branch, run npx cap spm-migration-assistantマニュアルのXcodeステップを終了し、再度syncし、CIからCocoaPodsを削除するまでのアプリビルド後のみです。

If your iOS project is heavily customized, migrate in place. If it is close to the default Capacitor template, recreating ios/ 再作成 npx cap add ios --packagemanager SPM がよりクリーンな方法であるかもしれません。