feat(ios-prebuild): emit ReactNativeDependenciesHeaders.xcframework sidecar

chrfalch · claude · chrfalch · commit 69178459e607 · 2026-07-06T18:36:24.000+02:00
The binary ReactNativeDependencies.xcframework is FRAMEWORK-type: it
cannot carry a HeadersPath key, so its root Headers/ dir is invisible to
SwiftPM binaryTargets (verified empirically 2026-07-04 - xcodebuild
rejects -headers without -library, and SwiftPM hard-rejects HeadersPath
on framework entries). This adds a headers-only LIBRARY-type sidecar,
ReactNativeDependenciesHeaders.xcframework, that SwiftPM auto-serves
with zero flags: stub static archives paired with per-slice Headers/
holding the seven third-party namespaces (folly, glog, boost, fmt,
double-conversion, fast_float, SocketRocket).

- headers-xcframework.js (new): dependency-light shared emitter -
  composeHeadersOnlyXcframework (the stub-archive recipe factored out of
  buildReactNativeHeadersXcframework), stubSlicesFromXcframework (slice
  parity derived from the binary artifact's Info.plist, so the sidecar
  resolves for every platform the binary does), and
  buildDepsHeadersXcframework with a set-equality gate that fails closed
  in both directions (declared-but-missing and undeclared namespaces).
- compose-framework.js: the deps compose emits and signs the sidecar
  right after assembling the root Headers/ (slice-uniform content).
- prebuild-ios-dependencies.yml: the sidecar ships INSIDE the deps
  tarball (self-contained for CocoaPods) and as a standalone tarball;
  cache key bumped and now also hashes compose-framework.js.
