feat(ios): add SPM dependency resolution support alongside CocoaPods by jsnavarroc · Pull Request #8933 · invertase/react-native-firebase

jsnavarroc · 2026-03-17T16:23:33Z

Summary

Add dual SPM/CocoaPods dependency resolution for Firebase iOS SDK via a centralized firebase_dependency() helper (packages/app/firebase_spm.rb)
When React Native >= 0.75 is detected, Firebase dependencies are resolved via Swift Package Manager (spm_dependency). For older versions or when explicitly disabled ($RNFirebaseDisableSPM = true), CocoaPods is used as fallback.
Solves Xcode 26 compilation errors caused by explicit modules not finding Firebase internal modules (FirebaseCoreInternal, FirebaseSharedSwift) when using CocoaPods

Changes

packages/app/firebase_spm.rb — New helper with firebase_dependency() function that auto-detects SPM support
packages/app/package.json — Added firebaseSpmUrl field as single source of truth
16 podspecs — Updated to use firebase_dependency() instead of direct s.dependency
43 native iOS files — Added #if __has_include guards for dual SPM/CocoaPods imports
CI matrix — Extended E2E workflow with dep-resolution: ['spm', 'cocoapods'] dimension (4 job combinations)
Unit tests — Added Ruby Minitest suite for firebase_spm.rb logic
Documentation — Added docs/ios-spm.md with architecture, integration guides, and troubleshooting

How it works

# Each podspec calls:
firebase_dependency(s, version, ['FirebaseAuth'], 'Firebase/Auth')

# Internally decides:
# - SPM path:      spm_dependency(spec, url: ..., products: ['FirebaseAuth'])
# - CocoaPods path: spec.dependency 'Firebase/Auth', version

Decision logic:

Is spm_dependency() defined? (RN >= 0.75 injects it) → YES → use SPM
Is $RNFirebaseDisableSPM set in Podfile? → YES → force CocoaPods
Neither available → fall back to CocoaPods

User-facing configuration

SPM mode (default for RN >= 0.75):

# ios/Podfile
linkage = 'dynamic'
use_frameworks! :linkage => linkage.to_sym

CocoaPods mode (legacy/opt-out):

# ios/Podfile
$RNFirebaseDisableSPM = true
linkage = 'static'
use_frameworks! :linkage => linkage.to_sym

Xcode 26 workaround (both modes):

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_ENABLE_EXPLICIT_MODULES'] = 'NO'
    end
  end
end

Test plan

Ruby unit tests pass (packages/app/__tests__/firebase_spm_test.rb)
CI: Code Quality Checks pass (clang-format, linting)
CI: E2E iOS debug + SPM passes
CI: E2E iOS debug + CocoaPods passes
CI: E2E iOS release + SPM passes
CI: E2E iOS release + CocoaPods passes
$RNFirebaseDisableSPM = true correctly forces CocoaPods
Log messages indicate which resolution mode is active

CLAassistant · 2026-03-17T16:23:45Z

All committers have signed the CLA.

vercel · 2026-03-17T16:23:58Z

@jsnavarroc is attempting to deploy a commit to the Invertase Team on Vercel.

A member of the Team first needs to authorize it.

Add dual SPM/CocoaPods dependency resolution for Firebase iOS SDK. When React Native >= 0.75 is detected, Firebase dependencies are resolved via Swift Package Manager (spm_dependency). For older versions or when explicitly disabled ($RNFirebaseDisableSPM = true), CocoaPods is used. Changes: - Add firebase_spm.rb helper with firebase_dependency() function - Add firebaseSpmUrl to packages/app/package.json (single source of truth) - Update all 16 podspecs to use firebase_dependency() - Add #if __has_include guards in 43 native iOS files for dual imports - Add CI matrix (spm × cocoapods × debug × release) in E2E workflow - Add Ruby unit tests for firebase_spm.rb - Add documentation at docs/ios-spm.md

