fix(iOS): stage Hermes headers in prebuild compose job so ReactNativeHeaders resolves <hermes/...> (#57661)

Summary:
The iOS prebuild workflow (`.github/workflows/prebuild-ios-core.yml`) splits into two jobs on separate runners:

- **`build-rn-slice`** stages the hermes-ios headers during setup (`.build/artifacts/hermes/destroot/include/hermes`), but uploads only `.build/headers` + the SPM Products — **not** the hermes artifact.
- **`compose-xcframework`** (fresh runner) runs the compose (`-c` → `buildXCFrameworks`), which computed the hermes include path from `.build/artifacts/hermes/destroot/include`. That directory never exists on the compose runner, so `hermesHeaders` resolved to `null` and the hermes-header fold in `headers-compose.js` was **silently skipped**.

Net effect: the published `ReactNativeHeaders.xcframework` shipped without the `hermes/` namespace, so consumers (e.g. Expo prebuilt) couldn't resolve `<hermes/...>`. Because the value was `null` rather than a bad path, not even the existing warning fired — every nightly regressed silently.

## Fix

Build-time staging, matching the artifact's self-contained design (the orphaned consumer-side sidecar + health check in `download-spm-artifacts.js` confirm the bake was intended to happen at compose time):

- **Workflow:** `compose-xcframework` now re-stages the hermes-ios headers before composing — a `Set Hermes version` step (`$GITHUB_ENV` doesn't cross jobs) and a `Stage Hermes headers` step that extracts the tarball into `.build/artifacts/hermes`. Both are guarded by the same `cache-hit` condition as the sibling steps.
- **Fail-closed guard:** the inline hermes resolution is extracted into an exported `resolveHermesHeaders(buildFolder, required)` with a `findFirst` fallback (mirroring the consumer-side stager). When a version-stamped CI cut can't find the headers it now **throws** instead of silently shipping without `hermes/`. Gated behind a new `--require-hermes` flag, which the workflow passes only when `version-type` is set — so local `-c` keeps the previous no-fold behavior.

## Changelog:

[IOS] [FIXED] - Prebuilt `ReactNativeHeaders.xcframework` now ships the Hermes public headers so consumers resolve `<hermes/...>` out of the box

Pull Request resolved: https://github.com/react/react-native/pull/57661

Test Plan:
- New unit tests for `resolveHermesHeaders` (`__tests__/xcframework-test.js`): resolves at the standard path, resolves via the `findFirst` fallback, returns `null` when absent + not required, throws when absent + required.
- `yarn jest packages/react-native/scripts/ios-prebuild/__tests__/xcframework-test.js --no-cache -i` → 4/4 pass (red before the resolver was exported).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed By: javache

Differential Revision: D113554720

Pulled By: cipolleschi

fbshipit-source-id: 30d21240ae97978e58a95ffdfad4088ed85536d4
This commit is contained in:
Christian Falch authored and meta-codesync[bot] committed 2026-07-27 06:30:32 -07:00
1 parent 20d04aefa1
commit 43b44ed7c3
6 files changed
+162 -16

No files matched your search

+23 -2
View File
@@ -175,6 +175,27 @@ jobs:
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
- name: Set Hermes version
if: steps.restore-ios-xcframework.outputs.cache-hit != 'true'
shell: bash
run: |
# Non-stable RN builds resolve Hermes from npm's latest-v1 dist-tag.
# TODO: rename 'latest-v1' to 'latest' once V1 is the only Hermes on npm.
# Stable builds use the version pinned in version.properties.
if [ "${{ inputs.use-hermes-prebuilt }}" == "true" ]; then
HERMES_VERSION="latest-v1"
else
HERMES_VERSION=$(sed -n 's/^HERMES_VERSION_NAME=//p' packages/react-native/sdks/hermes-engine/version.properties)
fi
echo "Using Hermes version: $HERMES_VERSION"
echo "HERMES_VERSION=$HERMES_VERSION" >> $GITHUB_ENV
- name: Stage Hermes headers
if: steps.restore-ios-xcframework.outputs.cache-hit != 'true'
working-directory: packages/react-native
env:
FLAVOR: ${{ matrix.flavor }}
run: |
node -e "require('./scripts/ios-prebuild/hermes').prepareHermesArtifactsAsync(require('./package.json').version, process.env.FLAVOR).then(()=>process.exit(0)).catch(e=>{console.error(e);process.exit(1)})"
- name: Setup Keychain
if: ${{ steps.restore-ios-xcframework.outputs.cache-hit != 'true' && env.REACT_ORG_CODE_SIGNING_P12_CERT != '' }}
uses: apple-actions/import-codesign-certs@v3 # https://github.com/marketplace/actions/import-code-signing-certificates
@@ -185,12 +206,12 @@ jobs:
if: ${{ steps.restore-ios-xcframework.outputs.cache-hit != 'true' && env.REACT_ORG_CODE_SIGNING_P12_CERT == '' }}
run: |
cd packages/react-native
node scripts/ios-prebuild -c -f "${{ matrix.flavor }}"
node scripts/ios-prebuild -c -f "${{ matrix.flavor }}" ${{ inputs.version-type != '' && '--require-hermes' || '' }}
- name: Create and Sign XCFramework
if: ${{ steps.restore-ios-xcframework.outputs.cache-hit != 'true' && env.REACT_ORG_CODE_SIGNING_P12_CERT != '' }}
run: |
cd packages/react-native
node scripts/ios-prebuild -c -f "${{ matrix.flavor }}" -i "React Org"
node scripts/ios-prebuild -c -f "${{ matrix.flavor }}" -i "React Org" ${{ inputs.version-type != '' && '--require-hermes' || '' }}
- name: Verify composed headers
if: steps.restore-ios-xcframework.outputs.cache-hit != 'true'
run: |
+1
View File
@@ -77,6 +77,7 @@ async function main() {
frameworkPaths,
buildType,
cli.identity,
cli.requireHermes,
);
}
@@ -0,0 +1,70 @@
/**
* 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 {resolveHermesHeaders} = require('../xcframework');
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
describe('resolveHermesHeaders', () => {
let tmp /*: string */ = '';
let buildFolder /*: string */ = '';
beforeEach(() => {
tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'xcframework-test-'));
buildFolder = path.join(tmp, '.build');
});
afterEach(() => {
fs.rmSync(tmp, {recursive: true, force: true});
});
test('returns the base include directory when hermes/hermes.h exists', () => {
const includeDir = path.join(
buildFolder,
'artifacts',
'hermes',
'destroot',
'include',
);
fs.mkdirSync(path.join(includeDir, 'hermes'), {recursive: true});
fs.writeFileSync(path.join(includeDir, 'hermes', 'hermes.h'), '');
expect(resolveHermesHeaders(buildFolder, true)).toBe(includeDir);
});
test('finds a non-standard nested include directory', () => {
const includeDir = path.join(
buildFolder,
'artifacts',
'hermes',
'nested',
'archive',
'destroot',
'include',
);
fs.mkdirSync(path.join(includeDir, 'hermes'), {recursive: true});
fs.writeFileSync(path.join(includeDir, 'hermes', 'hermes.h'), '');
expect(resolveHermesHeaders(buildFolder, true)).toBe(includeDir);
});
test('returns null when Hermes headers are absent and not required', () => {
expect(resolveHermesHeaders(buildFolder, false)).toBeNull();
});
test('throws when Hermes headers are absent and required', () => {
expect(() => resolveHermesHeaders(buildFolder, true)).toThrow(
/ReactNativeHeaders[\s\S]*<hermes\/\.\.\.>[\s\S]*destroot\/include/,
);
});
});
+7
View File
@@ -66,6 +66,11 @@ const cli = yargs
describe:
'Specify the code signing identity to use for signing the frameworks.',
})
.option('require-hermes', {
type: 'boolean',
describe:
'Require Hermes headers when composing the ReactNativeHeaders XCFramework.',
})
.help();
/**
@@ -80,6 +85,7 @@ async function getCLIConfiguration() /*: Promise<?{|
flavor: BuildFlavor,
destinations: ReadonlyArray<Destination>,
identity: ?string,
requireHermes: boolean,
|}> */ {
// Run input parsing
const argv = await cli.argv;
@@ -124,6 +130,7 @@ async function getCLIConfiguration() /*: Promise<?{|
flavor: flavor,
destinations: resolvedPlatforms,
identity: argv.identity,
requireHermes: argv.requireHermes ?? false,
};
}
+27
View File
@@ -12,6 +12,7 @@
const {execSync} = require('node:child_process');
const fs = require('node:fs');
const path = require('node:path');
/**
* Creates a folder if it does not exist
@@ -28,6 +29,31 @@ function createFolderIfNotExists(folderPath /*:string*/) /*: string */ {
return folderPath;
}
function findFirst(
dir /*: string */,
predicate /*: (name: string) => boolean */,
depth /*: number */,
) /*: string | null */ {
if (depth <= 0 || !fs.existsSync(dir)) {
return null;
}
for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
// $FlowFixMe[incompatible-type] Dirent.name is string|Buffer in Flow but always string here
const full /*: string */ = path.join(dir, entry.name);
// $FlowFixMe[incompatible-type] Dirent.name is string|Buffer in Flow but always string here
if (predicate(entry.name)) {
return full;
}
if (entry.isDirectory()) {
const hit = findFirst(full, predicate, depth - 1);
if (hit != null) {
return hit;
}
}
}
return null;
}
function throwIfOnEden() {
try {
execSync('eden info', {stdio: 'ignore'});
@@ -104,6 +130,7 @@ async function computeNightlyTarballURL(
module.exports = {
createFolderIfNotExists,
findFirst,
throwIfOnEden,
createLogger,
computeNightlyTarballURL,
+34 -14
View File
@@ -19,16 +19,45 @@ const fs = require('node:fs');
const path = require('node:path');
const {execSync, execFileSync} = childProcess;
const {createLogger} = utils;
const {createLogger, findFirst} = utils;
const frameworkLog = createLogger('XCFramework');
function resolveHermesHeaders(
buildFolder /*: string */,
required /*: boolean */,
) /*: ?string */ {
const hermesArtifacts = path.join(buildFolder, 'artifacts', 'hermes');
const baseInclude = path.join(hermesArtifacts, 'destroot', 'include');
if (fs.existsSync(path.join(baseInclude, 'hermes', 'hermes.h'))) {
return baseInclude;
}
const includeDir = findFirst(hermesArtifacts, name => name === 'include', 8);
if (
includeDir != null &&
fs.existsSync(path.join(includeDir, 'hermes', 'hermes.h'))
) {
return includeDir;
}
if (required) {
throw new Error(
'Cannot compose ReactNativeHeaders: <hermes/...> will not resolve because ' +
"hermes/hermes.h is missing. Stage the hermes-ios tarball's " +
'destroot/include into .build/artifacts/hermes before composing.',
);
}
return null;
}
function buildXCFrameworks(
rootFolder /*: string */,
buildFolder /*: string */,
frameworkFolders /*: Array<string> */,
buildType /*: BuildFlavor */,
identity /*: ?string */,
requireHermes /*: boolean */ = false,
) {
// Let's run codegen for FBReactNativeSpec otherwise some headers will be missing
generateFBReactNativeSpecIOS('.');
@@ -103,19 +132,9 @@ function buildXCFrameworks(
// ReactNativeHeaders so consumers resolve `<hermes/hermes.h>` out of the box
// (same fold ensureHeadersLayout does consumer-side). The hermes-ios tarball
// is staged at .build/artifacts/hermes/destroot/include by the hermes prebuild
// step; pass it when its `hermes/` namespace is present, else null (then
// `<hermes/...>` stays consumer-composed, as before).
const hermesInclude = path.resolve(
process.cwd(),
'.build',
'artifacts',
'hermes',
'destroot',
'include',
);
const hermesHeaders = fs.existsSync(path.join(hermesInclude, 'hermes'))
? hermesInclude
: null;
// step; pass it when its `hermes/` namespace is present, else null for local
// development. CI release composition requires it and fails closed.
const hermesHeaders = resolveHermesHeaders(buildFolder, requireHermes);
const headersXcfw = buildReactNativeHeadersXcframework(
path.dirname(outputPath),
plan,
@@ -271,4 +290,5 @@ function signXCFramework(
module.exports = {
buildXCFrameworks,
resolveHermesHeaders,
};