- reactNativeDependencies.js: consumers extract the sidecar alongside
  the binary; pre-sidecar tarballs (pinned RN_DEP_VERSION) warn and
  continue - CocoaPods is unaffected, SwiftPM recomposes it locally.

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/prebuild-ios-dependencies.yml b/.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') }}
diff --git a/packages/react-native/scripts/ios-prebuild/__tests__/headers-xcframework-test.js b/packages/react-native/scripts/ios-prebuild/__tests__/headers-xcframework-test.js
@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+'use strict';
+
+const {buildDepsHeadersXcframework} = require('../headers-xcframework');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+describe('buildDepsHeadersXcframework set-equality gate', () => {
+  let tmp /*: string */;
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'deps-headers-test-'));
+  });
+  afterEach(() => {
+    fs.rmSync(tmp, {recursive: true, force: true});
+  });
+
+  const mkHeaders = (namespaces /*: Array<string> */) => {
+    const dir = path.join(tmp, 'Headers');
+    fs.mkdirSync(dir, {recursive: true});
+    for (const ns of namespaces) {
+      fs.mkdirSync(path.join(dir, ns), {recursive: true});
+    }
+    return dir;
+  };
+
+  // Both gates throw BEFORE any staging or xcodebuild invocation, so these
+  // tests run without macOS tooling.
+  test('fails closed when a declared namespace is missing from the artifact', () => {
+    const headers = mkHeaders(['folly']);
+    expect(() =>
+      buildDepsHeadersXcframework(tmp, headers, ['folly', 'glog'], []),
+    ).toThrow(/missing from .*Headers: glog/);
+  });
+
+  test('fails closed when the artifact ships an undeclared namespace', () => {
+    const headers = mkHeaders(['folly', 'brand-new-dep']);
+    expect(() =>
+      buildDepsHeadersXcframework(tmp, headers, ['folly'], []),
+    ).toThrow(/undeclared in DEPS_NAMESPACES.*brand-new-dep/);
+  });
+
+  test('ignores loose files at the Headers root (directories are the namespace set)', () => {
+    const headers = mkHeaders(['folly']);
+    fs.writeFileSync(path.join(headers, 'stray.h'), '');
+    expect(() =>
+      buildDepsHeadersXcframework(tmp, headers, ['folly', 'glog'], []),
+    ).toThrow(/missing from .*Headers: glog/); // throws for glog, not stray.h
+  });
+});
diff --git a/packages/react-native/scripts/ios-prebuild/headers-xcframework.js b/packages/react-native/scripts/ios-prebuild/headers-xcframework.js
@@ -0,0 +1,241 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ * @format
+ */
+
+/**
+ * Headers-only xcframework emitter — the shared recipe behind
+ * ReactNativeHeaders.xcframework (headers-compose.js) and the
+ * ReactNativeDependenciesHeaders.xcframework sidecar (the deps prebuild's
+ * compose-framework.js). A headers-only artifact is a LIBRARY-type
+ * xcframework: stub static archives (nothing embeds in apps) paired with a
+ * staged Headers dir. The per-slice Headers/ layout and the Info.plist
+ * `HeadersPath` key — what makes SwiftPM auto-serve the headers with zero
+ * flags — are produced by `xcodebuild -create-xcframework -library ...
+ * -headers ...` itself and are never hand-written (framework-type entries
+ * hard-reject `HeadersPath`; verified 2026-07-04).
+ *
+ * This module must stay dependency-light (fs/path/child_process only): the
+ * deps prebuild under scripts/releases requires it across the package
+ * boundary.
+ */
+
+const {execSync} = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/*::
+export type StubSlice = {
+  name: string, // human label
+  sdk: string, // xcrun --sdk name
+  targets: Array<string>, // clang -target triples (lipo'd when > 1)
+};
+*/
+
+const DEFAULT_STUB_SLICES /*: Array<StubSlice> */ = [
+  {name: 'ios', sdk: 'iphoneos', targets: ['arm64-apple-ios15.0']},
+  {
+    name: 'ios-simulator',
+    sdk: 'iphonesimulator',
+    targets: [
+      'arm64-apple-ios15.0-simulator',
+      'x86_64-apple-ios15.0-simulator',
+    ],
+  },
+];
+
+// Mac Catalyst slice — used by the real compose (the cached-artifact
+// repackage path skips it to stay fast; React.xcframework carries it).
+const CATALYST_STUB_SLICE /*: StubSlice */ = {
+  name: 'mac-catalyst',
+  sdk: 'macosx',
+  targets: ['arm64-apple-ios15.0-macabi', 'x86_64-apple-ios15.0-macabi'],
+};
+
+// SupportedPlatform(+variant) from an xcframework Info.plist -> stub recipe.
+// The min OS version in the triple only shapes the stub object file; slice
+// identity (what create-xcframework groups by) comes from platform + variant
+// + archs.
+const PLATFORM_STUB_RECIPES /*: {
+  [key: string]: {sdk: string, os: string, suffix: string},
+} */ = {
+  ios: {sdk: 'iphoneos', os: 'ios15.0', suffix: ''},
+  'ios-simulator': {
+    sdk: 'iphonesimulator',
+    os: 'ios15.0',
+    suffix: '-simulator',
+  },
+  'ios-maccatalyst': {sdk: 'macosx', os: 'ios15.0', suffix: '-macabi'},
+  macos: {sdk: 'macosx', os: 'macosx11.0', suffix: ''},
+  tvos: {sdk: 'appletvos', os: 'tvos15.1', suffix: ''},
+  'tvos-simulator': {
+    sdk: 'appletvsimulator',
+    os: 'tvos15.1',
+    suffix: '-simulator',
+  },
+  xros: {sdk: 'xros', os: 'xros1.0', suffix: ''},
+  'xros-simulator': {sdk: 'xrsimulator', os: 'xros1.0', suffix: '-simulator'},
+};
+
+/**
+ * Derives stub slices matching an existing (binary) xcframework's slice set,
+ * so a headers-only sidecar resolves for every platform the binary does.
+ */
+function stubSlicesFromXcframework(
+  xcfwPath /*: string */,
+) /*: Array<StubSlice> */ {
+  const plist = JSON.parse(
+    execSync(
+      `plutil -convert json -o - "${path.join(xcfwPath, 'Info.plist')}"`,
+    ).toString(),
+  );
+  return plist.AvailableLibraries.map(lib => {
+    const key =
+      lib.SupportedPlatformVariant != null
+        ? `${lib.SupportedPlatform}-${lib.SupportedPlatformVariant}`
+        : lib.SupportedPlatform;
+    const recipe = PLATFORM_STUB_RECIPES[key];
+    if (recipe == null) {
+      throw new Error(
+        `headers-xcframework: no stub recipe for slice '${key}' of ` +
+          `${xcfwPath}. Add it to PLATFORM_STUB_RECIPES.`,
+      );
+    }
+    return {
+      name: key,
+      sdk: recipe.sdk,
+      targets: lib.SupportedArchitectures.map(
+        a => `${a}-apple-${recipe.os}${recipe.suffix}`,
+      ),
+    };
+  });
+}
+
+/**
+ * Composes `<name>.xcframework` under `outDir` from an already-populated
+ * Headers stage dir: one stub static archive per slice, then
+ * `xcodebuild -create-xcframework` pairing every archive with the stage.
+ * The caller owns (and cleans) the stage dir.
+ */
+function composeHeadersOnlyXcframework(
+  outDir /*: string */,
+  name /*: string */,
+  stage /*: string */,
+  slices /*: Array<StubSlice> */,
+) /*: string */ {
+  const work = fs.mkdtempSync(path.join(outDir, '.stub-work-'));
+  fs.writeFileSync(
+    path.join(work, 'stub.c'),
+    `// ${name} is headers-only; this stub satisfies xcframework tooling.\n` +
+      `static int ${name}Stub __attribute__((unused)) = 0;\n`,
+  );
+  const libs = slices.map(slice => {
+    const sdkPath = execSync(`xcrun --sdk ${slice.sdk} --show-sdk-path`)
+      .toString()
+      .trim();
+    const thins = slice.targets.map((t, i) => {
+      const obj = path.join(work, `stub-${slice.name}-${i}.o`);
+      execSync(
+        `xcrun clang -c -target ${t} -isysroot "${sdkPath}" "${path.join(work, 'stub.c')}" -o "${obj}"`,
+      );
+      const lib = path.join(work, `stub-${slice.name}-${i}.a`);
+      execSync(`xcrun libtool -static -o "${lib}" "${obj}" 2>/dev/null`);
+      return lib;
+    });
+    const outLib = path.join(work, `lib${name}-${slice.name}.a`);
+    if (thins.length === 1) {
+      fs.copyFileSync(thins[0], outLib);
+    } else {
+      execSync(
+        `xcrun lipo -create ${thins.map(l => `"${l}"`).join(' ')} -output "${outLib}"`,
+      );
+    }
+    return outLib;
+  });
+
+  const outXcfw = path.join(outDir, `${name}.xcframework`);
+  fs.rmSync(outXcfw, {recursive: true, force: true});
+  execSync(
+    `xcodebuild -create-xcframework ` +
+      libs.map(l => `-library "${l}" -headers "${stage}"`).join(' ') +
+      ` -output "${outXcfw}"`,
+    {stdio: 'pipe'},
+  );
+  fs.rmSync(work, {recursive: true, force: true});
+  return outXcfw;
+}
+
+const DEPS_HEADERS_XCFRAMEWORK_NAME = 'ReactNativeDependenciesHeaders';
+
+/**
+ * Builds ReactNativeDependenciesHeaders.xcframework: the headers-only sidecar
+ * serving the third-party deps namespaces (folly/glog/boost/fmt/
+ * double-conversion/fast_float/SocketRocket). The binary
+ * ReactNativeDependencies.xcframework is FRAMEWORK-type, so its root Headers/
+ * dir is invisible to SwiftPM — this LIBRARY-type sidecar is what makes the
+ * deps headers auto-served, keeping ReactNativeHeaders pure-RN.
+ *
+ * Set-equality with `namespaces` (headers-spec.js DEPS_NAMESPACES) is
+ * enforced fail-closed in BOTH directions: a declared namespace missing from
+ * `depsHeaders` would ship a silently-broken sidecar; an undeclared dir means
+ * a new third-party dep was added without a spec decision.
+ */
+function buildDepsHeadersXcframework(
+  outDir /*: string */,
+  depsHeaders /*: string */,
+  namespaces /*: Array<string> */,
+  slices /*: Array<StubSlice> */,
+) /*: string */ {
+  const found = fs
+    .readdirSync(depsHeaders, {withFileTypes: true})
+    .filter(e => e.isDirectory())
+    .map(e => String(e.name));
+  const missing = namespaces.filter(ns => !found.includes(ns));
+  const undeclared = found.filter(d => !namespaces.includes(d));
+  if (missing.length > 0 || undeclared.length > 0) {
+    throw new Error(
+      `headers-xcframework: deps namespaces out of sync with the spec.\n` +
+        (missing.length > 0
+          ? `  missing from ${depsHeaders}: ${missing.join(', ')}\n`
+          : '') +
+        (undeclared.length > 0
+          ? `  undeclared in DEPS_NAMESPACES (headers-spec.js): ${undeclared.join(', ')}\n`
+          : '') +
+        `Declare new deps deliberately — the sidecar and the spec must agree.`,
+    );
+  }
+
+  const stage = fs.mkdtempSync(path.join(outDir, '.deps-headers-stage-'));
+  for (const ns of namespaces) {
+    execSync(
+      `/bin/cp -Rc "${path.join(depsHeaders, ns)}" "${path.join(stage, ns)}"`,
+    );
+  }
+  const outXcfw = composeHeadersOnlyXcframework(
+    outDir,
+    DEPS_HEADERS_XCFRAMEWORK_NAME,
+    stage,
+    slices,
+  );
+  fs.rmSync(stage, {recursive: true, force: true});
+  console.log(
+    `headers-xcframework: ${DEPS_HEADERS_XCFRAMEWORK_NAME}.xcframework ` +
+      `(${slices.map(s => s.name).join(', ')}) -> ${outXcfw} ` +
+      `(namespaces: ${namespaces.join(', ')})`,
+  );
+  return outXcfw;
+}
+
+module.exports = {
+  CATALYST_STUB_SLICE,
+  DEFAULT_STUB_SLICES,
+  DEPS_HEADERS_XCFRAMEWORK_NAME,
+  buildDepsHeadersXcframework,
+  composeHeadersOnlyXcframework,
+  stubSlicesFromXcframework,
+};
diff --git a/packages/react-native/scripts/ios-prebuild/reactNativeDependencies.js b/packages/react-native/scripts/ios-prebuild/reactNativeDependencies.js
@@ -92,6 +92,28 @@ async function prepareReactNativeDependenciesArtifactsAsync(
     stdio: 'inherit',
   });
 
