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

[CLAassistant]

All committers have signed the CLA.

[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!