fix(app, ios): clarify SPM static linkage error when use_frameworks is absent

Author: Mastersam07

docs/ios-spm.mdx

@@ -34,6 +34,8 @@ use_frameworks! :linkage => :dynamic
 ```
 
 Do not use RNFB's SPM mode with `use_frameworks! :linkage => :static`.
+A Podfile with no `use_frameworks!` line (or `use_frameworks! false`) is static
+linkage too — that is the stock React Native / bare Expo default.
 firebase-ios-sdk SPM products are automatic libraries (plain `.library(...)`,
 not `type: .dynamic`), so each pod that depends on them embeds its own copy.
 With static pod linkage those copies collide at link time as duplicate-symbol
@@ -200,7 +202,16 @@ time with duplicate symbols (and `pod install` rejects the combination).
   Remove `$RNFirebaseDisableSPM = true` and Expo `ios.disableSPM`. Use
   `use_frameworks! :linkage => :dynamic` and React Native 0.75+.
 - **`pod install` fails with "SPM + static linkage is not supported":** Use
-  dynamic linkage (`use_frameworks! :linkage => :dynamic`).
+  dynamic linkage (`use_frameworks! :linkage => :dynamic`). A Podfile with no
+  `use_frameworks!` line (or `use_frameworks! false`), the stock React Native /
+  Expo default, is static linkage too.
+  - With the stock template Podfile, `USE_FRAMEWORKS=dynamic pod install` also
+    works, but it must be set for every `pod install` (including CI); the
+    Podfile line is the durable fix.
+  - Expo: set `ios.useFrameworks` to `"dynamic"` in the `expo-build-properties`
+    plugin (see [Expo projects](#expo-projects)), then re-run
+    `npx expo prebuild`. Only if you maintain `ios/` by hand (no prebuild), set
+    `"ios.useFrameworks": "dynamic"` in `ios/Podfile.properties.json` instead.
 - **`FirebaseApp.app()` is `nil` / Auth looks signed-out inside another native
   pod, or runtime logs duplicate `FIRApp` classes:** SPM mode cannot share one
   `FirebaseCore` across dynamic pod frameworks. See

packages/app/__tests__/firebase_spm_shape_test.rb

@@ -137,6 +137,48 @@ def test_build_type_static_matches_real_linkage_semantics
       assert Pod::BuildType.static_library.static?
     end
 
+    # Real Pod::Podfile target definitions (no install context needed) for
+    # every Podfile linkage form rnfirebase_fail_if_spm_static_linkage!
+    # distinguishes: `build_type.static?` selects the failing targets and
+    # `uses_frameworks?` splits "no use_frameworks!" (static libraries) from
+    # `use_frameworks! :linkage => :static`. MockTargetDefinition in
+    # firebase_spm_test.rb assumes exactly these pairs.
+    def test_target_definition_static_and_uses_frameworks_match_podfile_linkage
+      podfile = Pod::Podfile.new do
+        # No block: a target with no `use_frameworks!` line at all.
+        target 'NoFrameworks'
+        target 'FrameworksFalse' do
+          use_frameworks! false
+        end
+        target 'StaticFrameworks' do
+          use_frameworks! linkage: :static
+          target 'StaticChild' do
+            inherit! :complete
+          end
+        end
+        target 'DynamicFrameworks' do
+          use_frameworks! linkage: :dynamic
+        end
+      end
+
+      expected = {
+        'NoFrameworks' => [true, false],
+        'FrameworksFalse' => [true, false],
+        'StaticFrameworks' => [true, true],
+        'DynamicFrameworks' => [false, true],
+        'StaticChild' => [true, true]
+      }
+      expected.each do |name, pair|
+        definition = podfile.target_definitions.fetch(name)
+        assert_equal pair, [definition.build_type.static?, definition.uses_frameworks?],
+                     "Pod::Podfile target `#{name}` no longer reports " \
+                     "[build_type.static?, uses_frameworks?] == #{pair.inspect} -- " \
+                     'rnfirebase_fail_if_spm_static_linkage! (and MockTargetDefinition) ' \
+                     'rely on this pair to select and label static-linkage targets.'
+      end
+      assert_equal 'StaticFrameworks', podfile.target_definitions.fetch('StaticChild').parent.name
+    end
+
     def test_pod_target_exposes_name_and_build_type
       assert Pod::PodTarget.method_defined?(:name)
       build_type_defined = Pod::PodTarget.method_defined?(:build_type) ||

packages/app/__tests__/firebase_spm_test.rb

@@ -253,11 +253,19 @@ def ==(other)
   end
 end
 
