DEV Community

Cover image for React Native CocoaPods to Swift Package Manager: what breaks
Warren de Leon
Warren de Leon

Posted on Originally published at warrendeleon.com

React Native CocoaPods to Swift Package Manager: what breaks

✍️ Originally published on warrendeleon.com, where I post first.

On 2 December 2026 CocoaPods trunk stops accepting new podspecs. Your builds keep working and the pods you already resolve keep resolving. Updates through trunk stop, and that affects only the pods your Podfile.lock lists under trunk:; this app had two, lottie-ios and MMKVCore.

The pressure comes from libraries that stop publishing pods, and Firebase is one: its migration page says Firebase 12 is the final major version on CocoaPods and that new versions stop going there in October 2026. All twelve libraries here still ship a podspec at the versions I used.

In August, React Native 0.87 added an experimental Swift Package Manager (SwiftPM) path: one command that swaps CocoaPods out of an existing Xcode project. React Native keeps CocoaPods as its default, and the proposal behind the command, RFC (request for comments) #994, gives no date for dropping it and says "Existing applications should not need to migrate immediately".

The trunk freeze does not force a migration. Try this path on a branch before you plan one.

I ran the command on a finished app, a Pokédex with twelve native libraries chosen to cover eight kinds of iOS dependency between them, and followed it until the app built, launched and passed its test suites again. Four of the twelve moved untouched. Five needed a patched manifest. One stopped being a native module and left its font in the app. The other two, the storage library mmkv and the Nitro Modules it runs on, had to go: mmkv came back one major version older, with a patch of its own. The result is six patches to keep and a downgrade to live with, in exchange for a build that needs no Ruby.

Each of the six patches carries something pod install did in Ruby. Three more fixes in them come from SwiftPM's own rules: the name of a URL-declared package, an umbrella-header layout CocoaPods never applied, and a Swift access level one pod had hidden. The command translates a podspec's sources, search paths and simple settings, and writes a prefix header of its own; the patches keep both and carry what it leaves out:

<p>What pod install did, in Ruby</p>
<ul>
  <li><strong>Permissions:</strong> <code>setup_permissions</code> rewrote the podspec on disk</li>
  <li><strong>Lottie:</strong> <code>s.name = package["name"]</code>, computed at install time</li>
  <li><strong>Screens, permissions, mmkv:</strong> <code>install_modules_dependencies</code> injected <code>RCT_NEW_ARCH_ENABLED</code> and the Folly flags</li>
  <li><strong>Screens:</strong> a codegen <code>header_dir</code> made <code>&lt;rnscreens/…&gt;</code> importable</li>
  <li><strong>Every pod:</strong> a generated prefix header</li>
  <li><strong>svg:</strong> a resource bundle carried the Metal kernels</li>
</ul>


<p>What the patch carries instead</p>
<ul>
  <li><strong>Permissions:</strong> the handler list, written into the manifest</li>
  <li><strong>Lottie:</strong> <code>swiftpmConfig.name</code> in <code>package.json</code></li>
  <li><strong>Screens, permissions, mmkv:</strong> the define by hand, and for mmkv the Folly flags</li>
  <li><strong>Screens:</strong> <code>.headerSearchPath</code> for the parent directory</li>
  <li><strong>Every scaffold:</strong> <code>react-native-spm-prefix.h</code>, force-included</li>
  <li><strong>svg:</strong> the kernels excluded; two <code>feComposite</code> operators do nothing</li>
</ul>
Enter fullscreen mode Exit fullscreen mode

From the first command to a feature-complete build took about 35 minutes and twelve builds, by the timestamps in my migration log; the test suites, the removal of CocoaPods and the clean-build measurements took the rest of the afternoon. The clean Release build came out about 50 seconds faster on one run each, for a cause I have not traced (a second SwiftPM build, from a fresh clone, took 159.2 s against 173.8 s). The app bundle and the binary are smaller, and Ruby is no longer needed on the build machine.

Everything here is React Native 0.88.1 on Xcode 26.4.1, and I have not verified it on 0.87. The builds and measurements are Release for the iPhone 17 Pro simulator. A Debug build of the result also runs from Metro, and an unsigned Release archive for a device builds with Lottie embedded, but I did not run the app on a device.

There is nothing for you to build along the way. The companion repo, react-native-cocoapods-to-spm, has the app at the tag cocoapods and the result at the tag spm, and the two commits between them are the whole migration; the six patches are in its patches/ directory. To replay the commands, start from the app as it was and install it as its README at that tag says (npm install, bundle install, then bundle exec pod install in ios/):

git clone https://github.com/warrendeleon/react-native-cocoapods-to-spm
cd react-native-cocoapods-to-spm
git checkout cocoapods
Enter fullscreen mode Exit fullscreen mode

The app and its twelve libraries

Library What it does in the app Why it is here
react-native-gesture-handler, react-native-reanimated with react-native-worklets, react-native-safe-area-context Swipe to remove, the hero parallax, toasts, the safe areas Four libraries that already ship a Package.swift
lottie-react-native 7.5.0 The Poké Ball loading animation Depends on lottie-ios, a pod from CocoaPods trunk
react-native-screens 4.30.1 Native stack navigation A podspec with a codegen subspec and a header_dir
react-native-svg 15.16.0 The detail screen's artwork Precompiled Metal kernels shipped in a resource bundle
@notifee/react-native 9.1.8 The daily reminder Ruby branches in the podspec; last released in 2024
react-native-permissions 5.6.3 The notification prompt Its handlers are chosen by setup_permissions in the Podfile
@react-native-vector-icons/material-design-icons Tab and action icons A podspec whose only job is copying a font into the app
react-native-mmkv 4.3.2 on react-native-nitro-modules Favourites and the saved theme A Swift and C++ bridge, and MMKVCore from trunk

