How to Migrate a Capacitor App to Swift Package Manager¶
Capacitor 8 made Swift Package Manager (SPM) the default dependency manager for new iOS projects, and CocoaPods is officially in maintenance mode. If you maintain an existing Capacitor app on CocoaPods, migrating to SPM is the path forward. This post walks you through what changes on the iOS side and three ways to perform the migration.
What Changes Are Needed¶
Migrating a Capacitor app from CocoaPods to SPM replaces the entire iOS dependency layer. Here's what changes at a high level.
CapApp-SPM Replaces the Podfile¶
In a CocoaPods-based Capacitor app, plugin dependencies live in the ios/App/Podfile. With SPM, that file is gone. Instead, Capacitor uses a local Swift package called CapApp-SPM as the central reference point for all plugin dependencies. The Capacitor CLI updates this package automatically when you run npx cap sync, so you should not edit it by hand.
A New debug.xcconfig Is Generated¶
The SPM setup ships a generated debug.xcconfig file that needs to be added to your Xcode project. It carries the build settings that the old Pods.xcconfig used to provide.
All Plugins Must Support SPM¶
You cannot mix SPM and CocoaPods in a single Capacitor app. Every Capacitor and Cordova plugin in your package.json must offer SPM support before you migrate. Most official and Capawesome plugins already do, but third-party plugins might not. If you maintain a plugin yourself, see How to Migrate a Capacitor Plugin to Swift Package Manager.
What to Back Up Before Migrating¶
The cleanest migration path involves deleting the existing ios/ folder and re-scaffolding it. That means any customization you've made to the native project will be lost unless you preserve it. Before you start, back up the following files from ios/App/:
App/Info.plistApp/AppDelegate.swift(andSceneDelegate.swiftif present)App/Assets.xcassets/App/Base.lproj/App/App.entitlementsApp/GoogleService-Info.plist(if you use Firebase)- Any custom
.xcconfigfiles - Signing configuration (team ID, bundle identifier, provisioning profile settings)
If your project contains additional native Swift or Objective-C source files, custom frameworks, or third-party SDK files outside of plugins, back those up as well. Always commit your changes to source control before starting the migration so you have a clean rollback point.
Migration Options¶
You have three ways to perform the migration. The recommended option depends on how comfortable you are running an AI coding agent against your project.
Option 1: Capawesome Skills (Recommended)¶
Capawesome Skills is a collection of open source AI agent skills for Claude Code and other AI coding agents. It includes a dedicated capacitor-app-spm-migration skill that drives the full migration end to end: it checks prerequisites, inventories your installed plugins, backs up the customized iOS files listed above, deletes the existing ios/ folder, re-scaffolds it with SPM, restores the preserved files, re-syncs plugins, and verifies the build.
Install the skills:
Then prompt your AI agent:
The agent walks through each step interactively and adapts to your app's specific setup. This is the recommended option because it removes most of the manual file shuffling while still keeping you in control of every change.
Option 2: npx cap spm-migration-assistant¶
The Capacitor CLI ships an interactive migration assistant that automates parts of the process:
The assistant removes the CocoaPods infrastructure, generates a Package.swift from your installed plugins, and creates the configuration files needed by SPM. After it finishes, you still need to open the Xcode project and complete a few manual steps:
In Xcode, add CapApp-SPM as a local package dependency and add the generated debug.xcconfig to your project. The assistant prints the exact paths to use.
A few things to keep in mind:
- The assistant works best on unmodified Xcode projects. If you have heavy native customization, expect to fix things up by hand afterwards.
- Plugins that don't ship SPM support will cause the migration to fail. Update or replace them before running the assistant.
- Always commit your changes to source control before running the assistant.
Option 3: Manual Migration¶
If your Xcode project has not been customized, the cleanest manual approach is to delete the ios/ folder and let the Capacitor CLI scaffold a fresh SPM-based project:
After re-scaffolding, restore the files you backed up earlier (Info.plist, AppDelegate.swift, Assets.xcassets, Base.lproj, App.entitlements, GoogleService-Info.plist, custom .xcconfig files, and signing configuration). Then open the project in Xcode and verify that it builds and runs:
This approach gives you full control but requires the most attention to detail. It's a good fit if you prefer to understand every change or if the other two options ran into issues with your project.
Try Capawesome Cloud¶
If you're shipping Capacitor apps, Capawesome Cloud can help you ship faster with cloud-based native builds, over-the-air updates, and automated app store publishing — all of which work seamlessly with both CocoaPods and SPM-based projects.
Conclusion¶
Migrating a Capacitor app to Swift Package Manager is mostly a matter of replacing the CocoaPods layer with CapApp-SPM and a generated debug.xcconfig. With the capacitor-app-spm-migration skill, the official npx cap spm-migration-assistant, or a manual re-scaffold, you have three solid paths to choose from. Make sure all your plugins support SPM, back up your customized iOS files, and pick the option that matches your comfort level.
If you maintain your own Capacitor plugin, take a look at How to Migrate a Capacitor Plugin to Swift Package Manager for the plugin-side counterpart to this guide. If you still need CocoaPods for your project, see How to Use CocoaPods Instead of SPM with Capacitor.
If you have questions, feel free to join the Capawesome Discord server. To stay up to date with the latest news, subscribe to the Capawesome newsletter.