+# `uses_frameworks: false` models a Podfile with no `use_frameworks!` at all:
+# real CocoaPods then reports a `static_library` build type, which is also
+# `static?`, so the check must name that case distinctly in its message.
 class MockTargetDefinition
   attr_reader :build_type
 
-  def initialize(static: false)
-    @build_type = MockBuildType.new(static: static)
+  def initialize(static: false, uses_frameworks: true)
+    @uses_frameworks = uses_frameworks
+    @build_type = uses_frameworks ? MockBuildType.new(static: static) : MockBuildType.static_library
+  end
+
+  def uses_frameworks?
+    @uses_frameworks
   end
 end
 
@@ -272,10 +280,10 @@ def initialize(static: false)
 class MockAggregateTarget
   attr_reader :user_project, :name, :target_definition
 
-  def initialize(user_project, name: 'Pods-testing', static_linkage: false)
+  def initialize(user_project, name: 'Pods-testing', static_linkage: false, uses_frameworks: true)
     @user_project = user_project
     @name = name
-    @target_definition = MockTargetDefinition.new(static: static_linkage)
+    @target_definition = MockTargetDefinition.new(static: static_linkage, uses_frameworks: uses_frameworks)
   end
 end
 
@@ -2239,9 +2247,73 @@ def test_fail_fast_raises_pod_informative_when_spm_active_and_a_target_is_static
       rnfirebase_fail_if_spm_static_linkage!(installer)
     end
     assert_includes error.message, 'SPM + static linkage is not supported'
-    assert_includes error.message, 'Pods-testing'
-    assert_includes error.message, 'use_frameworks! :linkage => :dynamic'
-    refute_includes error.message, '$RNFirebaseDisableSPM = true'
+    assert_includes error.message, '- `use_frameworks! :linkage => :static` ' \
+                                   '(incl. `USE_FRAMEWORKS=static` / Expo `useFrameworks: "static"`): Pods-testing'
+    refute_includes error.message, 'no `use_frameworks!`'
+    assert_static_linkage_fix_wording(error.message)
+  end
+
+  # Remediation wording shared by every static-linkage failure: dynamic
+  # linkage only (Podfile line, `USE_FRAMEWORKS=dynamic` env with its
+  # every-install caveat, Expo plugin config + prebuild with the generated
+  # Podfile.properties.json only for hand-maintained ios/). The SPM opt-out
+  # must not be offered here.
+  def assert_static_linkage_fix_wording(message)
+    assert_includes message, "Fix your Podfile to use dynamic linkage, then run `pod install` again:\n\n  " \
+                             "use_frameworks! :linkage => :dynamic\n"
+    assert_includes message, 'With the stock template Podfile you can instead run ' \
+                             '`USE_FRAMEWORKS=dynamic pod install`, but it must be set for every `pod install` ' \
+                             '(including CI) or linkage reverts to static; the Podfile line above is the durable fix.'
+    assert_includes message, 'Expo: set `ios.useFrameworks` to `"dynamic"` in the `expo-build-properties` ' \
+                             'plugin config, then re-run `npx expo prebuild`'
+    assert_includes message, 'Only if you maintain `ios/` by hand (no prebuild), ' \
+                             'set `"ios.useFrameworks": "dynamic"` in `ios/Podfile.properties.json`'
+    assert_includes message, 'See https://rnfirebase.io/ios-spm'
+    refute_includes message, 'RNFirebaseDisableSPM'
+    refute_includes message, 'disableSPM'
+    refute_includes message, 'Opt out of SPM'
+  end
+
+  def test_fail_fast_names_missing_use_frameworks_as_static_libraries
+    load_firebase_spm
+    RNFirebaseSPM.activate!('12.10.0')
+
+    # Stock React Native / bare Expo Podfile: no `use_frameworks!` line, so
+    # CocoaPods builds every pod as a static library. That is static linkage
+    # too, but the message must not only point at a `use_frameworks!` line
+    # the user doesn't have.
+    installer = MockInstaller.new([
+                                    MockAggregateTarget.new(nil, name: 'Pods-testing', uses_frameworks: false)
+                                  ])
+
+    error = assert_raises(Pod::Informative) do
+      rnfirebase_fail_if_spm_static_linkage!(installer)
+    end
+    assert_includes error.message,
+                    '- no `use_frameworks!` (or `use_frameworks! false`) -- ' \
+                    'pods build as static libraries: Pods-testing'
+    refute_includes error.message, '- `use_frameworks! :linkage => :static`'
+    assert_static_linkage_fix_wording(error.message)
+  end
+
+  def test_fail_fast_groups_static_library_and_static_framework_targets
+    load_firebase_spm
+    RNFirebaseSPM.activate!('12.10.0')
+
+    installer = MockInstaller.new([
+                                    MockAggregateTarget.new(nil, name: 'Pods-app', uses_frameworks: false),
+                                    MockAggregateTarget.new(nil, name: 'Pods-ext', static_linkage: true)
+                                  ])
+
+    error = assert_raises(Pod::Informative) do
+      rnfirebase_fail_if_spm_static_linkage!(installer)
+    end
+    expected = <<~DETECTED
+      Detected static pod linkage:
+        - no `use_frameworks!` (or `use_frameworks! false`) -- pods build as static libraries: Pods-app
+        - `use_frameworks! :linkage => :static` (incl. `USE_FRAMEWORKS=static` / Expo `useFrameworks: "static"`): Pods-ext
+    DETECTED
+    assert_includes error.message, expected
   end
 
   def test_fail_fast_ignores_aggregate_targets_own_always_static_build_type