The Podfile also has a post_install hook that raises old pods' deployment targets. Some kinds of iOS dependency are not in the twelve: none of their podspecs uses vendored_frameworks or script_phases, the app has no Expo modules, and the Podfile turns on use_frameworks! only when the USE_FRAMEWORKS environment variable is set. A library that needs any of those is outside what this post tested.

If your libraries differ, the kinds of failure will still look familiar. Each failure in the twelve builds was one of six kinds:

  • a package or product name that does not match
  • a header layout or resource SwiftPM handles differently from CocoaPods
  • a header path or prefix header CocoaPods supplied
  • Swift and Objective-C split into two targets
  • a sync that runs after Xcode has resolved the packages
  • a native module opted out of the build while its JavaScript still imports it

The first command checks which libraries have manifests; the builds expose the rest.

The first command finds the libraries without a manifest

The 0.87 release post gives the command for an existing CocoaPods project:

cd ios && npx react-native spm --deintegrate
Enter fullscreen mode Exit fullscreen mode

That leaves your shell in ios/: run cd .. before going on, since every later command, until the closing fresh clone, runs from the repository root. Started from the project root instead, the tool detects the layout and runs in ios/ itself.

Run with --verbose --yes, it exits with code 2 after 1.3 seconds, before touching the project. The project, the Podfile and Pods/ are as they were, and git status is clean. It did run codegen and write an autolinking.json under ios/build/generated/, and it printed a verdict on each of the twelve libraries.

Run it on a branch to see which of your libraries need a manifest or another way in. The verdicts say nothing about the compilation, linking and runtime work that follows; for that, grep your podspecs for the lines that needed a patch or another fix here: a name computed in Ruby, install_modules_dependencies, a header_dir, resources or resource_bundles; and grep your Podfile for a hook that rewrites a podspec, as setup_permissions does here.

Verdict Libraries What the tool says
Self-managed gesture-handler, reanimated, worklets, safe-area-context, lottie-react-native The library ships its own Package.swift
No manifest Notifee, the icon font, screens, svg "ships no Swift Package Manager support": run spm scaffold, persist the result with patch-package, ask the maintainer
Mixed sources mmkv, nitro-modules, permissions "has mixed Swift + Objective-C/C++ sources, which Swift Package Manager cannot compile in a single target": opt the library out in react-native.config.js, or consume a prebuilt binary

The tool refuses to touch the project while any linked native library has no manifest, and its scaffolder cannot write one for a library that mixes Swift with Objective-C or C++ in one target. One library without a manifest blocks the other eleven. A self-managed verdict means only that a manifest ships: Lottie's passes this check and is the first build failure.

The same output carries two kinds of warning. Three of the self-managed libraries still declare their SwiftPM settings in an spm block of react-native.config.js; 0.88 wants swiftpmConfig in package.json. And this one:

'lottie-react-native' ships a podspec React Native could not read a name from (CocoaPods may
not be installed), so it is named 'LottieReactNative' after its npm package instead. A machine
that can read the podspec may resolve a different name — set 'swiftpmConfig.name' in
lottie-react-native's package.json to settle it everywhere.
Enter fullscreen mode Exit fullscreen mode

Lottie's podspec computes its name in Ruby (s.name = package["name"]), so the tool's static reader gives up and spawns pod ipc spec. This app installs CocoaPods through Bundler, so pod is not on PATH, and putting the Bundler binstub there does not help: it fails on gem activation without Bundler's environment. The run that works is bundle exec npx react-native spm ..., and under it the package is named lottie-react-native after s.name. For as long as the Podfile and the Gemfile exist, run the SwiftPM tool under bundle exec. The two Lottie names collide at the fourth build.

Scaffold what has no manifest

bundle exec npx react-native spm scaffold
Enter fullscreen mode Exit fullscreen mode

This also exits 2, stopped by Nitro, but it writes six manifests into node_modules first, each translated from the library's podspec, and writes swiftpmConfig.name into each library's package.json so the name no longer depends on reading the podspec.

Library Generated Package.swift
react-native-screens 213 sources, 21 header search paths copied from the podspec
react-native-svg 204 sources, public headers in apple/
@notifee/react-native 18 sources; the podspec's Ruby branches collapsed to the default subspec
react-native-permissions 4 sources: RNPermissions.{h,mm} and the Notifications handler
material-design-icons No sources, one resource, .copy("fonts/*.ttf"), and a warning that SwiftPM may reject the target
react-native-mmkv Only the 8 files under cpp/; the Swift file, the generated Nitro bridge, the MMKVCore dependency and the Folly header path all dropped, with four warnings
react-native-nitro-modules Refused: mixed sources

A scaffold from the pristine permissions podspec has no handlers. The globs the scaffolder read are not the ones in the npm tarball. The shipped podspec says s.source_files = "ios/*.{h,mm}". The copy in node_modules says "ios/*.{h,mm}", "ios/Notifications/*.{h,mm,swift}" and s.frameworks = "UserNotifications", because setup_permissions(['Notifications']) in the Podfile edits the podspec on disk at pod install time. The scaffold inherited that edit. Once CocoaPods is gone, setup_permissions no longer runs. The companion's patch keeps both the rewritten podspec and the manifest, so a fresh install that applies it keeps the Notifications handler. When you scaffold an unpatched new version, restore the handler selection by hand.

scaffold also accepted permissions only by accident. The --deintegrate run had refused it as mixed, and scaffold accepts it, because the autolinker judges by walking the directory tree (one Swift file, the iOS 18 contact picker under ios/Contacts/) while the scaffolder judges by the podspec's source_files globs, which here cover only ios/ itself and the Notifications handler; an app that selects Contacts adds that directory and its Swift file to them.

The mmkv scaffold cannot build: it leaves out the Swift file, the Nitro bridge and the MMKVCore dependency. Nitro has no manifest at all. Nitro's podspec globs ios/**/*.swift and ios/**/*.{m,mm} together, so both checks refuse it. Upstream, Nitro's v1 alpha does ship a Package.swift that splits the Swift and C++ into five targets, so the tool's single-target limit does not apply to it; the cost is an alpha whose minimum is iOS 16, above this app's 15.1. I opted both out for now, to get the other ten building:

