RFC: (iOS) Swift Package Manager in React Native (Cocoapods deprecation)

[chrfalch]

This RFC contains a plan and technical description for how to deprecate Cocoapods and replace it with Swift Package Manager on iOS.

RFC Document

[mrousavy]

Overall this is a really exciting!
I added a section about Mixing C++ and Swift with the direct interop, used by Nitro and all Nitro libraries as this is quite relevant to the ecosystem imo.
I'm sure I can find a solution for this soon.

Thanks for the great RFC Christian!

[mrousavy]

Suggested change

	### Mixing C++ and Swift
	As per [the "Setting Up Mixed-Language Swift and C++ Projects" Swift documentation](https://www.swift.org/documentation/cxx-interop/project-build-setup/#mixing-swift-and-c-using-swift-package-manager), Swift Package Manager (SPM) **does not yet support Swift and C++ in the same target.**
	This causes issues for Swift + C++ libraries or frameworks, including but not limited to the entire [Nitro Modules](https://nitro.margelo.com) ecosystem, as Nitro is built ontop of the direct Swift + C++ interop feature, and uses calls from Swift -> C++, as well as calls from C++ -> Swift within the same target/library - aka bi-directional interop.
	This should not impose a problem for react-native directly as react-native uses Objective-C(++) for interoping between the languages (even Swift - C++ interop uses Objective-C(++) as a bridge, not **direct** Swift C++ interop).
	The [Margelo](https://margelo.com) team is investigating whether this can be solved easily in Nitro - e.g. by using separate targets (one C++, one Swift, and possibly a third one to somehow break the bi-directional dependency).
	As of today, this will affect popular libraries like react-native-vision-camera, react-native-mmkv, react-native-unistyles, react-native-video, and more.

I'll make sure to find a solution for this soon.

[Saadnajmi]

Thank you so much for this! I look forward to the new future. I left some minor comments and nits, but this looks very well thought out 👍

[Saadnajmi]

One edge case that used to not work but I think does now is a monorepo with several library packages, and one app. Old autolinking used to not work and I would hardcode extra pods in my podfile that pointed to the "local" podspecs, but nowadays autolinking works with local packages too. It would be great if that kept working with SPM too.

[chrfalch]

You will have a separate Package.swift files that you can commit and change as much as you like - it will reference another Package.swift file that contains the auto linked targets.

[Saadnajmi]

Is the idea that if someone adds a node module with native code, there's a script phase somewhere that detects that the user might be missing an autolinked pakage?
I.E:

yarn ios --init
yarn add @shopify/react-native-skia
# User runs and builds the app without running `yarn ios`

Would there be an error, or does the "auto-sync build phase" regenerate autolinked/Package.Swift?? I suppose this is similar to how RN devs know they need to pod install constantly, and much better than adding a post install.

[chrfalch]

As for now the flow will basically be the same, when you update your dependencies you will need to update. This can of course be improved - the problem today is that running pod install is very slow - otherwise we'd be doing it automatically I guess.

[Saadnajmi]

To confirm, autolinking would not do what the CLI does today with cocoapods and look for Package.Swift files at the root of every node module? That seems fine, just wanted to confirm.

[chrfalch]

@Saadnajmi - Not sure what you're asking for here? We will basically try to use the same logic for auto linking since it is agnostic when it comes to wether we're using Cocoapods or SPM - it is all about collecting the modules that needs to be linked.

[hurali97]

Hey, thanks for the very well put RFC 🚀

From Brownfield perspective, I have two points in addition to a review:

• #994 (comment)
• #994 (comment)

[hurali97]

There will be an option in the cli for generating separate Package.swift files for distributing the app as a brownfield target.

Is this intended to support a similar use-case we previously did with Podfile using the following code?

target 'BrownfieldLib' do
  inherit! :complete
end

Context: In brownfield apps, when we create a new framework target inside a RNApp, we add the above block in RNApp/ios/Podfile to inherit the package linking and all to the framework target.

Since this behavior may not directly be available with SPM - I am wondering whether the suggested approach of creating a separate Package.swift for the framework target will have duplications containing the same parts as App Target's Package.swift file.

[hurali97]

• static and dynamic frameworks

How are we planning to support this with SPM? With cocoapods, we would usually change this line to toggle between static and dynamic framework linkage:

linkage = ENV['USE_FRAMEWORKS']

Since with the final shape of SPM, we may not have this Podfile - so I wonder have you thought of any ideas on how we support it?

This in general should be for both greenfield and brownfield.

[hurali97]

• Brownfield Packaging

This is rather third party library scoped https://github.com/callstack/react-native-brownfield. There we have a few brownfield packages and 3 of them are shipped as separate xcframeworks.

The user then have the flexibility to either:

• Drag and Drop them to their xcode projects
• Distribute them via SPM

We do not provide first class support for SPM but that is doable by the user. Now that this RFC is actually going to make that support in the core, we will also comply and extend it to our brownfield packaging. This does NOT in anyway means that the generated SPM from this package needs to be linked by the Brownfield Target - rather by the native host App consuming it.

One point on that:
If with this RFC, we ship a separate Package.swift for Brownfield Target, then we are thinking to opt for the following approach for packaging brownfield:

• Create a Package.swift with ReactBrownfield.xcframework, brownfield-navigation.xcramework and brownie.xcframework - as binaryTargets
• Reference the generated Package.swift for Brownfield Target inside this new Package.swift
• Add the binaryTargets to the Brownfield Target
• Ship this Package.swift to the native host App

The above is the layout of what I think we can do once we have this RFC delivered as a RC. Before that, we can also experiment with SPM and once RFC is released, we can change the local link for Brownfield Target to the Package.swift link and keep the rest Package.swift the same with binaryTargets.

[tjzel]

Thanks for the well-thought RFC, I like this direction.

I haven't had the opportunity to use SPM but I wonder if libraries can comfortably hook some scripts prior to compilation using it.

Libraries like Reanimated and Worklets currently execute some custom Ruby scripts inside .podspec to assert proper configuration and obtain compilation flags.

It would be perfect if library authors could extract their common logic from build.gradle and .podspec and put it into react-native.config.js file but I'm aware it's out of scope of this RFC.

[tjzel]

Does it mean that stepping into RN code while debugging will be only available when using Cocoapods, during the transition period?

[cipolleschi]

Until we enable building from source with SPM, yes, you'll have to go back and use Cocoapods, unfortunately.

[chrfalch]

It doesn't mean that we will never support it - we just have to set a few limits to our 1 phase scope.

[cipolleschi]

@tjzel I think you should be able to run Swift PM Plugins to run prebuild code and ensure that everything is properly configured. That's a good point to add to the RFC, that libraries should be able to ship and configure Swift PM plugins. @chrfalch

I believe it is ok if the first implementation doesn't have it, and we work with you folks from Reanimated to add the feature! 😉

[chrfalch]

@tjzel and @cipolleschi: Build plugins have limited access to what they can do - but package resolving runs the Package.swift code and can contain almost anything you need, including updating script files or running separate pipelines. This is the equivalent of running pod install and will probably be the most popular hook for doing things like you mention.

[chrfalch]

• static and dynamic frameworks

How are we planning to support this with SPM? With cocoapods, we would usually change this line to toggle between static and dynamic framework linkage:

linkage = ENV['USE_FRAMEWORKS']

Since with the final shape of SPM, we may not have this Podfile - so I wonder have you thought of any ideas on how we support it?

This in general should be for both greenfield and brownfield.

A package.swift file can include references to both prebuilt XCFrameworks and source files - so as long as the package you want to consume (like Firebase packages) is packaged as a framework you should be able to consume it from your package - without having to change anything in your project.

[tido64]

Will there be any hooks for customizations that require running scripts?

[chrfalch]

Great idea, we haven't made any decisions about this yet - can you come up with some use cases for us to look into? (Remember that you will be able to run scripts from the resolve phase of your own package.swift code)

[tido64]

In RNTA, we also generate the Xcode project files when pod install is run. Additionally, we also:

• Disable warnings in third party libraries to reduce noise
• Define macros to enable/disable certain parts in third party libraries
• Add assets/resources declared in an external file
• Configure code signing (also declared in an external file)
• Apply config plugins (if applicable)
• Various scripts to validate configuration files
• Generate code that must be included in the project

[tibbe]

Thanks for putting this together!

What's the story for migrating existing (non-framework) setups that already have a generated XCode project, etc to the new setup?

[MikePendo]

Hi
wanted to raise another use case that we are currently struggeled with and I want you to take in to account.
When a dynamic framework is resolved via SPM inside a subproject (like Pods.xcodeproj), Xcode fails to automatically embed and sign it in the main app bundle. It compiles fine, but crashes instantly on physical devices with dyld: Library not loaded.

[chrfalch]

Hi wanted to raise another use case that we are currently struggeled with and I want you to take in to account. When a dynamic framework is resolved via SPM inside a subproject (like Pods.xcodeproj), Xcode fails to automatically embed and sign it in the main app bundle. It compiles fine, but crashes instantly on physical devices with dyld: Library not loaded.

Could you give a simple reproduction for this so that we could learn more?

[MikePendo]

Hi @chrfalch — thanks for looking into this.
(sorry for late response I will genrate the message with AI so you could feed it and easily reproduce)

Our React Native plugin's SPM support isn't released yet, so I can't point you at a published package that wires this up. But you don't need it — the crash is a pure Xcode/SPM/dyld issue (not React Native specific), and everything needed to reproduce is already public. Here's a compact spec you can hand to an AI/agent.

Bug

A dynamic framework resolved via SPM inside a subproject (e.g. Pods.xcodeproj) is linked but not auto-embedded/signed into the app bundle. It compiles, runs on Simulator, but crashes at launch on a physical device with dyld: Library not loaded.

Reproduction (no React Native, no account, no unreleased code)

Our native SDK is a public, standard SPM binary package (a .binaryTarget dynamic XCFramework), so plain Xcode is enough:

1. Create a plain iOS app target (ReproApp).
2. Add a second Xcode project as a subproject in the workspace (name it Pods.xcodeproj to mirror the CocoaPods layout).
3. Add this public SPM package, resolved on the subproject — NOT directly on the app target:
   • URL: https://github.com/pendo-io/pendo-mobile-sdk.git
   • Product: Pendo
4. Reference a Pendo symbol from the app so it links (e.g. import Pendo). Do not add it under the app target's "Frameworks, Libraries, and Embedded Content" with Embed & Sign — that auto-fixes it and hides the bug.
5. Build & run on a physical device.

Expected: app launches.
Actual: crash at launch → dyld: Library not loaded: @rpath/Pendo.framework/Pendo … Reason: image not found.

Constraints that must hold (otherwise the bug hides)

• Framework must be dynamic (Pendo is).
• Package must be resolved in a subproject, not directly on the app target.
• Must run on a device — the Simulator masks it.

Root cause

Pure CocoaPods embeds dynamic frameworks via its generated [CP] Embed Pods Frameworks phase (Pods-<App>-frameworks.sh), which copies each framework into Frameworks/ and re-signs it. Once the dependency is SPM-resolved instead of a Pod, it's not in that script — and Xcode only auto-embeds SPM products attached directly to the app target, not ones resolved inside a subproject. So nothing copies/signs it into the bundle.

RFC implication

Declaring the SPM dependency isn't sufficient on its own — there needs to be a defined embed + sign story for dynamic frameworks resolved in subprojects, otherwise every dynamic-framework SDK will crash on device.

Let me know if a clone-and-run repro repo would help and I'll put one together.

[chrfalch]

@MikePendo - The good news is that it comes from the hybrid layout: the framework being resolved on a subproject (Pods.xcodeproj) rather than on the app target. As you note in step 4, attaching it directly to the app target with Embed & Sign "auto-fixes it and hides the bug" — and that's exactly the configuration this RFC produces. add injects the SPM package references directly into the app's existing .xcodeproj / app target, in place, and add --deintegrate runs pod deintegrate and removes React Native from the Podfile, so in the end state there's no Pods.xcodeproj subproject holding the dependency. Xcode's automatic embed-and-sign for products attached to the app target is what covers the dynamic-framework case here.

Where your point does land squarely is brownfield and the migration window, where an SPM-resolved dynamic framework can still live in a subproject alongside an existing CocoaPods/Xcode setup. I'll capture "embed + sign story for dynamic frameworks resolved in subprojects" as an explicit requirement for the brownfield/migration tooling so we don't regress into this on device. A clone-and-run repo would still be genuinely useful there — if you're up for putting one together, please do.