packages/app/firebase_spm.rb

@@ -577,8 +577,7 @@ def rnfirebase_verify_spm_embed_phase_applied!(installer)
 # (`duplicate symbol`). Under dynamic pod linkage the app builds, but each
 # dynamic framework still keeps a private copy (runtime class duplication /
 # split FirebaseApp registries). There is no supported combination of RNFB's
-# SPM mode with static linkage; the fix is always to switch to dynamic
-# linkage or opt out of SPM entirely.
+# SPM mode with static linkage; the fix is to switch to dynamic linkage.
 #
 # Raises `Pod::Informative` -- CocoaPods' own user-facing error class, which
 # `pod install` prints as a plain, readable message with no Ruby backtrace --
@@ -604,18 +603,40 @@ def rnfirebase_fail_if_spm_static_linkage!(installer)
   end
   return if static_targets.empty?
 
-  target_names = static_targets.map(&:name).join(', ')
+  # `build_type.static?` is true for two different Podfiles: no
+  # `use_frameworks!` at all (CocoaPods' default static libraries -- the stock
+  # React Native / bare Expo Podfile) and `use_frameworks! :linkage => :static`.
+  # Name the one the user actually has so they can find it in their Podfile.
+  library_targets, framework_targets = static_targets.partition do |target|
+    !target.target_definition.uses_frameworks?
+  end
+  detected = []
+  unless library_targets.empty?
+    library_label = 'no `use_frameworks!` (or `use_frameworks! false`) -- pods build as static libraries'
+    detected << "  - #{library_label}: #{library_targets.map(&:name).join(', ')}"
+  end
+  unless framework_targets.empty?
+    framework_label = '`use_frameworks! :linkage => :static` ' \
+                      '(incl. `USE_FRAMEWORKS=static` / Expo `useFrameworks: "static"`)'
+    detected << "  - #{framework_label}: #{framework_targets.map(&:name).join(', ')}"
+  end
 
   raise Pod::Informative, <<~MESSAGE
-    [react-native-firebase] SPM + static linkage is not supported (target(s): #{target_names}).
+    [react-native-firebase] SPM + static linkage is not supported.
 
-    firebase-ios-sdk's Swift Package products are automatic libraries (not `type: .dynamic`), so each react-native-firebase pod that resolves Firebase via SPM embeds its own copy. With `use_frameworks! :linkage => :static` those copies collide at link time as duplicate-symbol errors.
+    Detected static pod linkage:
+    #{detected.join("\n")}
+
+    firebase-ios-sdk's Swift Package products are automatic libraries (not `type: .dynamic`), so each react-native-firebase pod that resolves Firebase via SPM embeds its own copy. With static pod linkage those copies collide at link time as duplicate-symbol errors.
 
     Fix your Podfile to use dynamic linkage, then run `pod install` again:
 
       use_frameworks! :linkage => :dynamic
 
-    CocoaPods Firebase is no longer available with Firebase Apple SDK 13+. See https://rnfirebase.io/ios-spm
+    With the stock template Podfile you can instead run `USE_FRAMEWORKS=dynamic pod install`, but it must be set for every `pod install` (including CI) or linkage reverts to static; the Podfile line above is the durable fix.
+    Expo: set `ios.useFrameworks` to `"dynamic"` in the `expo-build-properties` plugin config, then re-run `npx expo prebuild`. Only if you maintain `ios/` by hand (no prebuild), set `"ios.useFrameworks": "dynamic"` in `ios/Podfile.properties.json`.
+
+    See https://rnfirebase.io/ios-spm
   MESSAGE
 end