```js title="react-native.config.js"
module.exports = {
dependencies: {
'react-native-nitro-modules': { platforms: { ios: null } },
'react-native-mmkv': { platforms: { ios: null } },
},
};




Favourites and the saved theme stop working, and so does the app's launch, until mmkv comes back by a different route.

## The deintegration runs, and leaves two things behind

With every remaining library self-managed or scaffolded, `bundle exec npx react-native spm --deintegrate --yes` exits 0 in 11.3 s. It fills `~/Library/Caches/ReactNative/spm-artifacts/0.88.1` with React Native's prebuilt debug and release artefacts (1.4 GiB on disk; this run found them already cached) and generates three local packages under `ios/build/`: one of React Native's headers, `React-GeneratedCode` with the app's codegen output and generated headers, and `Autolinked`, which aggregates the ten libraries.

The React, Hermes and ReactNativeDependencies binaries are linked through the generated xcconfig, which picks the debug or release copy, and a build script embeds them.

Then it changes the project. It runs `pod deintegrate`, injects three local package references into the `.xcodeproj` with an xcconfig carrying the search paths, `-ObjC` and the flavour-switched framework paths, and adds a scheme pre-action that re-runs `spm sync` whenever `package.json`, `react-native.config.js`, the lockfile, `node_modules` or a library manifest is newer than the last sync's stamp file. The `ios/.gitignore` it writes excludes the generated package trees and `Package.resolved`. The `ios/ReactNativeSPM/` xcconfig and its two scripts are committed, with the project and scheme changes.

The workspace still references the deleted Pods project, so builds go through the project from here; in `.detoxrc.js`, change the build command's `-workspace ios/Pokedex.xcworkspace` to `-project ios/Pokedex.xcodeproj`. Every SwiftPM build in this walkthrough is this command (Detox builds its own `E2E=true` variant from `.detoxrc.js`):



```bash
xcodebuild -project ios/Pokedex.xcodeproj -scheme Pokedex -configuration Release \
  -sdk iphonesimulator -derivedDataPath ios/build build
Enter fullscreen mode Exit fullscreen mode

Keep -derivedDataPath ios/build in it: the steps that say to delete ios/build mean the folder it writes. To run a build on a booted simulator:

xcrun simctl install booted ios/build/Build/Products/Release-iphonesimulator/Pokedex.app
xcrun simctl launch booted org.reactjs.native.example.Pokedex
Enter fullscreen mode Exit fullscreen mode