…dSupport is true When $RNFirebaseAnalyticsWithoutAdIdSupport = true with SPM enabled, FirebaseAnalytics pulls in GoogleAppMeasurement which contains APMETaskManager and APMMeasurement cross-references. These cause linker errors when FirebasePerformance is not installed. Switch to FirebaseAnalyticsCore (-> GoogleAppMeasurementCore) in that case, which has no IDFA and no APM symbols. CocoaPods path is unchanged. docs: add Section 8 with 5 real integration bugs found during tvOS Xcode 26 migration and their solutions

fix(analytics): use FirebaseAnalyticsCore when WithoutAdIdSupport + SPM

jsnavarroc · 2026-03-18T17:07:02Z

Additional fix included: `FirebaseAnalyticsCore` when SPM + `$RNFirebaseAnalyticsWithoutAdIdSupport = true`

While integrating this PR in a tvOS app (React Native tvOS 0.77, Xcode 26), we encountered a linker error that is only triggered when all three conditions are true simultaneously:

SPM dependency resolution is active (this PR)
$RNFirebaseAnalyticsWithoutAdIdSupport = true in Podfile
FirebasePerformance is not installed

Linker error

Undefined symbols for architecture arm64:
  "_OBJC_CLASS_$_APMETaskManager"
  "_OBJC_CLASS_$_APMMeasurement"

Root cause

The FirebaseAnalytics SPM product resolves to GoogleAppMeasurement, which contains cross-references to APMETaskManager and APMMeasurement (Firebase Performance classes). When FirebasePerformance is not in the project, those symbols are missing at link time.

The fix: when SPM + WithoutAdIdSupport = true, use FirebaseAnalyticsCore instead — it resolves to GoogleAppMeasurementCore (no IDFA, no APM dependencies).

Fix applied in `RNFBAnalytics.podspec`

if defined?(spm_dependency) && !defined?($RNFirebaseDisableSPM) &&
   defined?($RNFirebaseAnalyticsWithoutAdIdSupport) && $RNFirebaseAnalyticsWithoutAdIdSupport
  firebase_dependency(s, firebase_sdk_version, ['FirebaseAnalyticsCore'], 'FirebaseAnalytics/Core')
else
  firebase_dependency(s, firebase_sdk_version, ['FirebaseAnalytics'], 'FirebaseAnalytics/Core')
end

This change is fully backwards compatible — all existing paths (CocoaPods, SPM without the flag, SPM with IDFA) are unchanged.

This fix is already included in the current head of this PR. Happy to extract it into a separate PR if preferred.

Context: why SPM matters for React Native in 2026

This article is highly relevant for the community — it covers the broader roadmap and real-world pain points of migrating React Native apps to SPM, including the Xcode 26 requirement and Firebase-specific issues:

📖 React Native — Roadmap to Swift Package Manager 2026

jsnavarroc · 2026-03-18T17:14:21Z

Hey @mikehardy — could you approve the workflows to run on this PR when you get a chance?

The CI checks are blocked waiting for maintainer approval. Happy to address any feedback once they run.

Thanks!

mikehardy

Wow! This is pretty amazing. Thank you for proposing this - just finished first pass review and while I left comments all over the place I hope none of that gives the feeling that this isn't amazing, and that we won't merge SPM support, it is something this repository obviously needs. So again, thank you

But then of course there are all the comments with some specific questions, some pings out to a firebase-ios-sdk maintainer (hi Paul 👋 ) that I collaborate with on occasion, and some notes to myself regarding testing

mikehardy · 2026-03-19T12:28:11Z

.github/workflows/tests_e2e_ios.yml

-          key: ${{ runner.os }}-ios-pods-v3-${{ hashFiles('tests/ios/Podfile.lock') }}
-          restore-keys: ${{ runner.os }}-ios-pods-v3
+          key: ${{ runner.os }}-ios-pods-v3-${{ matrix.dep-resolution }}-${{ hashFiles('tests/ios/Podfile.lock') }}
+          restore-keys: ${{ runner.os }}-ios-pods-v3-${{ matrix.dep-resolution }}


I prefer the variable interpolations at the front and all together and the various naming / key "sauce" at the end

Suggested change

restore-keys: ${{ runner.os }}-ios-pods-v3-${{ matrix.dep-resolution }}

