feat(iOS): ReactNativeDependenciesHeaders sidecar + pure-RN ReactNativeHeaders, published to Maven

.github/actions/build-npm-package/action.yml

@@ -31,6 +31,15 @@ runs:
         pattern: ReactCore*
         path: ./packages/react-native/ReactAndroid/external-artifacts/artifacts
         merge-multiple: true
+    # ReactNativeDependenciesHeaders* is already covered by the
+    # ReactNativeDependencies* pattern above; ReactNativeHeaders* needs its own.
+    - name: Download ReactNativeHeaders artifacts
+      if: ${{ inputs.skip-apple-prebuilts != 'true' }}
+      uses: actions/download-artifact@v7
+      with:
+        pattern: ReactNativeHeaders*
+        path: ./packages/react-native/ReactAndroid/external-artifacts/artifacts
+        merge-multiple: true
     - name: Print Artifacts Directory
       if: ${{ inputs.skip-apple-prebuilts != 'true' }}
       shell: bash

.github/actions/test-ios-rntester/action.yml

@@ -15,9 +15,18 @@ inputs:
     required: false
     default: false
   use-frameworks:
-    description: Whether we have to build with Dynamic Frameworks. If this is set to true, it builds from source
+    description: Whether we have to build with Dynamic Frameworks.
     required: false
     default: false
+  use-prebuilds:
+    description: >-
+      Whether to consume the prebuilt ReactCore/ReactNativeDependencies
+      artifacts. 'auto' (default) keeps the historical coupling: prebuilds for
+      static, source for dynamic frameworks. Pass 'true' with
+      use-frameworks:true for the prebuilt + dynamic-frameworks lane (the
+      config of the 2026-07-03 SocketRocket dual-copy regression).
+    required: false
+    default: auto
 
 runs:
   using: composite
@@ -41,33 +50,47 @@ runs:
     - name: Prepare IOS Tests
       if: ${{ inputs.run-unit-tests == 'true' }}
       uses: ./.github/actions/prepare-ios-tests
+    - name: Resolve prebuilds mode
+      id: prebuilds
+      shell: bash
+      run: |
+        if [[ "${{ inputs.use-prebuilds }}" == "auto" ]]; then
+          # Historical coupling: prebuilds for static, source for dynamic frameworks.
+          if [[ "${{ inputs.use-frameworks }}" == "true" ]]; then
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          fi
+        else
+          echo "enabled=${{ inputs.use-prebuilds }}" >> "$GITHUB_OUTPUT"
+        fi
     - name: Download ReactNativeDependencies
-      if: ${{ inputs.use-frameworks == 'false' }}
+      if: ${{ steps.prebuilds.outputs.enabled == 'true' }}
       uses: actions/download-artifact@v7
       with:
         name: ReactNativeDependencies${{ inputs.flavor }}.xcframework.tar.gz
         path: /tmp/third-party/
     - name: Print third-party folder
-      if: ${{ inputs.use-frameworks == 'false' }}
+      if: ${{ steps.prebuilds.outputs.enabled == 'true' }}
       shell: bash
       run: ls -lR /tmp/third-party
     - name: Download React Native Prebuilds
-      if: ${{ inputs.use-frameworks == 'false' }}
+      if: ${{ steps.prebuilds.outputs.enabled == 'true' }}
       uses: actions/download-artifact@v7
       with:
         name: ReactCore${{ inputs.flavor }}.xcframework.tar.gz
         path: /tmp/ReactCore
     - name: Print ReactCore folder
-      if: ${{ inputs.use-frameworks == 'false' }}
+      if: ${{ steps.prebuilds.outputs.enabled == 'true' }}
       shell: bash
       run: ls -lR /tmp/ReactCore
     - name: Install CocoaPods dependencies
       shell: bash
       run: |
         if [[ ${{ inputs.use-frameworks }} == "true" ]]; then
           export USE_FRAMEWORKS=dynamic
-        else
-          # If use-frameworks is false, let's use prebuilds
+        fi
+        if [[ "${{ steps.prebuilds.outputs.enabled }}" == "true" ]]; then
           export RCT_USE_LOCAL_RN_DEP="/tmp/third-party/ReactNativeDependencies${{ inputs.flavor }}.xcframework.tar.gz"
           export RCT_TESTONLY_RNCORE_TARBALL_PATH="/tmp/ReactCore/ReactCore${{ inputs.flavor }}.xcframework.tar.gz"
         fi

