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

.github/workflows/scripts/configure-ios-dep-resolution.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Configure tests/ios/Podfile for the CI dependency-resolution matrix leg (spm vs cocoapods).
+# Shared by both "Configure Dependency Resolution Mode" steps in tests_e2e_ios.yml
+# (the `ios` job and the `ios-release-archive` job) so the two legs can't drift apart.
+#
+# Usage: configure-ios-dep-resolution.sh <spm|cocoapods> [podfile-dir]
+#   podfile-dir defaults to tests/ios, since every caller in tests_e2e_ios.yml runs
+#   with the workflow's default working directory (the repo root).
+#
+# spm mode is a no-op: the checked-in Podfile already resolves Firebase via SPM
+# (dynamic linkage, no $RNFirebaseDisableSPM flag -- see packages/app/firebase_spm.rb).
+#
+# cocoapods mode patches the Podfile to force static linkage and disable SPM
+# resolution. Each patch is grep-verified immediately after being applied, so a future
+# change to the Podfile's wording (e.g. reformatting `linkage = 'dynamic'`) fails this
+# script loudly instead of silently leaving the "cocoapods" CI leg testing the SPM path
+# a second time.
+set -euo pipefail
+
+log_dep_resolution() {
+  echo "[dep-resolution] $*"
+}
+
+configure_cocoapods_mode() {
+  local podfile_dir="$1"
+  local podfile="${podfile_dir}/Podfile"
+
+  log_dep_resolution "configuring CocoaPods-only mode (disabling SPM) in ${podfile}"
+
+  sed -i '' "s/^linkage = 'dynamic'/linkage = 'static'/" "$podfile"
+  grep -q "^linkage = 'static'" "$podfile" || {
+    log_dep_resolution "ERROR: expected \"linkage = 'static'\" in ${podfile} after sed, but it was not found -- has the Podfile's linkage line wording changed?"
+    exit 1
+  }
+
+  printf '%s\n' '$RNFirebaseDisableSPM = true' | cat - "$podfile" > "${podfile}.tmp" && mv "${podfile}.tmp" "$podfile"
+  local first_line
+  first_line="$(head -n 1 "$podfile")"
+  [[ "$first_line" == '$RNFirebaseDisableSPM = true' ]] || {
+    log_dep_resolution "ERROR: expected the first line of ${podfile} to be '\$RNFirebaseDisableSPM = true' after prepend, got: ${first_line}"
+    exit 1
+  }
+
+  log_dep_resolution "Podfile configured for CocoaPods-only mode"
+}
+
+configure_spm_mode() {
+  log_dep_resolution "using default SPM mode (dynamic linkage)"
+}
+
+MODE="${1:-}"
+PODFILE_DIR="${2:-tests/ios}"
+
+case "$MODE" in
+  cocoapods)
+    configure_cocoapods_mode "$PODFILE_DIR"
+    ;;
+  spm)
+    configure_spm_mode
+    ;;
+  *)
+    log_dep_resolution "ERROR: unrecognized dependency-resolution mode '${MODE}' (expected 'spm' or 'cocoapods')"
+    exit 1
+    ;;
+esac

.github/workflows/scripts/simulator-logging.sh