+  // The headers-only ReactNativeDependenciesHeaders.xcframework sidecar ships
+  // alongside the binary in the same tarball — it is what serves the deps
+  // namespaces to SwiftPM (the binary is framework-type; its root Headers/ is
+  // invisible to binaryTargets). Absent only in pre-sidecar tarballs (pinned
+  // RN_DEP_VERSION): CocoaPods still works (the pod flattens the binary's
+  // root Headers/), SwiftPM consumers regain it via ensureHeadersLayout.
+  const headersSidecarSource = path.join(
+    path.dirname(xcframeworkSource),
+    'ReactNativeDependenciesHeaders.xcframework',
+  );
+  if (fs.existsSync(headersSidecarSource)) {
+    execSync(`cp -R "${headersSidecarSource}" "${artifactsPath}"`, {
+      stdio: 'inherit',
+    });
+  } else {
+    dependencyLog(
+      'ReactNativeDependenciesHeaders.xcframework not present in the tarball ' +
+        '(pre-sidecar artifact) — continuing with the binary xcframework only.',
+      'warning',
+    );
+  }
+
   // Delete the tarball after extraction
   if (!process.env.HERMES_ENGINE_TARBALL_PATH) {
     fs.unlinkSync(localPath);
diff --git a/scripts/releases/ios-prebuild/compose-framework.js b/scripts/releases/ios-prebuild/compose-framework.js
