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 __CAPGO_KEEP_0__ app depends on files such as:

An SPM-based Capacitor app moves iOS dependency wiring into Swift Package Manager. During migration, __CAPGO_KEEP_1__ creates a local package named

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 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.

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.

Start from a clean branch and make sure the current app builds before changing dependency managers:

Then commit the working state. The migration touches generated iOS project files, so having a clean rollback point matters.

git status
npm run build
npx cap sync ios

Editor

次に、 ios/App/あなたのアプリがカスタマイズしたものを確認してください。

App/Info.plist
App/AppDelegate.swift
App/SceneDelegate.swift. 保存する必要がある一般的なファイルと設定は次のとおりです。
App/Assets.xcassets/
App/Base.lproj/
App/App.entitlements
App/GoogleService-Info.plist, がある場合
, Firebase を使用する場合 .xcconfig カスタム
ファイル
署名設定、バンドル識別子、チーム ID、プロビジョニングプロファイル

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.

また、インストールされている __CAPGO_KEEP_0__ と Cordova の依存関係も確認してください。ネイティブ依存関係が SPM に対応していない場合、SPM マイグレーションがブロックされる可能性があります。可能な場合は、更新することができます。

For most existing apps, start with the official Capacitor migration assistant:

npx cap spm-migration-assistant

ほとんどの既存のアプリでは、公式の Capacitor マイグレーションアシスタントから始めてください。 CapApp-SPM パッケージ、インストールしたネイティブ依存関係のパッケージ参照を生成し、iOSプロジェクトに必要な生成された設定を追加します。

終了後、iOSプロジェクトを開いてください。

npx cap open ios

ターミナルを閉じる前にアシスタントの出力を読んでください。アシスタントが手動でXcodeのステップを完了するように求めている場合、再度同期する前にそれらを実行してください。

Xcodeのステップを完了してください。

Xcodeでアプリのプロジェクトとターゲットの設定を確認してください。

確認 CapApp-SPM Capacitorがローカルパッケージ依存関係として追加されます。
生成されたパッケージ製品がアプリのターゲットとリンクされていることを確認してください。
アシスタントが追加を求める場合、プロジェクト設定に生成された debug.xcconfig を追加してください。
Xcodeでパッケージ警告を解決してください。
Xcodeからアプリを一度ビルドしてください。

Xcode がパッケージを解決できない場合、使用します。 ファイル > パッケージ > パッケージキャッシュをリセット、するとパッケージを解決してください。

Sync とビルドを再度実行してください。

Xcode が設定された後、ターミナルに戻り、Capacitor を同步してください:

npx cap sync ios

Xcode からビルドをもう一度実行してください。migration を完了したと考えるまで、clean ビルドが Xcode から正常に動作することを確認してください。リリース署名、特権、App 拡張、パッケージ解決などは、Xcode で検証されます。

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

代替: 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 変更を失う可能性が高いため、最初にそれらをインベントリに追加することをお勧めします。

For new Capacitor apps, Capacitor 8 creates iOS projects with SPM by default:

npx cap add ios

明示的に指定することもできます:

npx cap add ios --packagemanager SPM

CocoaPodsの残骸を片付けます

SPMアプリがビルドされた後、ローカルスクリプトとCIからCocoaPodsの仮定を削除してください。

次のようなステップを削除してください:

pod install

CocoaPodsのために存在したキャッシュを削除することも必要です:

ios/App/Pods
ios/App/Podfile.lock
CocoaPodsのスペックリポジトリ
Podfileに基づくCIキャッシュキー

A basic CI flow after migration should install JavaScript dependencies, build the web app, sync Capacitor, and build with Xcode:

npm ci
npm run build
npx cap sync ios

CIがまだビルドしている場合 App.xcworkspaceプロジェクトまたはワークスペースのパスを更新してください。移行後存在するパスを維持する必要はありません。古いジョブが使用していた古いCocoaPodsのパスを維持する必要はありません。

トラブルシューティング

依存関係が不相応であることを助手が警告する

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

Xcodeはパッケージを解決できません

Xcodeのパッケージキャッシュをリセットし、 CapApp-SPM がローカルパッケージとして存在し、 npx cap sync ios を実行してください。

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

古いCocoaPodsの仮定を探してください: pod install, Pods/ キャッシュ Podfile.lock キャッシュキー .xcworkspace.

ビルドコマンドが削除された

署名または特権が変更された

移行チェックリスト

移行前に

ブランチを作成する
現在のiOSアプリのビルドを確認する
作業中の状態をコミットする
カスタムネイティブファイルと署名設定を調べる
既にSPM互換のリリースがあるネイティブ依存関係を更新する

移行中

実行 npx cap spm-migration-assistant.
Xcodeでプロジェクトを開く npx cap open ios.
必要に応じて CapApp-SPM Xcodeで
追加 debug.xcconfig Xcodeで必要な場合に追加します。
パッケージ警告を解決します。
実行 npx cap sync ios.

移行後:

Xcodeからアプリをビルドします。
シミュレータまたはデバイスでネイティブ機能をテストします。
CIからCocoaPodsコマンドを削除します。
CocoaPodsのみのキャッシュを削除します。
アーカイブとリリース署名を検証します。

移行に使用するCapgoスキル

AIエージェントを使用して移行を管理する場合、ここから始めます。 Capgoスキル代わりに空のプロンプトを使用せずに。

capacitor-best-practices この作業で最も役立つスキルは次のとおりです。 ios/.
cocoapods-to-spm アプリ構造を変更する前に、構造を確認すること。
capacitor-ci-cd SPM移行とXcodeの後続ステップを計画すること。
debugging-capacitor ビルドパイプラインからCocoaPodsの仮定を削除すること。 ios-android-logs to investigate device-only issues after migration.

移行後、デバイスのみの問題を調査すること。

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-assistantSwift Package Managerに__CAPGO_KEEP_0__アプリを移行することは、主にiOS依存性管理の変更です。安全なパスは、クリーンブランチから始めて、

If your iOS project is heavily customized, migrate in place. If it is close to the default Capacitor template, recreating ios/ with npx cap add ios --packagemanager SPM can be cleaner.