"Stripped React Native integration from Podfile" removed the lines with prepare_react_native_project!, use_native_modules! and use_react_native!(, but left that last call's arguments and the post_install block in place, so the Podfile no longer parses. The Podfile is dead either way; what to do with it is settled in Remove CocoaPods and make a fresh checkout build, once nothing needs pod.

The project is converted, and nothing has been resolved yet. The first build checks the manifests against SwiftPM's own rules.

Resolution fails on names and layouts a podspec never checked

Xcode resolves the whole package graph before it compiles a file, so the first four builds stop in seconds: three on names and layouts CocoaPods never checked, one on a sync that runs too late.

Lottie names the wrong package (build 1)

The first build fails in 9 s with exit 74, and the failure is in a library that ships its own manifest:

error: Could not resolve package dependencies:
  unknown package 'lottie-ios' in dependencies of target 'LottieReactNative'; valid packages
  are: 'ReactNative' (...), 'React-GeneratedCode' (...), 'lottie-spm' (from
  'https://github.com/airbnb/lottie-spm.git')
Enter fullscreen mode Exit fullscreen mode

Lottie's Package.swift declares .package(url: "https://github.com/airbnb/lottie-spm.git", exact: "4.6.0"), and SwiftPM names a URL-declared package after its repository, lottie-spm. The target then asks for .product(name: "Lottie", package: "lottie-ios"). The fix is one word in that line:

```diff title="node_modules/lottie-react-native/Package.swift"

  • .product(name: "Lottie", package: "lottie-ios"),
  • .product(name: "Lottie", package: "lottie-spm"), ```

The .package declaration replaces the trunk pod: the podspec's s.dependency 'lottie-ios', '4.6.0' becomes airbnb's own lottie-spm package at the same version, a binary Lottie.xcframework downloaded from the GitHub release plus an empty stub target so SwiftPM has something to compile. The library author did that mapping. MMKV's core ships a Package.swift of its own, but react-native-mmkv 4.3.2 maps nothing to it: its podspec depends on the MMKVCore pod, and the scaffold dropped the dependency.

🚩 Edits to node_modules do not survive an install, so from here every fix is a patch-package patch. Set it up with npm install --save-dev patch-package@8.0.1 and npm pkg set scripts.postinstall=patch-package, then run npx patch-package <package> --exclude '^$' after each edit; build 4 shows why.

Permissions' umbrella header and the icon font's resource path (build 2)

The second build stops on two generated manifests at once:

target 'RNPermissions' has invalid header layout: umbrella header found at
'.../RNPermissions/ios/RNPermissions.h', but directories exist next to it:
.../ios/AppTrackingTransparency, .../ios/Bluetooth, ... .../ios/StoreKit; consider removing them
Invalid Resource 'fonts/*.ttf': File not found.
public headers ("include") directory path for 'react-native-vector-icons-material-design-icons'
is invalid or not contained in the target
Enter fullscreen mode Exit fullscreen mode

The permissions scaffold set publicHeadersPath: "ios" from the podspec. That directory holds RNPermissions.h, named after the module. With no custom module.modulemap there, SwiftPM generates a module map with that file as its umbrella header, and its rule is that a top-level umbrella header may have other headers beside it but no directories. Twenty handler directories sit beside it. CocoaPods built the same layout without complaint, which suggests it only read the globs. The fix is a public headers path with no umbrella in it, the one handler this app compiles:

```diff title="node_modules/react-native-permissions/Package.swift"

  • publicHeadersPath: "ios",
  • publicHeadersPath: "ios/Notifications", ```

Nothing outside the package imports these headers, since React Native's generated RCTModuleProviders.mm finds the module class by name. This app has one handler and I tried no other; an app with several has the same umbrella rule to satisfy, and this patch, written for one handler, will not carry over as it is.

The icon library's podspec has no sources, only s.resources = 'fonts/*.ttf', and CocoaPods copied the font to the app bundle's root, where UIAppFonts in Info.plist finds it. The scaffold turned that into .copy("fonts/*.ttf") on a target with no sources, and SwiftPM rejects the glob (.copy takes a path) and also the source-less target.

Fixing both would not help: a SwiftPM resource lands in <package>_<target>.bundle, not the app root. On SwiftPM I made a library's font the app's responsibility when UIAppFonts loads it, as the app's own fonts already were. The library stops being a native module (an '@react-native-vector-icons/material-design-icons': { platforms: { ios: null } } entry in react-native.config.js), its scaffolded Package.swift is deleted, and MaterialDesignIcons.ttf joins the Nunito files in the app target's Fonts group as a file reference into node_modules, so it follows the package's version.

In Xcode, add it to the Pokedex target without copying, which also puts it in the Copy Bundle Resources phase; the path relative to the group is ../../node_modules/@react-native-vector-icons/material-design-icons/fonts/MaterialDesignIcons.ttf. Info.plist already listed it; the JavaScript side of the icon set is untouched.

The sync runs too late (build 3)

The third build fails in under a second, and the failure shows when the scheme's sync runs:

the package manifest at '.../autolinking/libs/react-native-vector-icons-material-design-icons/
Package.swift' cannot be accessed (... doesn't exist in file system)
Enter fullscreen mode Exit fullscreen mode

The scheme pre-action does re-run spm sync when react-native.config.js changes. Xcode resolves the package graph before any pre-action runs, and the generated Autolinked manifest from the previous sync still listed the package I had opted out. A change that removes a library needs an explicit spm sync before the next build, and from the same order of events I expect one that adds a library does too, though I tested only removal.

bundle exec npx react-native spm sync
Enter fullscreen mode Exit fullscreen mode

Lottie's local product name disagrees with autolinking (build 4)

lottie-spm is the remote package Lottie depends on, fixed in build 1. This build is about two names of the local package itself: the one the autolinker gives it and the product name its own manifest declares. The fourth build hits the collision between them:

product 'lottie-react-native' required by package 'autolinking' target 'AutolinkedAggregate'
not found in package 'lottie-react-native'.
Enter fullscreen mode Exit fullscreen mode

Under bundle exec the package is named lottie-react-native after s.name, but Lottie's own manifest names its product LottieReactNative; without pod reachable, the tool had derived LottieReactNative from the npm name, which happened to match. The fix is the one the Lottie warning named, in Lottie's package.json:

```json title="node_modules/lottie-react-native/package.json"
"swiftpmConfig": { "name": "LottieReactNative" }




Run `bundle exec npx react-native spm sync` after the edit, since the product name the aggregate refers to has changed; it then reads `.product(name: "LottieReactNative", package: "LottieReactNative")`.

The `swiftpmConfig` entry belongs upstream in lottie-react-native; until it lands, it has to live in the patch. At first it did not: `patch-package` leaves `package.json` out by default, though the scaffolder says the patch will capture it, so I recreated every patch with `--exclude '^$'`. Without that flag a fresh `npm install` restores the manifests but loses `swiftpmConfig.name`, and the `lottie-react-native` collision returns wherever `pod` is reachable, under `bundle exec` included. With resolution clean, the next build is the first to compile the scaffolds.

## Compilation needs the defines and headers CocoaPods injected

With the graph resolved, Xcode compiles every library for the first time, and three builds fail on what CocoaPods used to supply around the source: a resource bundle, a header path and a prefix header.

### svg's Metal kernels, which the podspec never compiled (build 5)

The fifth build compiles for 14 s and stops in react-native-svg:



```text
CompileMetalFile .../RNSVG/apple/Filters/MetalCI/RNSVGArithmeticFilter.metal (in target 'RNSVG_RNSVG')
error: cannot execute tool 'metal' due to missing Metal Toolchain; use: xcodebuild -downloadComponent MetalToolchain
Enter fullscreen mode Exit fullscreen mode

It stops here only when Xcode's Metal Toolchain component is not installed, as on this Mac. With the component installed I expect the build to get past this step, though I did not test it; the manifest needs replacing either way, because the compiled kernels would not be where svg loads them.

The scaffold never lists the two .metal files, but Xcode compiles any Metal source it finds under a package target's path, and Xcode 26 ships the Metal compiler as a separate download. The CocoaPods build never compiled them. The podspec puts the precompiled kernels in a resource bundle, s.ios.resource_bundles = {'RNSVGFilters' => ['apple/**/*.iphoneos.metallib']}, and RNSVGCustomFilter.mm loads them at runtime by name from RNSVGFilters.bundle, skipping the filter when the bundle is missing. A SwiftPM resource lands in RNSVG_RNSVG.bundle, so shipping the kernels as resources would not reach that code either.

react-native-svg's main carries a hand-written Package.swift that the published 15.16.0 does not ship, and it excludes every kernel with a comment saying why: SwiftPM cannot produce that bundle. The two kernels it excludes, RNSVGCompositeXor and RNSVGArithmeticFilter, implement feComposite's xor and arithmetic operators, so on SwiftPM those two operators silently do nothing. This app's artwork uses neither. I replaced the scaffold, its Package.swift and its prefix header, with upstream's manifest verbatim, at commit b6152ad of 29 October 2026 (every path it names exists in 15.16.0).

That manifest also defines RCT_NEW_ARCH_ENABLED=1, with the comment "RCT_NEW_ARCH_ENABLED comes from install_modules_dependencies under CocoaPods; without it, all Fabric code compiles out". The CocoaPods build log has -DRCT_NEW_ARCH_ENABLED=1 30 times, in the compiler flags of nine of the sixteen pod targets; Notifee's is not one of them, and its source never reads the define.

None of the four scaffolds for screens, svg, Notifee and permissions had it. Add it now to the screens, Notifee and permissions manifests, as .define("RCT_NEW_ARCH_ENABLED", to: "1") in both the cSettings and cxxSettings arrays; its absence is not what fails build 5.

For screens and permissions that matches the CocoaPods flags; Notifee did not get it there. In permissions it guards the TurboModule implementation (getTurboModule); the module's registration does not depend on it. Screens 4.30.1's sources never read it, so it is inert there and in Notifee, and I did not test permissions without it. The five self-managed libraries' manifests do not carry it.

Each scaffold also carries a react-native-spm-prefix.h (Foundation and UIKit, force-included with -include), standing in for the prefix header CocoaPods generated per pod.

Screens: a header_dir without its parent (build 6)

The sixth build gets 30 s in and fails on one header in screens:

ios/tabs/bottom-accessory/RNSTabsBottomAccessoryComponentView.h:8:
  'rnscreens/RNSTabsBottomAccessoryComponentDescriptor.h' file not found
Enter fullscreen mode Exit fullscreen mode

The podspec's codegen subspec sets ss.header_dir = "rnscreens", so under CocoaPods the generated headers are importable as <rnscreens/...>. The scaffold copied the podspec's search paths, which include that directory but not its parent, so the angle-bracket form resolves nowhere. One search path, added to both the cSettings and cxxSettings arrays, fixes it:

```diff title="node_modules/react-native-screens/Package.swift"

  • .headerSearchPath("common/cpp/react/renderer/components"), ```

svg's manifest is ahead of its release (build 7)

The seventh build compiles screens and fails svg with twenty errors, the first of them unknown type name 'int32_t' in a header that imports nothing. Under CocoaPods it compiled through the generated prefix header, but I had just replaced svg's scaffold with upstream's manifest, which has no prefix header; on main, apple/Filters/RNSVGBlendMode.h now begins with #import <Foundation/Foundation.h>. A hand-written manifest on a library's main describes the next release, and the version in node_modules can differ from it. Until a release ships both the manifest and that import, 15.16.0 needs upstream's manifest plus the scaffolder's prefix header, restored (every scaffold's copy of react-native-spm-prefix.h is identical, so take any of them) and force-included in both settings blocks. The two added lines differ by a comma, because the debug and release defines still follow the cxxSettings one:

```diff title="node_modules/react-native-svg/Package.swift"
cSettings: defines.map { .define($0, to: $1) }

  • + headerSearchPaths.map { .headerSearchPath($0) },
  • + headerSearchPaths.map { .headerSearchPath($0) }
  • + [.headerSearchPath("."), .unsafeFlags(["-include", "react-native-spm-prefix.h"])], cxxSettings: defines.map { .define($0, to: $1) }
    • headerSearchPaths.map { .headerSearchPath($0) }
  • + [.headerSearchPath("."), .unsafeFlags(["-include", "react-native-spm-prefix.h"])]
    • [ ```

Every library now compiles; Lottie, which CocoaPods built as one pod, no longer links.

Lottie compiles and fails to link

Lottie's own manifest splits the library in two, and it takes three builds to make the halves link.

One pod became two targets (build 8)

The eighth build compiles every library in 77 s and fails to link the app:

Undefined symbols for architecture arm64:
  "_OBJC_CLASS_$_LottieAnimationView", referenced from:
      __OBJC_$_CATEGORY_LottieAnimationView_$_RCTExternModule in LottieReactNativeObjC.o
  "_OBJC_CLASS_$_LottieContainerView", referenced from: ... in LottieReactNativeObjC.o
Enter fullscreen mode Exit fullscreen mode

Both classes are Swift (@objc(LottieContainerView) class ContainerView: RCTView, @objc(LottieAnimationView) class AnimationViewManagerModule: RCTViewManager), referenced from the library's own Objective-C. That Objective-C already declares them, through Lottie's handwritten LottieContainerView.h and React Native's RCT_EXTERN_MODULE macro, so it compiles. The failure is at link time. Lottie's manifest puts the Swift files in one target and the Objective-C in another, because SwiftPM cannot mix them. Under CocoaPods they were one pod, built into one library, and the class symbols resolved. Across two SwiftPM targets they do not.

📊 Diagram: view it on warrendeleon.com

nm on ContainerView.o shows the class symbol as global; on the target's merged object the same symbol is local. Neither class is public, which suggests Xcode's merge of a Swift target hides whatever the module does not export. The Swift target's object is on the app's link line; the symbol is not exported from it.

Public classes need public overrides and aliases (builds 9 and 10)

The fix is public, and each error names every site that needs it:

  1. Make both classes public class. The ninth build (6 s) fails with "overriding instance method must be as accessible as its enclosing type".
  2. Make five methods across the two files public override. The tenth build (6 s) fails with "method cannot be declared public because its result uses an internal type".
  3. Make the two View aliases that view() returns public typealias, and Lottie links.

In ContainerView.swift, steps 1 and 2 look like this:

```diff title="node_modules/lottie-react-native/ios/LottieReactNative/ContainerView.swift"
-class ContainerView: RCTView {
+public class ContainerView: RCTView {

  • override func layoutSubviews() {
  • public override func layoutSubviews() { ```

Upstream still has them internal, so Lottie's shipped SwiftPM support does not link here. I tested the unpatched library's link failure only in Release.

The eleventh build succeeds in 20 s, incremental, with nine libraries on SwiftPM.

The app throws before its first render, and mmkv goes back a major version

The build is green and the app throws at launch, leaving a blank screen, because one of the libraries opted out at the scaffold step is still in use.

The library you opted out is still imported (build 11)

Unhandled JS Exception: [runtime not ready]: Error: Failed to get NitroModules:
The native "NitroModules" Turbo/Native-Module could not be found.
Enter fullscreen mode Exit fullscreen mode

storage.ts creates the MMKV instance at import, and the JavaScript half of react-native-mmkv is still installed. platforms: { ios: null } removes a library from the native build and leaves its JavaScript installed. The tool's advice to opt out is sound for a library the app does not call; for one it does, the JavaScript has to go too, or be replaced.

Three options for favourites and the saved theme:

  1. Nitro's v1 alpha, which ships a manifest. Five of the sixteen NitroModules/ headers that mmkv 4.3.2's generated bridge includes do not exist in it; mmkv would have to be regenerated with the alpha's nitrogen code generator and patched. Too far from a published version to be this post's advice.
  2. AsyncStorage, whose iOS sources mix Swift and Objective-C++, so the checks that refused Nitro would refuse it too. Its API is also asynchronous, which changes the app: the store and the theme are read synchronously before the first render.
  3. react-native-mmkv 3.3.3 (the last 3.x release, September 2025): the same synchronous API (new MMKV({ id }) for createMMKV, delete for remove), no Swift sources, and it vendors MMKV's core instead of depending on the MMKVCore trunk pod.

I went with react-native-mmkv 3.3.3. It is one major version back, and it takes the second trunk dependency out with it.

npm uninstall react-native-nitro-modules && npm install react-native-mmkv@3.3.3
Enter fullscreen mode Exit fullscreen mode

Then take the react-native-mmkv and react-native-nitro-modules entries out of react-native.config.js, keeping the icon library's, so mmkv is back in the native build. The scaffolder skips any library opted out there, so make that edit before you scaffold:

bundle exec npx react-native spm scaffold
Enter fullscreen mode Exit fullscreen mode

The scaffold for 3.3.3 is 75 sources including two assembly files, eight header paths and -x objective-c++, with one warning, "install_modules_dependencies(s) detected": that call is where the podspec got RCT_NEW_ARCH_ENABLED and the Folly flags under CocoaPods, so they go in by hand (RCT_NEW_ARCH_ENABLED=1, FOLLY_NO_CONFIG, FOLLY_MOBILE=1, FOLLY_USE_LIBCPP=1, FOLLY_CFG_NO_COROUTINES, plus the podspec's own FORCE_POSIX). Save them with npx patch-package react-native-mmkv --exclude '^$'.

Running scaffold for one library regenerates every scaffold in the app. The command has no per-library option, and it passes force: true to the scaffolder, so every manifest carrying the scaffolder's marker is rewritten from its podspec. The screens, Notifee and permissions manifests lost their RCT_NEW_ARCH_ENABLED defines, the permissions headers path and the screens search path; the svg manifest (upstream's, no marker) and Lottie's (shipped) were untouched.

At this point in the migration, restore those three libraries; mmkv's edits have just been saved. Delete the three packages from node_modules and reinstall, so the postinstall applies their patches to clean copies, then sync once more:

rm -rf node_modules/react-native-screens node_modules/@notifee/react-native node_modules/react-native-permissions
npm install
bundle exec npx react-native spm sync
Enter fullscreen mode Exit fullscreen mode

Re-applying the patches in place does not work. With the regenerated manifests there, npx patch-package prints a tick for each patch and changes nothing: when a patch fails to apply, patch-package 8.0.1 tries it in reverse, and the existing files pass that dry run, so it treats the patch as already applied. With the manifests deleted first, the patches fail instead, on their package.json hunk, because the swiftpmConfig.name they add is still there from the first scaffold.

To keep a later scaffold away from an edited manifest, strip its AUTO-SCAFFOLDED marker lines: the scaffolder's source leaves any Package.swift without them alone ("Never touch"), though the comment it writes just below the marker says that removing the file, or only the marker, and re-running scaffold regenerates it. The companion's patches keep the markers.

The finished spm tag has no Gemfile, so a later scaffold there is plain npx react-native spm scaffold. Without pod, it reads each podspec with a regular expression and drops sources and settings (screens goes from 213 sources to 73), so restore all four regenerated libraries, mmkv included, and run the sync without bundle exec:

rm -rf node_modules/react-native-screens node_modules/@notifee/react-native \
  node_modules/react-native-permissions node_modules/react-native-mmkv
npm install
npx react-native spm sync
Enter fullscreen mode Exit fullscreen mode

That restores the patches at their pinned versions; it does not repair a patch that fails against a new version.

ios/build/generated/autolinking/libs/<Name> is a symlink into node_modules, and a tsconfig.json that includes **/*.ts will type-check every linked library. Add ios/build to the exclude list in tsconfig.json.

The JavaScript changes are two lines in storage.ts and a Jest stand-in that exports an MMKV class, which you can take from the companion with git show spm:__mocks__/react-native-mmkv.ts > __mocks__/react-native-mmkv.ts:

```diff title="src/store/storage.ts"
-import { createMMKV } from 'react-native-mmkv';
+import { MMKV } from 'react-native-mmkv';
-export const storage = createMMKV({ id: 'pokedex' });
+export const storage = new MMKV({ id: 'pokedex' });




The app's other calls, `getString`, `getBoolean` and `set`, have the same names in 3.x; I did not check what else the app gives up from 4.x.

The 173 tests of the main Jest config and the three of the timezone config pass unchanged. Jest runs against that stand-in; the simulator checks reach the native store, including Detox's relaunch tests and the read-back of a 4.3.2 store in 3.3.3.

### The app launches (build 12)

The twelfth build, with mmkv 3.3.3, succeeds in 54 s. The app launches, and the grid, fonts, icons, daily card and theme toggle work as before. Detox, on an `E2E=true` build of the same tree, passes 31 of 31, the same count as on the `cocoapods` tag. The first run had one flake: the relaunch test "keeps the theme the user chose after the app is closed" timed out waiting for the dark-mode toggle, while the favourites relaunch test, on the same MMKV instance, passed. Re-run on its own, the theme test passed twice, and the full second run was clean, which suggests the flake came from the suite under load. The single `cocoapods` run had none.

A store that 4.3.2 wrote opens in 3.3.3. I set the dark theme and a favourite in the CocoaPods build, installed the SwiftPM build over it without deleting the app, and both were still there. That covers one unencrypted instance and two string values; the reminder's boolean was not set, so it was not read back.

The app is on SwiftPM; CocoaPods is still in the repo, and a fresh checkout cannot build yet.

## Remove CocoaPods and make a fresh checkout build

This is the last gate: the repo without CocoaPods, and a clone of it that builds on a machine with no Ruby.

`ios/Podfile.lock`, the Gemfile and its lockfile, `.bundle/`, `vendor/`, the workspace and the `# Ruby / CocoaPods` section of `.gitignore` go:



```bash
rm -rf ios/Podfile.lock Gemfile Gemfile.lock .bundle vendor ios/Pokedex.xcworkspace
sed -i '' '/^# Ruby \/ CocoaPods$/,/^\/vendor\/bundle\/$/d' .gitignore
Enter fullscreen mode Exit fullscreen mode

The post_install hook that raised deployment targets goes too, once the Podfile is reduced to a comment; the build passed without an equivalent, so no package in this app needed one. The Podfile itself does not go: version 20 of React Native's command-line interface (CLI) still uses it to find the iOS project.

CLI 20 still needs a Podfile

Deleting the Podfile shows why: with no Podfile and Ruby off PATH, the sync fails with "CLI config did not provide project.ios.sourceDir". npx react-native config reports project.ios: null with or without Ruby, because @react-native-community/cli-config-apple 20.x locates the iOS project with findPodfilePath and returns null without one. The comment above the check that returns null reads "The only file that we can assume to exist on disk is Podfile".

Setting project.ios.sourceDir in react-native.config.js does not help, since that only moves where the search starts. The fix is a three-line ios/Podfile holding a comment that says why it exists, plus project: { ios: { automaticPodsInstallation: false } } at the top level of react-native.config.js's export so run-ios does not try to install pods from it:

```ruby title="ios/Podfile"

This app builds with Swift Package Manager; there are no pods to install.

The file exists because @react-native-community/cli (20.x) finds the iOS project by looking

for a Podfile, and reports no iOS project without one, which breaks the SwiftPM sync.




The sync then completes in about two seconds with no `ruby`, `pod` or `bundle` on `PATH`.

`cli-config-apple@21.0.0-alpha.1` adds `findSpmProjectDir`, which reads the marker `react-native spm` injects into the Xcode project and takes precedence over the Podfile search. The comment-only Podfile is a workaround for CLI 20 and is not needed on CLI 21, so check your CLI version before copying it. In a copy of the finished app with the alpha installed and the Podfile deleted, `npx react-native config` finds the iOS project, `spm update` completes and the Release build exits 0.

### A fresh clone needs `spm update`

A fresh checkout exposes a separate setup step, and fails its first build without it. Delete `ios/build`, run `npx react-native spm sync`, build:



```text
the package at '.../ios/build/xcframeworks' cannot be accessed (... doesn't exist in file system)
xcodebuild: error: Could not resolve package dependencies
Enter fullscreen mode Exit fullscreen mode

spm sync runs three of the six steps setup-apple-spm.js lists for add and update: codegen, autolinking.json, the Autolinked manifest. The other three prepare the prebuilt frameworks, write build/xcframeworks/Package.swift with its symlinks and inject the packages into the Xcode project; spm update runs all six. ios/.gitignore lists build/xcframeworks/, so a fresh checkout has an Xcode project whose package references point at a directory nothing recreates before the first build. The pre-action runs sync, so it cannot help.

On CocoaPods the equivalent step was pod install, which the CLI ran for you. The 0.87 release post lists this among its known limitations, for fresh clones and continuous integration (CI) machines: "After a fresh clone, and in CI, run npx react-native spm once before building." On SwiftPM with CLI 20 it is npx react-native spm update, once, after npm install; the README says so, and that route, replayed on a fresh clone with no ruby, pod or bundle on PATH, ends in a clean Release build that succeeds. A postinstall hook could run it, but it would need Xcode during npm install and would download any artefacts missing from the cache, so I left it as a documented step.

Run that route on the finished app, in a fresh clone of the spm tag made from the folder that holds the opening's clone:

git clone https://github.com/warrendeleon/react-native-cocoapods-to-spm cocoapods-to-spm-finished
cd cocoapods-to-spm-finished
git checkout spm
npm install
npx react-native spm update
Enter fullscreen mode Exit fullscreen mode

The clone has to be fresh. In a clone where pod install has run and react-native-permissions has not been reinstalled since, the podspec inside node_modules is already rewritten, so the permissions patch no longer applies, npm install still exits 0, and spm update then stops on permissions as a mixed library.

What changed, measured

Both columns are clean simulator builds on the same Mac, the CocoaPods one through -workspace ios/Pokedex.xcworkspace, with x86_64 and arm64 in both apps and the dependency caches warm: React Native's prebuilt artefacts, and SwiftPM's copy of lottie-spm. The build re-created the 293 MiB checkout from that copy inside the 124.4 s. A cold cache, the first build on a CI machine, was not measured.

App, binary and framework sizes are file bytes divided by 1,000,000. Dependency stores are disk usage from /usr/bin/du -sh, in GiB and MiB; ios/Pods is from a fresh pod install of the cocoapods tag, where React-Core-prebuilt alone takes 638 MiB.

The CocoaPods numbers need one trap avoided. pod install runs React Native's codegen and writes the generated sources into ios/build/generated/, inside the directory the build uses for its products. Delete ios/build after pod install to make the build "clean" and the Pods project references 14 generated files that no longer exist. The order is delete, install, build.

CocoaPods SwiftPM
Dependency step after a clean checkout pod install, 15.3 s spm update, 5.7 s, run by hand once
Clean Release build 173.8 s 124.4 s
Warnings in the build log (warning: lines) 1,189 851
App bundle 78.2 MB 74.2 MB
Main binary 30.4 MB 20.7 MB
Frameworks/ 39.2 MB: React, Hermes, ReactNativeDependencies 45.0 MB: the same three, about 1 MB larger here, plus Lottie, now a 4.6 MB dynamic framework
Dependency store on disk ios/Pods, 1.3 GiB, per app ~/Library/Caches/ReactNative/spm-artifacts/0.88.1, 1.4 GiB, shared across apps; plus a 293 MiB lottie-spm checkout under ios/build
Ruby on the build machine needed not needed
Files in the repo for dependencies Podfile, Podfile.lock, Gemfile, Gemfile.lock, .bundle, a workspace six patches, a comment-only Podfile, react-native.config.js, ios/.gitignore, a marker file in the project, and the ios/ReactNativeSPM/ xcconfig and two scripts

A second clean SwiftPM build, from a fresh clone in another directory, took 159.2 s. CocoaPods was not rerun alongside it, so read the two SwiftPM figures as separate runs in different conditions.

Both builds use React Native's prebuilt frameworks: the CocoaPods side installed React-Core-prebuilt, so neither compiled React Core. The logs hold 1,088 CompileC steps for CocoaPods and 1,020 for SwiftPM, across both architectures. I did not time individual steps, so those counts do not explain the build-time difference, and the two builds differ in more than the package manager: Nitro and MMKVCore gone, mmkv 3.3.3, Lottie's core prebuilt. The community libraries compile from source on both, so a project whose build time is dominated by them may see less.

Part of the binary's shrink has a known cause: Lottie moved out into its own framework, which now counts under Frameworks/, and Nitro is gone. I did not compare symbols, so the rest of the difference is unexplained.

The warning counts include dependency diagnostics, JavaScript-bundle warnings and Xcode's own build warnings. I have not separated the causes of the difference.

What the six patches cost to keep

Part of the cost is waiting on React Native and its CLI, which have five issues of their own:

  1. Bundler and podspec naming: the first command, build 4.
  2. What the scaffolder leaves out and regenerates: build 5, build 6, build 11, and its idea of "mixed" in the scaffold.
  3. A scheme pre-action that runs after package resolution: build 3.
  4. A sync that leaves build/xcframeworks out: a fresh clone.
  5. Finding the iOS project by its Podfile, fixed in CLI 21.0.0-alpha.1: CLI 20.

Every patch is pinned to the version it was made against (react-native-screens+4.30.1.patch), so each library upgrade is a decision about its patch. A bump ends one of three ways:

  • The patch still applies. npm install prints a version-mismatch warning and leaves it to you to check that the package still behaves as you expect. Five of the six patches create Package.swift with a fixed list of sources, so one can apply cleanly to a version whose files have moved, and the build is where that shows.
  • The patch no longer applies. postinstall says so. Locally it still exits 0, so the install succeeds; on a CI machine --error-on-fail is on by default and the install fails. For a scaffolded library, regenerate its manifest from the new version's podspec and make the old patch's edits again by hand: a re-scaffold loses the manifest edits, and if the permissions podspec is unpatched, restore the handler selection too. Without pod, the regenerated manifest also loses sources, so compare its source list with the old patch's. For a library with its own or upstream's manifest, review that manifest instead. If the upgrade changes the library's native dependencies, check the new ones are supported before rebuilding the patch.
  • The new version ships its own Package.swift. The scaffolder leaves it alone, and the patch becomes a candidate for deletion. Delete it once the app builds and behaves without it; Lottie's shipped manifest is the reason to check.

On 1 November I applied two of this app's patches to the newest versions on npm, each in a scratch project. That checks whether a patch applies; I did not build the app on either version. The screens patch fails on the 30 October nightly, which ships its own Package.swift, so that release is a candidate to try without the patch. The Lottie patch fails on 8.0.0-rc.0, and there the upgrade takes the library off SwiftPM: the release candidate ships no Package.swift and depends on Nitro Modules, the library this post had to opt out. Both installs exit 0 locally and 1 with CI=true.

Where each patch stood on 1 November 2026, and what would retire it:

  1. react-native-svg: a release that ships the manifest on main. That manifest still excludes the Metal kernels, so feComposite's xor and arithmetic stay unavailable on SwiftPM.
  2. react-native-screens: a release that ships the manifest on main, which describes a source tree reorganised after 4.30.1 and so cannot be dropped onto 4.30.1. The 30 October nightly carries it.
  3. lottie-react-native: three upstream edits: lottie-spm for lottie-ios in the manifest, the two classes made public with their five overrides and two typealiases, and swiftpmConfig.name. The 8.0 release candidate moves to Nitro instead.
  4. react-native-permissions: no release has a SwiftPM equivalent of setup_permissions. Pull request #989, open since 20 October 2026, generates the manifest from a list in package.json, through an autolinking-plugin contract that React Native 0.88.1's own source marks "PREVIEW / UNSTABLE".
  5. react-native-mmkv: a Nitro release with SwiftPM support this app can take, and react-native-mmkv mapping its MMKVCore dependency to MMKV's own Package.swift. Nitro's support is only in the v1 alpha, and the one scaffolded manifest proposed to react-native-mmkv (pull request #1096) was closed unmerged by its author.
  6. @notifee/react-native: nothing would retire it yet. I found no SwiftPM proposal in its tracker, and its maintainers recommend expo-notifications.

Sources

Top comments (1)

Collapse
 
beusebiu profile image
Eusebiu Balan •

I carry a patch-package patch for react-native-mmkv too, from the Android side. It pinned C++ to 17, and React Native's bridging headers use C++20 requires, so the native build failed with "unknown type name 'requires'".

Nobody saw it for a while because only iOS had been built until then.