restore-keys: ${{ runner.os }}-${{ matrix.dep-resolution }}-ios-pods-v3

mikehardy · 2026-03-19T12:32:29Z

packages/analytics/ios/RNFBAnalytics/RNFBAnalyticsModule.m

 #import <Firebase/Firebase.h>
+#else
+@import FirebaseCore;
+@import FirebaseAnalytics;


Taking note of your comment here on the FirebasePerformance symbols missing at link time if ad ids are disabled does this FirebaseAnalytics import still work here in the FirebaseAnalyticsCore dependency case? #8933 (comment)

mikehardy · 2026-03-19T12:34:25Z

packages/analytics/RNFBAnalytics.podspec

-    Pod::UI.puts "#{s.name}: Not installing FirebaseAnalytics/IdentitySupport Pod, no IDFA will be collected."
+  # Analytics has conditional dependencies that vary between SPM and CocoaPods.
+  # SPM: use FirebaseAnalyticsWithoutAdIdSupport when $RNFirebaseAnalyticsWithoutAdIdSupport = true
+  #      to avoid GoogleAppMeasurement APM symbols that require FirebaseRemoteConfig (linker error).


was it FirebasePerformance symbols or FirebaseRemoteConfig symbols missing at link time? The comment on the PR and the comment here in code and slightly lower in code are inconsistent 🤔

mikehardy · 2026-03-19T12:36:34Z

packages/analytics/RNFBAnalytics.podspec

+    s.frameworks =       'AdSupport'
+  end
+
+  # GoogleAdsOnDeviceConversion (CocoaPods only, not available in firebase-ios-sdk SPM)


Is there some documentation on how to access on-device conversion in the SPM case? This is surprising to me as I thought on-device conversion was one of the newer features of firebase-ios-sdk which creates the expectation in me that it should be available there somehow ? Perhaps just built in to core SPM dep I'm not sure

mikehardy · 2026-03-19T12:39:34Z

packages/app-check/ios/RNFBAppCheck/RNFBAppCheckModule.m

+#if __has_include(<Firebase/Firebase.h>)
 #import <Firebase/Firebase.h>
-#import <FirebaseAppCheck/FIRAppCheck.h>
+#elif __has_include(<FirebaseAppCheck/FirebaseAppCheck.h>)
+#import <FirebaseAppCheck/FirebaseAppCheck.h>


<Firebase/Firebase.h> will always be found in the CocoaPods case won't it? It's the most fundamental header if I understand correctly. Does it transitively include <FirebaseAppCheck/FIRAppCheck.h> such that the explicit import is no longer required then (or maybe was never required?). Surprising this compiles as I think that preprocessor branch is likely the only __has_include branch that will ever be taken, and it makes me think the #elif __has_include(<FirebaseAppCheck/FirebaseAppCheck.h>) branch may not even be needed, I can't see how <Firebase/Firebase.h> won't be found

mikehardy · 2026-03-19T13:31:23Z

packages/app/README.md

+Add this line at the top of your Podfile (before any `target` block):
+
+```ruby
+# Podfile
+$RNFirebaseDisableSPM = true
+```
+
+This forces all RNFB modules to use traditional `s.dependency` CocoaPods declarations.
+You can use either static or dynamic linkage with this option.


Similarly - if there is something Expo people need to do to add a Podfile directive we'll need to explain it here or we'll have a lot of issues opened in the repo later about it

mikehardy · 2026-03-19T13:33:02Z

packages/app/firebase_spm.rb

+
+# Read Firebase SPM URL from app package.json (single source of truth)
+$firebase_spm_url ||= begin
+  app_package_path = File.join(__dir__, 'package.json')


maintainer note to check this as recommended relative/package-local file resolution style (as well as the includes of this file from other packages) for all cases - including monorepos with possible package hoists, pnpm etc

mikehardy · 2026-03-19T13:38:27Z

packages/app/firebase_spm.rb

+# Set `$RNFirebaseDisableSPM = true` in your Podfile to force CocoaPods-only
+# dependency resolution. This is required when using `use_frameworks! :linkage => :static`
+# because static frameworks cause each pod to embed Firebase SPM products,
+# resulting in duplicate symbol linker errors.


