[Bug]: Update Capacitor docs to describe how to update existing projects to SPM

[ptmkenny]

Capacitor Version

7

Other API Details

Platforms Affected

• [ ] iOS
• [ ] Android
• [ ] Web

Current Behavior

The Capacitor 7 announcement promotes SPM instead of Cocoapods and notes that Cocoapods are deprecated.. In addition to all the official plugins, many third-party plugins now support SPM.

However, it seems the actual Capacitor SPM docs have not been updated since Capacitor 6, and the documentation is lacking some important info:

• How to migrate from Cocoapods to SPM for an existing project (the docs only have Using SPM in a new Capacitor project)
• Converting existing plugins to SPM- this section says "more coming soon"; it should probably be filled out

Expected Behavior

I expect the docs to describe how to migrate existing projects and how to convert plugins.

Project Reproduction

https://github.com/ionic-team/capacitor/issues?q=is%3Aissue%20state%3Aopen%20migrate

Additional Information

No response

[markemer]

The death of Cocoapods is on our Radar, and we're working on both documentation and preparing to remove SPM from the realm of experimental. You should see some movement soon.

[terencehonles]

I'm just looking at configuring an iOS build, and I was seeing if my patch https://github.com/ionic-team/capacitor/pull/7870 is needed there (it's not, as it already does what I'm proposing).

How experimental is the SPM support? I see that it's printed when running cap sync.

Should I target SPM now, or just wait till we both migrate to v7 for our Android build and SPM is no longer experimental? Will non experimental SPM support be coming in minor or patch release?

[markemer]

I'm just looking at configuring an iOS build, and I was seeing if my patch #7870 is needed there (it's not, as it already does what I'm proposing).

How experimental is the SPM support? I see that it's printed when running cap sync.

Should I target SPM now, or just wait till we both migrate to v7 for our Android build and SPM is no longer experimental? Will non experimental SPM support be coming in minor or patch release?

The biggest issue is that if you use plugins from other sources they may not support it. All the plugins in capacitor-plugins support SPM. Full support is coming, although it may need to wait for a major version upgrade. Cocoapods won't be moving to read-only until Dec 2026 - so there is some time, but because of this impending change it's a priority.

[terencehonles]

Ok, thanks for the update! For the app I'm targeting first we're only using the built in plugins (at least for now) so that would be fine.

One thing I'm noticing about the different builds is that I'm not finding the app inspectable by Safari and there is no debug output. I may table this because of that, but if I have enough time to focus on SPM I may look into that more.

Any chance you know if that's a known issue? (I didn't see it when very quickly searching)

I don't have much xcode experience, but I believe it should be also building a debug build and it's the same simulator. If I do investigate SPM more then I'd probably clean all the .gitignored files in case something left over is an issue.

[ptmkenny]

@terencehonles Please open a new issue. This issue is about adding docs on how to migrate to SPM.

[terencehonles]

Well the docs should probably include known issues, and that's all I was asking... I know it's slightly tangential, but I'm also interested in migrating to SPM and not sure the docs are coming very soon since it sounds like full support may be further away since the announcement you mentioned was from the cocoapods project not the ionic/capacitor project.

[ptmkenny]

Known issues will, by definition, already be an issue that is open in the repo. So search the issues and, if you don't find it, open a new issue. Asking about other issues on a different issue derails the discussion in that issue.

SPM support was originally announced for Capacitor 6, so this is not a new feature, although it is still marked as beta.

I just converted my app from cocoapods to SPM. It turns out there isn't a migration path. You have to delete your existing iOS app and then recreate it as an SPM app (source: the capacitor CLI). This means that you will have to manually reconfigure any customizations you made to the capacitor-generated Xcode project. In my case, app signing, firebase, and deep links all had to be reconfigured. I imagine this is different for each project so it's probably a pain to document, but the short of it is: create your project, and this time choose SPM instead of cocoapods.

[terencehonles]

Yes, I did roughly the same (though I moved some xcode files around that kept my settings. I wasn't as far as you were, so possibly those settings would have been nuked regardless).

I now have two outstanding PRs in this repo and one is approaching ~a year~ two years old (so I'm a little disappointed in communication, but they are both minor changes 🤷 ). I was only trying to engage with two people who care about SPM (one of them is you, but I wasn't sure if you were using SPM or just interested). Since it sounds like you have converted your project to SPM you can also answer my question regarding if you are able to inspect an SPM capacitor app with Safari (or view any logs).

[ptmkenny]

@terencehonles I have no problem inspecting the iOS app's logs in Safari (deployed by TestFlight). After converting the project to SPM, I didn't have to make any changes to my build pipeline.

[markemer]

The docs are also linked to a new tool going in the PR

• #7963

[ionitron-bot[bot]]

Thanks for the issue! This issue is being locked to prevent comments that are not relevant to the original issue. If this is still an issue with the latest version of Capacitor, please create a new issue and ensure the template is fully filled out.