.github/workflow-scripts/__tests__/verifyArtifactsAreOnMaven-test.js

@@ -22,24 +22,47 @@ jest.mock('../utils.js', () => ({
 process.exit = mockExit;
 global.fetch = mockFetch;
 
+const BASE_URL =
+  'https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts';
+
+// The verifier HEAD-checks the POM plus every classifier tarball attached to
+// the react-native-artifacts publication (external-artifacts/build.gradle.kts).
+const expectedUrls = version => [
+  `${BASE_URL}/${version}/react-native-artifacts-${version}.pom`,
+  ...[
+    'reactnative-core-debug',
+    'reactnative-core-release',
+    'reactnative-dependencies-debug',
+    'reactnative-dependencies-release',
+    'reactnative-headers-debug',
+    'reactnative-headers-release',
+    'reactnative-dependencies-headers-debug',
+    'reactnative-dependencies-headers-release',
+  ].map(
+    classifier =>
+      `${BASE_URL}/${version}/react-native-artifacts-${version}-${classifier}.tar.gz`,
+  ),
+];
+
 describe('#verifyArtifactsAreOnMaven', () => {
   beforeEach(jest.clearAllMocks);
 
   it('waits for the packages to be published on maven when version has no v', async () => {
     mockSleep.mockReturnValueOnce(Promise.resolve()).mockImplementation(() => {
       throw new Error('Should not be called again!');
     });
+    // First attempt: the POM is not there yet. Second attempt: every URL is.
     mockFetch
       .mockReturnValueOnce(Promise.resolve({status: 404}))
-      .mockReturnValueOnce(Promise.resolve({status: 200}));
+      .mockReturnValue(Promise.resolve({status: 200}));
 
     const version = '0.78.1';
     await verifyArtifactsAreOnMaven(version);
 
     expect(mockSleep).toHaveBeenCalledTimes(1);
-    expect(mockFetch).toHaveBeenCalledWith(
-      'https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/0.78.1/react-native-artifacts-0.78.1.pom',
-    );
+    for (const url of expectedUrls('0.78.1')) {
+      expect(mockFetch).toHaveBeenCalledWith(url, {method: 'HEAD'});
+    }
   });
 
   it('waits for the packages to be published on maven, when version starts with v', async () => {
@@ -48,27 +71,46 @@ describe('#verifyArtifactsAreOnMaven', () => {
     });
     mockFetch
       .mockReturnValueOnce(Promise.resolve({status: 404}))
-      .mockReturnValueOnce(Promise.resolve({status: 200}));
+      .mockReturnValue(Promise.resolve({status: 200}));
 
     const version = 'v0.78.1';
     await verifyArtifactsAreOnMaven(version);
 
     expect(mockSleep).toHaveBeenCalledTimes(1);
-    expect(mockFetch).toHaveBeenCalledWith(
-      'https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/0.78.1/react-native-artifacts-0.78.1.pom',
-    );
+    for (const url of expectedUrls('0.78.1')) {
+      expect(mockFetch).toHaveBeenCalledWith(url, {method: 'HEAD'});
+    }
   });
 
   it('passes immediately if packages are already on Maven', async () => {
-    mockFetch.mockReturnValueOnce(Promise.resolve({status: 200}));
+    mockFetch.mockReturnValue(Promise.resolve({status: 200}));
 
     const version = '0.78.1';
     await verifyArtifactsAreOnMaven(version);
 
     expect(mockSleep).toHaveBeenCalledTimes(0);
-    expect(mockFetch).toHaveBeenCalledWith(
-      'https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/0.78.1/react-native-artifacts-0.78.1.pom',
-    );
+    // All nine URLs (POM + 8 classifier tarballs) are verified in one pass.
+    expect(mockFetch).toHaveBeenCalledTimes(9);
+    for (const url of expectedUrls('0.78.1')) {
+      expect(mockFetch).toHaveBeenCalledWith(url, {method: 'HEAD'});
+    }
+  });
+
+  it('waits when a classifier artifact is missing even though the POM exists', async () => {
+    mockSleep.mockReturnValueOnce(Promise.resolve()).mockImplementation(() => {
+      throw new Error('Should not be called again!');
+    });
+    // First attempt: POM ok, first classifier missing. Second attempt: all ok.
+    mockFetch
+      .mockReturnValueOnce(Promise.resolve({status: 200}))
+      .mockReturnValueOnce(Promise.resolve({status: 404}))
+      .mockReturnValue(Promise.resolve({status: 200}));
+
+    const version = '0.78.1';
+    await verifyArtifactsAreOnMaven(version);
+
+    expect(mockSleep).toHaveBeenCalledTimes(1);
+    expect(mockExit).not.toHaveBeenCalled();
   });
 
   it('tries 90 times and then exits', async () => {
@@ -82,6 +124,7 @@ describe('#verifyArtifactsAreOnMaven', () => {
     expect(mockExit).toHaveBeenCalledWith(1);
     expect(mockFetch).toHaveBeenCalledWith(
       'https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/0.78.1/react-native-artifacts-0.78.1.pom',
+      {method: 'HEAD'},
     );
   });
 });

.github/workflow-scripts/verifyArtifactsAreOnMaven.js

@@ -7,6 +7,7 @@
  * @format
  */
 
+// @flow
 const {log, sleep} = require('./utils');
 
 const SLEEP_S = 60; // 1 minute
@@ -15,23 +16,49 @@ const ARTIFACT_URL =
   'https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/';
 const ARTIFACT_NAME = 'react-native-artifacts-';
 
+// The classifier-suffixed tarballs attached to the react-native-artifacts
+// publication (external-artifacts/build.gradle.kts). The POM check alone
+// would pass even when a classifier artifact never made it to Maven.
+const ARTIFACT_CLASSIFIERS = [
+  'reactnative-core-debug',
+  'reactnative-core-release',
+  'reactnative-dependencies-debug',
+  'reactnative-dependencies-release',
+  'reactnative-headers-debug',
+  'reactnative-headers-release',
+  'reactnative-dependencies-headers-debug',
+  'reactnative-dependencies-headers-release',
+];
+
 async function verifyArtifactsAreOnMaven(version, retries = MAX_RETRIES) {
   if (version.startsWith('v')) {
     version = version.substring(1);
   }
 
-  const artifactUrl = `${ARTIFACT_URL}${version}/${ARTIFACT_NAME}${version}.pom`;
+  const urls = [
+    `${ARTIFACT_URL}${version}/${ARTIFACT_NAME}${version}.pom`,
+    ...ARTIFACT_CLASSIFIERS.map(
+      classifier =>
+        `${ARTIFACT_URL}${version}/${ARTIFACT_NAME}${version}-${classifier}.tar.gz`,
+    ),
+  ];
   for (let currentAttempt = 1; currentAttempt <= retries; currentAttempt++) {
-    const response = await fetch(artifactUrl);
-
-    if (response.status !== 200) {
-      log(
-        `${currentAttempt}) Artifact's for version ${version} are not on maven yet.\nURL: ${artifactUrl}\nLet's wait a minute and try again.\n`,
-      );
-      await sleep(SLEEP_S);
-    } else {
+    let missingUrl = null;
+    for (const url of urls) {
+      const response = await fetch(url, {method: 'HEAD'});
+      if (response.status !== 200) {
+        missingUrl = url;
+        break;
+      }
+    }
+
+    if (missingUrl == null) {
       return;
     }
+    log(
+      `${currentAttempt}) Artifact's for version ${version} are not on maven yet.\nURL: ${missingUrl}\nLet's wait a minute and try again.\n`,
+    );
+    await sleep(SLEEP_S);
   }
 
   log(

.github/workflows/prebuild-ios-core.yml

@@ -167,9 +167,11 @@ jobs:
         if: steps.restore-ios-xcframework.outputs.cache-hit != 'true'
         shell: bash
         run: |
-          # ReactNativeHeaders.xcframework (built by the compose step) folds in
-          # the third-party deps namespaces (folly/glog/boost/...), so the deps
-          # headers must be staged here too — not just in build-slices.
+          # ReactNativeHeaders.xcframework is pure-RN (the deps namespaces ship
+          # in the ReactNativeDependenciesHeaders sidecar built by the deps
+          # prebuild), but the headers-verify compile gates still need the deps
+          # headers on their include path (folly/glog/... reached from RN's
+          # public headers), so the deps artifact is staged here too.
           tar -xzf /tmp/third-party/ReactNativeDependencies${{ matrix.flavor }}.xcframework.tar.gz -C /tmp/third-party/
           mkdir -p packages/react-native/third-party/
           mv /tmp/third-party/packages/react-native/third-party/ReactNativeDependencies.xcframework packages/react-native/third-party/ReactNativeDependencies.xcframework
@@ -212,6 +214,15 @@ jobs:
         run: |
           cd packages/react-native/.build/output/xcframeworks/${{matrix.flavor}}/Symbols
           tar -cz -f ../../ReactCore${{ matrix.flavor }}.framework.dSYM.tar.gz .
+      - name: Rename ReactNativeHeaders XCFramework tarball
+        if: steps.restore-ios-xcframework.outputs.cache-hit != 'true'
+        run: |
+          # The compose step already tars ReactNativeHeaders.xcframework standalone;
+          # published as its own Maven artifact (classifier reactnative-headers-*)
+          # so SwiftPM consumers can wire it as a separate binaryTarget. It also
+          # ships inside the ReactCore tarball for the CocoaPods pod.
+          cp packages/react-native/.build/output/xcframeworks/${{matrix.flavor}}/ReactNativeHeaders.xcframework.tar.gz \
+            packages/react-native/.build/output/xcframeworks/ReactNativeHeaders${{matrix.flavor}}.xcframework.tar.gz
       - name: Upload XCFramework Artifact
         uses: actions/upload-artifact@v6
         with:
@@ -222,11 +233,17 @@ jobs:
         with:
           name: ReactCore${{ matrix.flavor }}.framework.dSYM.tar.gz
           path: packages/react-native/.build/output/xcframeworks/ReactCore${{matrix.flavor}}.framework.dSYM.tar.gz
+      - name: Upload ReactNativeHeaders XCFramework Artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: ReactNativeHeaders${{ matrix.flavor }}.xcframework.tar.gz
+          path: packages/react-native/.build/output/xcframeworks/ReactNativeHeaders${{matrix.flavor}}.xcframework.tar.gz
       - name: Save cache if present
         if: ${{ github.ref == 'refs/heads/main' }} # To avoid that the cache explode
         uses: actions/cache/save@v5
         with:
           path: |
             packages/react-native/.build/output/xcframeworks/ReactCore${{matrix.flavor}}.xcframework.tar.gz
             packages/react-native/.build/output/xcframeworks/ReactCore${{matrix.flavor}}.framework.dSYM.tar.gz
+            packages/react-native/.build/output/xcframeworks/ReactNativeHeaders${{matrix.flavor}}.xcframework.tar.gz
           key: v2-ios-core-xcframework-${{ matrix.flavor }}-${{ hashFiles('packages/react-native/Package.swift', 'packages/react-native/scripts/ios-prebuild/*.js', 'packages/react-native/scripts/ios-prebuild.js', 'packages/react-native/React/**/*', 'packages/react-native/ReactCommon/**/*', 'packages/react-native/Libraries/**/*') }}

.github/workflows/prebuild-ios-dependencies.yml

@@ -130,7 +130,7 @@ jobs:
         with:
           path: |
             packages/react-native/third-party/
-          key: v3-ios-dependencies-xcframework-${{ matrix.flavor }}-${{ hashfiles('scripts/releases/ios-prebuild/configuration.js') }}
+          key: v4-ios-dependencies-xcframework-${{ matrix.flavor }}-${{ hashfiles('scripts/releases/ios-prebuild/configuration.js', 'scripts/releases/ios-prebuild/compose-framework.js') }}
       # If cache hit, we already have our binary. We don't need to do anything.
       - name: Yarn Install
         if: steps.restore-xcframework.outputs.cache-hit != 'true'
@@ -164,7 +164,13 @@ jobs:
         if: steps.restore-xcframework.outputs.cache-hit != 'true'
         run: |
           tar -cz -f packages/react-native/third-party/ReactNativeDependencies${{ matrix.flavor }}.xcframework.tar.gz \
-            packages/react-native/third-party/ReactNativeDependencies.xcframework
+            packages/react-native/third-party/ReactNativeDependencies.xcframework \
+            packages/react-native/third-party/ReactNativeDependenciesHeaders.xcframework
+      - name: Compress Headers Sidecar XCFramework
+        if: steps.restore-xcframework.outputs.cache-hit != 'true'
+        run: |
+          tar -cz -f packages/react-native/third-party/ReactNativeDependenciesHeaders${{ matrix.flavor }}.xcframework.tar.gz \
+            packages/react-native/third-party/ReactNativeDependenciesHeaders.xcframework
       - name: Show Symbol folder content
         if: steps.restore-xcframework.outputs.cache-hit != 'true'
         run: ls -lR packages/react-native/third-party/Symbols
@@ -179,6 +185,11 @@ jobs:
         with:
           name: ReactNativeDependencies${{ matrix.flavor }}.xcframework.tar.gz
           path: packages/react-native/third-party/ReactNativeDependencies${{ matrix.flavor }}.xcframework.tar.gz
+      - name: Upload Headers Sidecar XCFramework Artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: ReactNativeDependenciesHeaders${{ matrix.flavor }}.xcframework.tar.gz
+          path: packages/react-native/third-party/ReactNativeDependenciesHeaders${{ matrix.flavor }}.xcframework.tar.gz
       - name: Upload dSYM Artifact
         uses: actions/upload-artifact@v6
         with:
@@ -191,5 +202,6 @@ jobs:
         with:
           path: |
             packages/react-native/third-party/ReactNativeDependencies${{ matrix.flavor }}.xcframework.tar.gz
+            packages/react-native/third-party/ReactNativeDependenciesHeaders${{ matrix.flavor }}.xcframework.tar.gz
             packages/react-native/third-party/ReactNativeDependencies${{ matrix.flavor }}.framework.dSYM.tar.gz
-          key: v3-ios-dependencies-xcframework-${{ matrix.flavor }}-${{ hashfiles('scripts/releases/ios-prebuild/configuration.js') }}
+          key: v4-ios-dependencies-xcframework-${{ matrix.flavor }}-${{ hashfiles('scripts/releases/ios-prebuild/configuration.js', 'scripts/releases/ios-prebuild/compose-framework.js') }}

.github/workflows/test-all.yml

@@ -155,6 +155,12 @@ jobs:
         uses: ./.github/actions/test-ios-rntester
         with:
           use-frameworks: ${{ matrix.frameworks }}
+          # Consume the prebuilt artifacts in the dynamic-frameworks cells too:
+          # prebuilt + use_frameworks is the config of the 2026-07-03
+          # SocketRocket dual-copy regression, previously covered by no lane
+          # (source-built dynamic frameworks stay covered by
+          # test_ios_rntester_dynamic_frameworks).
+          use-prebuilds: true
           flavor: ${{ matrix.flavor }}
 
   test_e2e_ios_rntester:

packages/react-native/React-Core-prebuilt.podspec

@@ -22,11 +22,15 @@ Pod::Spec.new do |s|
   #  - React.xcframework: the compiled core. Its per-slice React.framework carries
   #    every <React/...> header + the framework module map, so `#import <React/...>`
   #    and `@import React;` resolve through FRAMEWORK_SEARCH_PATHS automatically.
-  #  - ReactNativeHeaders.xcframework: headers-only. Carries every other namespace
-  #    (<react/...>, <yoga/...>, folly, glog, ...). Its headers are flattened into a
-  #    top-level Headers/ (see prepare_command) and exposed via the standard pod
-  #    header search path. (<hermes/...> is supplied by the hermes-engine pod here;
-  #    it is folded into ReactNativeHeaders only on the SwiftPM consumer side.)
+  #  - ReactNativeHeaders.xcframework: headers-only, PURE-RN. Carries every other
+  #    RN namespace (<react/...>, <yoga/...>, ...). Its headers are flattened into
+  #    a top-level Headers/ (see prepare_command) and exposed via the standard pod
+  #    header search path. The third-party deps namespaces (folly/glog/boost/...)
+  #    are NOT here — the ReactNativeDependencies pod serves them from its own
+  #    artifact (see scripts/cocoapods/__docs__/prebuilt-deps.md), wired through
+  #    add_rn_third_party_dependencies below. (<hermes/...> is supplied by the
+  #    hermes-engine pod here; it is folded into ReactNativeHeaders only on the
+  #    SwiftPM consumer side.)
   # There is no clang VFS overlay.
   s.vendored_frameworks    = "React.xcframework"