This in This is required... is perhaps ambiguous for something this important

Suggested change

# Set `$RNFirebaseDisableSPM = true` in your Podfile to force CocoaPods-only

# dependency resolution. This is required when using `use_frameworks! :linkage => :static`

# because static frameworks cause each pod to embed Firebase SPM products,

# resulting in duplicate symbol linker errors.

# Set `$RNFirebaseDisableSPM = true` in your Podfile to force CocoaPods-only

# dependency resolution. You must disable SPM when using `use_frameworks! :linkage => :static`

# because static frameworks cause each pod to embed Firebase SPM products,

# resulting in duplicate symbol linker errors.

But a further question - the implication is that static frameworks and SPM are simply incompatible (because of duplicate symbols). Is that true? Is there a definitive upstream statement that firebase-ios-sdk, when used via SPM, must always be dynamic frameworks? (vs the Cocoapods path where both are/were supported?)

If there is a definitive statement about this requirement I'd prefer to just state it as a requirement without elaboration and reference the definitive statement via URL for context. If there is no definitive statement then perhaps it could be added in docs upstream via request

mikehardy · 2026-03-19T13:42:06Z

packages/analytics/RNFBAnalytics.podspec

@@ -1,4 +1,5 @@
 require 'json'
+require '../app/firebase_spm'


maintainer note (mirrored in similar note in firebase_spm.rb itself) to verify this is okay in monorepo (possibly hoisted)/pnpm/etc cases - there is likely a known-good inter-package local file resolution mechanism and it is likely not a simple ../<packagename>/ path unfortunately

mikehardy · 2026-03-19T13:43:58Z

DOCUMENTACION_SPM_IMPLEMENTACION.md

@@ -0,0 +1,1135 @@
+# Documentacion Completa: Soporte Dual SPM + CocoaPods para Firebase en React Native


Creo que este archivo markdown sea lo mismo como docs/ios_spm.md pero en español y menos obvio para desarrolladores - pienso que debe borrar este ?

jsnavarroc force-pushed the main branch from 388cc49 to 05eea19 Compare March 17, 2026 19:28

jsnavarroc and others added 2 commits March 18, 2026 11:55

fix(analytics): use FirebaseAnalyticsCore when WithoutAdIdSupport + SPM

27dde8d

fix(analytics): use FirebaseAnalyticsCore when WithoutAdIdSupport + SPM

github-actions bot added the Needs Attention label Mar 18, 2026

mikehardy requested changes Mar 19, 2026

View reviewed changes

mikehardy added Workflow: Waiting for User Response Blocked waiting for user response. Workflow: Needs Review Pending feedback or review from a maintainer. and removed Needs Attention labels Mar 19, 2026

	restore-keys: ${{ runner.os }}-ios-pods-v3-${{ matrix.dep-resolution }}
	restore-keys: ${{ runner.os }}-${{ matrix.dep-resolution }}-ios-pods-v3

		@@ -0,0 +1,1135 @@
		# Documentacion Completa: Soporte Dual SPM + CocoaPods para Firebase en React Native

Conversation

jsnavarroc commented Mar 17, 2026

Summary

Changes

How it works

User-facing configuration

Test plan

Uh oh!

CLAassistant commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Mar 17, 2026

Uh oh!

jsnavarroc commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Additional fix included: FirebaseAnalyticsCore when SPM + $RNFirebaseAnalyticsWithoutAdIdSupport = true

Linker error

Root cause

Fix applied in RNFBAnalytics.podspec

Context: why SPM matters for React Native in 2026

Uh oh!

jsnavarroc commented Mar 18, 2026

Uh oh!

mikehardy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

CLAassistant commented Mar 17, 2026 •

edited

Loading

jsnavarroc commented Mar 18, 2026 •

edited

Loading

Additional fix included: `FirebaseAnalyticsCore` when SPM + `$RNFirebaseAnalyticsWithoutAdIdSupport = true`

Fix applied in `RNFBAnalytics.podspec`