feat(ios): add SPM dependency resolution support alongside CocoaPods

[jsnavarroc]

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:

1. Is spm_dependency() defined? (RN >= 0.75 injects it) → YES → use SPM
2. Is $RNFirebaseDisableSPM set in Podfile? → YES → force CocoaPods
3. 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

related issue: #9010

---

Note

Medium Risk
Medium risk because it changes iOS dependency/linkage and native import behavior across many modules, which can break builds in certain Xcode/React Native configurations despite added CI coverage.

Overview
Introduces a centralized firebase_dependency() helper (packages/app/firebase_spm.rb) that switches RNFirebase iOS Firebase dependencies between SPM (RN >= 0.75 by default) and CocoaPods (fallback or $RNFirebaseDisableSPM), with the SPM repo URL sourced from packages/app/package.json.

Updates all affected RNFirebase module podspecs to use the helper (including special-casing Analytics’ SPM vs CocoaPods behavior), adjusts numerous iOS sources to compile under both header layouts via __has_include/module imports, and extends Crashlytics symbol upload scripting to find the SPM checkout.

Expands iOS E2E CI to run a matrix over spm/cocoapods × debug/release (including mode-specific Podfile edits and cache keys), adds Ruby unit tests for the helper and runs them in the Jest workflow, and adds new SPM documentation plus a local SPM verification screen.

^{Reviewed by Cursor Bugbot for commit 496d97c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
2 out of 3 committers have signed the CLA.

✅ jsnavarroc
✅ russellwheatley
❌ Johan Navarro

---

Johan Navarro seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[vercel]

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

A member of the Team first needs to authorize it.

[jsnavarroc]

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:

1. SPM dependency resolution is active (this PR)
2. $RNFirebaseAnalyticsWithoutAdIdSupport = true in Podfile
3. 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]

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]

Hey @jsnavarroc 👋 just a gentle ping on this - are you interested in / have time to work on moving this forward? Happy to collaborate, and it's a pretty important feature so I'm very interested personally. Curious for your thoughts

[jsnavarroc]

Hey @mikehardy! Yes, absolutely, I'm actively working on this and just pushed a new commit addressing all the review comments. Sorry for the delay.

Changes in the latest commit

1. Cache key order: Reordered per your suggestion (variable interpolations first)
2. Analytics podspec comment inconsistency: Fixed, it's FirebasePerformance (APM symbols), not RemoteConfig
3. GoogleAdsOnDeviceConversion: Added clear documentation about SPM incompatibility + runtime warning when user tries to enable it in SPM mode
4. AppCheckModule.m spacing: Reverted all unrelated spacing changes, kept only the #if __has_include import block
5. .npmignore: Added clarifying comment about the !ios/RNFBApp/RNFBVersion.m inclusion and the lack of a files array in package.json
6. RNFBML.podspec: Removed old commented-out s.dependency and raise lines
7. firebase_spm.rb: Improved static linkage comment with upstream context, added monorepo/pnpm path resolution note
8. README: Added Expo section, reframed dynamic/static in terms of pre-built RN core, added monorepo/pnpm notes
9. ios_config.sh: Replaced find with known deterministic path for SPM upload-symbols
10. DOCUMENTACION_SPM_IMPLEMENTACION.md: Deleted (was a Spanish duplicate of docs/ios-spm.md)

Ask

If you or anyone on the team has bandwidth to test this branch on different devices/platforms (iOS, tvOS, macCatalyst) and with different configurations (SPM vs CocoaPods, dynamic vs static), that would be incredibly valuable. I've verified it on iOS 26 simulator and tvOS 26 (Apple TV) but broader coverage would help catch edge cases before merge.

I'll reply to each individual review comment below with details.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 496d97c. Configure here.}

[paulb777]

Great to see the progress in this PR! I'm cc'ing @ncooke3, who is now a better contact than me for the firebase-ios-sdk questions in the comments.

[jsnavarroc]

Heads up: tvOS + Xcode 26 hybrid SPM/CocoaPods edge case worth documenting

While integrating this PR in a tvOS React Native project (hybrid CocoaPods + SPM resolution, Xcode 26, RN 0.77 with react-native-tvos), I ran into a subtle TestFlight-only crash that took considerable time to diagnose. Sharing here so maintainers can decide if it's worth adding a warning or a note in the docs.

Symptom

• App launches fine on tvOS simulator ✅
• App launches fine when installed directly from Xcode onto a real Apple TV (WiFi pairing or USB-C) ✅
• App crashes immediately at launch (<200ms, pre-main()) when the same archive is uploaded via Fastlane and installed from TestFlight ❌