@@ -9,7 +9,13 @@ restart_simulator_logging() {
   local sim_app_log="${log_dir}/sim-app.log"
   local resource_log="${log_dir}/resource-monitor.log"
   local repo_root="${RNFB_REPO_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)}"
-  local log_predicate='process == "testing" OR (process == "SpringBoard" AND eventMessage CONTAINS "invertase") OR eventMessage CONTAINS[c] "RNFBStorage" OR eventMessage CONTAINS[c] "FIRStorage" OR eventMessage CONTAINS[c] "StorageTask"'
+  # dyld logs its own fatal-launch-failure reason (e.g. "Symbol not found" / "Library not
+  # loaded") directly to the unified log via subsystem com.apple.dyld, independently of
+  # ReportCrash (which this workflow disables for CI performance -- see "Install yeetd and
+  # fix iOS perf issues" step -- so no .ips crash report is ever produced). Capture it here
+  # instead so launch-time dyld failures (e.g. release+spm launch timeouts) are diagnosable
+  # from sim-app.log without re-enabling the crash reporter daemon.
+  local log_predicate='process == "testing" OR (process == "SpringBoard" AND eventMessage CONTAINS "invertase") OR subsystem == "com.apple.dyld" OR eventMessage CONTAINS[c] "dyld"'
 
   if ! xcrun simctl list devices booted 2>/dev/null | grep -q Booted; then
     echo "[boot-status] phase=log_streams skipped=no_booted_simulator"

.github/workflows/scripts/verify-ios-release-archive.sh

@@ -0,0 +1,119 @@
+#!/bin/bash
+# Archive the iOS test app for a real device destination (unsigned) and verify
+# the app bundle it produces is actually runnable, i.e. every dynamic
+# framework any embedded binary depends on is present in Frameworks/.
+#
+# Why this exists: the CI matrix in tests_e2e_ios.yml only ever runs
+# `xcodebuild build -sdk iphonesimulator`. The "Archive" action is materially
+# different -- Xcode forces ONLY_ACTIVE_ARCH=NO and DEPLOYMENT_POSTPROCESSING=YES
+# (full stripping / install-style processing) for Archive regardless of what
+# the project/Podfile sets, and it targets a real device SDK, not the
+# simulator SDK. That is precisely the difference between "works when Xcode
+# installs it on a real device or in Simulator" and "crashes only from a
+# TestFlight/Fastlane archive" reported against this PR:
+# https://github.com/invertase/react-native-firebase/pull/8933#issuecomment-4308578826
+# and the release+SPM dyld launch failure fixed by
+# packages/app/firebase_spm.rb's embed phase (see
+# okf-bundle/ios-spm-native-imports.md "Runtime framework embedding"), which
+# was itself only ever validated against a Release-iphonesimulator build.
+#
+# This script does not require a signing identity or provisioning profile --
+# it produces an unsigned .xcarchive purely to exercise the real Archive
+# build settings and inspect the resulting app bundle. It is not a substitute
+# for an actual signed TestFlight/device install, but it catches the same
+# class of "framework built, but never embedded / stripped at archive time"
+# regression automatically, on every PR, without needing device hardware or
+# Apple signing credentials in CI.
+set -euo pipefail
+
+WORKSPACE="${RNFB_ARCHIVE_WORKSPACE:-testing.xcworkspace}"
+SCHEME="${RNFB_ARCHIVE_SCHEME:-testing}"
+CONFIGURATION="${RNFB_ARCHIVE_CONFIGURATION:-Release}"
+ARCHIVE_PATH="${RNFB_ARCHIVE_PATH:-build/testing.xcarchive}"
+
+log() {
+  echo "[ios-release-archive] $*"
+}
+
+rm -rf "$ARCHIVE_PATH"
+
+log "archiving scheme=${SCHEME} configuration=${CONFIGURATION} destination=generic/platform=iOS (unsigned) -> ${ARCHIVE_PATH}"
+
+set -o pipefail
+xcodebuild archive \
+  CC=clang CPLUSPLUS=clang++ LD=clang LDPLUSPLUS=clang++ \
+  -workspace "$WORKSPACE" \
+  -scheme "$SCHEME" \
+  -configuration "$CONFIGURATION" \
+  -destination 'generic/platform=iOS' \
+  -archivePath "$ARCHIVE_PATH" \
+  CODE_SIGN_IDENTITY="" \
+  CODE_SIGNING_REQUIRED=NO \
+  CODE_SIGNING_ALLOWED=NO \
+  CODE_SIGN_ENTITLEMENTS="" \
+  | xcbeautify
+
+APP_DIR="$(find "${ARCHIVE_PATH}/Products/Applications" -maxdepth 1 -name '*.app' 2>/dev/null | head -1)"
+if [[ -z "$APP_DIR" || ! -d "$APP_DIR" ]]; then
+  log "ERROR: no .app product found under ${ARCHIVE_PATH}/Products/Applications"
+  exit 1
+fi
+
+APP_NAME="$(basename "$APP_DIR" .app)"
+MAIN_BINARY="${APP_DIR}/${APP_NAME}"
+FRAMEWORKS_DIR="${APP_DIR}/Frameworks"
+
+log "app product: ${APP_DIR}"
+lipo -info "$MAIN_BINARY" 2>&1 | sed 's/^/[ios-release-archive]   /' || true
+
+if [[ -d "$FRAMEWORKS_DIR" ]]; then
+  log "embedded frameworks in ${FRAMEWORKS_DIR}:"
+  ls -1 "$FRAMEWORKS_DIR" | sed 's/^/[ios-release-archive]   /'
+else
+  log "no ${FRAMEWORKS_DIR} directory (expected for static-linkage/CocoaPods-only configs; continuing)"
+fi
+
+# Every *.framework a binary loads via @rpath must actually be embedded --
+# this is the exact regression class fixed by packages/app/firebase_spm.rb's
+# embed phase (missing FirebaseAppCheckInterop.framework /
+# FirebaseAuthInterop.framework), re-checked here at real Archive-action
+# fidelity rather than a plain simulator build.
+missing=0
+
+check_binary() {
+  local binary="$1"
+  local label="$2"
+  local dep fw_name
+
+  while IFS= read -r dep; do
+    [[ -z "$dep" ]] && continue
+    case "$dep" in
+      /System/*|/usr/lib/*) continue ;;
+    esac
+    fw_name="$(echo "$dep" | sed -E 's#.*/([^/]+\.framework)/.*#\1#')"
+    # Not a @rpath/Foo.framework/Foo style dependency -- nothing to check.
+    [[ "$fw_name" == "$dep" ]] && continue
+    if [[ ! -e "${FRAMEWORKS_DIR}/${fw_name}" ]]; then
+      log "MISSING: ${label} depends on ${fw_name} but it is not embedded in ${FRAMEWORKS_DIR}"
+      missing=$((missing + 1))
+    fi
+  done < <(otool -L "$binary" 2>/dev/null | tail -n +2 | awk '{print $1}')
+}
+
+check_binary "$MAIN_BINARY" "${APP_NAME} (main app binary)"
+
+if [[ -d "$FRAMEWORKS_DIR" ]]; then
+  for fw_bundle in "$FRAMEWORKS_DIR"/*.framework; do
+    [[ -d "$fw_bundle" ]] || continue
+    fw_binary_name="$(basename "$fw_bundle" .framework)"
+    fw_binary="${fw_bundle}/${fw_binary_name}"
+    [[ -f "$fw_binary" ]] && check_binary "$fw_binary" "${fw_binary_name}.framework"
+  done
+fi
+
+if [[ "$missing" -gt 0 ]]; then
+  log "FAILED: ${missing} missing framework dependency(ies) found in the real device archive -- see MISSING lines above"
+  exit 1
+fi
+
+log "OK: every embedded binary's @rpath framework dependencies are present in the archived app bundle"

.github/workflows/tests_e2e_ios.yml

@@ -90,17 +90,21 @@ jobs:
             // we want to test debug and release - they generate different code
             let buildmode = ['debug', 'release'];
 
+            // Test both SPM and CocoaPods dependency resolution modes
+            let depResolution = ['spm', 'cocoapods'];
+
             return {
               "iteration": iterationArray,
-              "buildmode": buildmode
+              "buildmode": buildmode,
+              "dep-resolution": depResolution
             }
       - name: Debug Output
         run: echo "${{ steps.build-matrix.outputs.result }}"
 
   # This uses the matrix generated from the matrix-prep stage
   # it will run unit tests on whatever OS combinations are desired
   ios:
-    name: iOS (${{ matrix.buildmode }}, ${{ matrix.iteration }})
+    name: iOS (${{ matrix.buildmode }}, ${{ matrix.dep-resolution }}, ${{ matrix.iteration }})
     runs-on: macos-26
     needs: matrix_prep
     # TODO matrix across APIs, at least 11 and 15 (lowest to highest)
@@ -210,7 +214,7 @@ jobs:
       - uses: hendrikmuhs/ccache-action@d62db5f07c26379fc4b4e0916f098a92573c3b03 # v1.2.23
         name: Xcode Compile Cache
         with:
-          key: ${{ runner.os }}-${{ matrix.buildmode }}-ios-v3 # makes a unique key w/related restore key internally
+          key: ${{ runner.os }}-${{ matrix.buildmode }}-${{ matrix.dep-resolution }}-ios-v3 # makes a unique key w/related restore key internally
           save: "${{ github.ref == 'refs/heads/main' }}"
           create-symlink: true
           max-size: 1500M
@@ -255,8 +259,11 @@ jobs:
         continue-on-error: true
         with:
           path: tests/ios/Pods
-          key: ${{ runner.os }}-ios-pods-v3-${{ hashFiles('tests/ios/Podfile.lock') }}
-          restore-keys: ${{ runner.os }}-ios-pods-v3
+          key: ${{ runner.os }}-${{ matrix.dep-resolution }}-ios-pods-v3-${{ hashFiles('tests/ios/Podfile.lock') }}
+          restore-keys: ${{ runner.os }}-${{ matrix.dep-resolution }}-ios-pods-v3
+
+      - name: Configure Dependency Resolution Mode
+        run: .github/workflows/scripts/configure-ios-dep-resolution.sh "${{ matrix.dep-resolution }}"
 
       - name: Pod Install
         # https://github.com/nick-fields/retry/releases
@@ -560,3 +567,140 @@ jobs:
         with:
           path: ${{ steps.workflow-variables.outputs.metro-cache }}
           key: ${{ steps.metro-bundler-cache.outputs.cache-primary-key }}
+
+  # Simulator/dev builds never exercise Xcode's "Archive" action, which forces
+  # ONLY_ACTIVE_ARCH=NO and DEPLOYMENT_POSTPROCESSING=YES (full install-style
+  # stripping) for a real device SDK regardless of project settings -- the
+  # exact difference between "works from Xcode/simulator" and "crashes only
+  # from a TestFlight/Fastlane archive" reported against SPM support in this
+  # repo. This job produces a real, unsigned device archive (no signing
+  # identity/provisioning profile needed) and verifies the resulting app
+  # bundle is actually loadable. See .github/workflows/scripts/verify-ios-release-archive.sh
+  # and okf-bundle/ios-spm-native-imports.md "Runtime framework embedding".
+  ios-release-archive:
+    name: iOS Release Archive (${{ matrix.dep-resolution }})
+    runs-on: macos-26
+    timeout-minutes: 45
+    env:
+      CCACHE_SLOPPINESS: clang_index_store,file_stat_matches,include_file_ctime,include_file_mtime,ivfsoverlay,pch_defines,modules,system_headers,time_macros
+      CCACHE_FILECLONE: true
+      CCACHE_DEPEND: true
+      CCACHE_INODECACHE: true
+      CCACHE_LIMIT_MULTIPLE: 0.95
+      XCODE_VERSION: latest-stable
+    strategy:
+      fail-fast: false
+      matrix:
+        dep-resolution: ['spm', 'cocoapods']
+    steps:
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22
+
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
+        with:
+          xcode-version: ${{ env.XCODE_VERSION }}
+
+      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
+        with:
+          fetch-depth: 50
+
+      - name: Yarn Cache Restore
+        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        id: yarn-cache
+        continue-on-error: true
+        with:
+          path: .yarn/cache
+          key: ${{ runner.os }}-ios-yarn-v1-${{ hashFiles('yarn.lock') }}
+          restore-keys: ${{ runner.os }}-ios-yarn-v1
+
+      - uses: hendrikmuhs/ccache-action@d62db5f07c26379fc4b4e0916f098a92573c3b03 # v1.2.23
+        name: Xcode Compile Cache
+        with:
+          key: ${{ runner.os }}-archive-${{ matrix.dep-resolution }}-ios-v1
+          save: "${{ github.ref == 'refs/heads/main' }}"
+          create-symlink: true
+          max-size: 1500M
+
+      - name: Yarn Install
+        uses: nick-fields/retry@ad984534de44a9489a53aefd81eb77f87c70dc60 # v4.0.0
+        with:
+          timeout_minutes: 15
+          retry_wait_seconds: 60
+          max_attempts: 3
+          command: yarn
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@89f90524b88a01fe6e0b732220432cc6142926af # v1.313.0
+        with:
+          ruby-version: 3
+
+      - name: Update Ruby build tools
+        uses: nick-fields/retry@ad984534de44a9489a53aefd81eb77f87c70dc60 # v4.0.0
+        with:
+          timeout_minutes: 2
+          retry_wait_seconds: 60
+          max_attempts: 3
+          command: gem update cocoapods xcodeproj
+
+      - name: Pods Cache Restore
+        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        id: pods-cache
+        continue-on-error: true
+        with:
+          path: tests/ios/Pods
+          key: ${{ runner.os }}-${{ matrix.dep-resolution }}-ios-pods-v3-${{ hashFiles('tests/ios/Podfile.lock') }}
+          restore-keys: ${{ runner.os }}-${{ matrix.dep-resolution }}-ios-pods-v3
+
+      - name: Configure Dependency Resolution Mode
+        run: .github/workflows/scripts/configure-ios-dep-resolution.sh "${{ matrix.dep-resolution }}"
+
+      - name: Pod Install
+        uses: nick-fields/retry@ad984534de44a9489a53aefd81eb77f87c70dc60 # v4.0.0
+        with:
+          timeout_minutes: 20
+          retry_wait_seconds: 30
+          max_attempts: 3
+          command: yarn tests:ios:pod:install
+
+      - name: Install brew utilities
+        uses: nick-fields/retry@ad984534de44a9489a53aefd81eb77f87c70dc60 # v4.0.0
+        with:
+          timeout_minutes: 5
+          retry_wait_seconds: 60
+          max_attempts: 3
+          command: bash .github/workflows/scripts/install-homebrew-rnfb.sh xcbeautify
+
+      - name: Archive Release build for a real device (unsigned) and verify embedded frameworks
+        working-directory: tests/ios
+        run: |
+          ccache -s
+          chmod +x ../../.github/workflows/scripts/verify-ios-release-archive.sh
+          ../../.github/workflows/scripts/verify-ios-release-archive.sh
+          ccache -s
+        shell: bash
+
+      - name: Upload archive (on failure, for triage)
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        continue-on-error: true
+        if: failure()
+        with:
+          name: ios-release-archive-${{ matrix.dep-resolution }}
+          path: tests/ios/build/testing.xcarchive/Products/Applications/*/Info.plist
+          if-no-files-found: ignore
+
+      - name: Yarn Cache Save
+        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        if: "${{ github.ref == 'refs/heads/main' }}"
+        continue-on-error: true
+        with:
+          path: .yarn/cache
+          key: ${{ steps.yarn-cache.outputs.cache-primary-key }}
+
+      - name: Pods Cache Save
+        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        if: "${{ github.ref == 'refs/heads/main' }}"
+        continue-on-error: true
+        with:
+          path: tests/ios/Pods
+          key: ${{ steps.pods-cache.outputs.cache-primary-key }}

.github/workflows/tests_e2e_other.yml

@@ -201,6 +201,9 @@ jobs:
           max_attempts: 3
           command: gem update cocoapods xcodeproj
 
+      - name: Verify Firebase SPM Xcodeproj/CocoaPods API shape
+        run: ruby packages/app/__tests__/firebase_spm_shape_test.rb
+
       - name: Pods Cache Restore
         # https://github.com/actions/cache/releases
         uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5