No formal crash log is generated, ReportCrash logs Failed to create bundle record because the process dies too early. The only signal in the system log (from Console.app connected to the device) is:

PineBoard  [app<com.example.myapp>:738] Now flagged as pending exit for reason: launch failed
PineBoard  [app<com.example.myapp>:738] Process exited:
  <RBSProcessExitContext| specific, status:<RBSProcessExitStatus| domain:dyld(6) code:0>>.

Root cause

The combination that triggers it:

1. Firebase resolved via SPM (source packages, statically linked into the main app binary)
2. @react-native-firebase/* frameworks compiled as dynamic frameworks with -undefined dynamic_lookup (necessary in hybrid setup to avoid duplicate Firebase class registrations, as documented in other threads)
3. Release configuration with default stripping settings (DEAD_CODE_STRIPPING=YES, STRIP_SWIFT_SYMBOLS=YES, etc.)

The Release + TestFlight pipeline strips Firebase symbols from the main binary's dynamic symbol table because the static analyzer sees them as "unused", nothing in the binary statically references them, RNFB frameworks resolve them at runtime via flat-namespace dynamic lookup. When dyld tries to resolve them on device after TestFlight processing, they're gone. Local Xcode installs don't exhibit this because development builds don't apply the same aggressive stripping.

Diagnostic evidence

Before fix (binary that crashed in TestFlight):

• Main app binary size: 3.3 MB
• nm -g <binary> | grep "FIR" | wc -l → 0
• nm -g <binary> | grep "InstallationIDDidChange" → nothing

After fix (binary that works in TestFlight):

• Binary size: 6.0 MB (+80%)
• nm -g <binary> | grep "FIR" | wc -l → 692
• nm -g <binary> | grep "InstallationIDDidChange" → S _FIRInstallationIDDidChangeNotification

Workaround

Anti-stripping settings on the main app target's Release configuration + exporting static symbols to the dynamic symbol table, added via post_install hook in the integrator's Podfile:

main_target.build_configurations.each do |cfg|
  next unless cfg.name == 'Release'
  cfg.build_settings['STRIP_SWIFT_SYMBOLS'] = 'NO'
  cfg.build_settings['DEAD_CODE_STRIPPING'] = 'NO'
  cfg.build_settings['STRIP_INSTALLED_PRODUCT'] = 'NO'
  cfg.build_settings['COPY_PHASE_STRIP'] = 'NO'
  cfg.build_settings['DEPLOYMENT_POSTPROCESSING'] = 'NO'
  ldflags = Array(cfg.build_settings['OTHER_LDFLAGS'] || ['$(inherited)'])
  ldflags << '-Wl,-export_dynamic' unless ldflags.include?('-Wl,-export_dynamic')
  cfg.build_settings['OTHER_LDFLAGS'] = ldflags
end

This belongs in the integrator's Podfile, not in the library, because it's specific to the hybrid linkage strategy and tvOS, and would be intrusive for iOS projects that don't need it (binary size doubles, Release optimizations disabled).

Suggestion

Since this is very hard to diagnose without the crashlog (which doesn't get generated) and only manifests after TestFlight upload (long iteration cycle), it might be worth considering one of:

1. A non-blocking warning during pod install when the risky combination is detected (platform: tvos + SPM active + main target missing anti-stripping in Release), pointing to the fix.
2. A troubleshooting section in the README / docs/ios-spm.md documenting the symptom and the Podfile snippet.

Happy to open a separate PR with either approach if maintainers think it's worth it, fully understand if you'd rather keep this PR focused and tackle it separately later. Flagging it here so it doesn't get lost.

Context: reproducible on my setup (Apple TV 4K, tvOS 26, Xcode 26.3, use_frameworks! :linkage => :static, Firebase iOS SDK 12.x via SPM). Others on the same configuration may hit it too.

cc @ncooke3 (per @paulb777's earlier comment pointing to you for firebase-ios-sdk questions), sharing in case this stripping interaction is relevant on the Firebase SDK side.

[ncooke3]

Hi @jsnavarroc, nice testing & investigation! If you didn't consider it, adding the -ObjC linker flag could possibly be an additional path that may (or may not) work, though it's not as precise as the workaround you documented. I'm unsure if it handles the risk of duplicate symbols.

In any case, I'll defer to @mikehardy here, but your suggestions sound reasonable.

[mikehardy]

looks pretty good in general - huge but given how profound the change is and how intractable some of the difficulties are it all holds together

some observations but no problems with the general direction / decisions just ergonomics / DX type things

[mikehardy]

I gave it a scan last night and all the stuff I noticed appears to be fixed

Please DO NOT MERGE until v26 is out, I want to make sure (as described in comments above) that we release the current batch of breaking changes before this goes out, since this is such a large change