macOS test app is blocked on react-native-macos ≥ 0.82 (Hermes static_h build scripts)

[kraenhansen]

Tracking the Test app (macOS) failure on #372 ("Adopt Hermes' first-party Node-API (static_h)"), and the conditions under which the macOS job can be re-enabled.

Status

The MacOS 💻 label has been removed from #372, so Test app (macOS) no longer runs there. macOS is knowingly deferred — everything else in that PR (iOS, Android, the Node.js tooling) is unaffected.

Why it fails

#372 vendors Hermes from facebook/hermes static_h (pinned SHA) and lets React Native build it from source via REACT_NATIVE_OVERRIDE_HERMES_DIR. On iOS that's RN 0.88.0-nightly, whose Hermes build scripts match. On macOS the app is scaffolded by scripts/init-macos-test-app.ts against react-native-macos@0.81.8 / react-native@0.81.6, and RN 0.81's Hermes build scripts predate the static_h changes we depend on:

1. [RN] [1] Build Hermesc fails immediately. RN 0.81's sdks/hermes-engine/utils/build-hermesc-xcode.sh invokes cmake -S … -B … -DJSI_DIR=… with no -DCMAKE_BUILD_TYPE, and wraps it in env -i, so nothing can be injected from the outside. The pinned Hermes hard-errors in its root CMakeLists.txt:

   CMake Error at CMakeLists.txt:46 (message):
     Please set CMAKE_BUILD_TYPE
   

   Reproduced locally against the pinned SHA with react-native-macos@0.81.8's ReactCommon/jsi: configure fails as above, and succeeds once -DCMAKE_BUILD_TYPE=Release is added. Upstream RN added that flag in 0.82.0.

2. [RN] [2] Build Hermes would fail next. RN 0.81's build-hermes-xcode.sh builds --target libhermes and copies API/hermes/hermes.framework. In the pinned Hermes the target is hermesvm and the bundle is lib/hermesvm.framework (same rename we handled for Android in Adopt Hermes' first-party Node-API (static_h) #372). RN main was updated for this; 0.81 was not.

3. Likely next: JSI header skew. Adopt Hermes' first-party Node-API (static_h) #372 drops the step that copied Hermes' JSI headers into RN's ReactCommon/jsi, on the grounds that the pinned Hermes and RN 0.87+ agree. RN 0.81 does not, so the host module's use of IHermes / getVMRuntimeUnsafe() may not compile even once (1) and (2) are past.

Note: the second failed phase in CI ([CP] Copy XCFrameworks for weak-node-api) is most likely collateral — an earlier run with the same Hermesc error reported that phase as passing. Confirm rather than assume once the build gets further.

What gates re-enabling macOS

react-native-macos must ship a release based on React Native ≥ 0.82 (that release carries both the CMAKE_BUILD_TYPE fix and the hermesvm rename). Today latest is 0.81.9, next is 0.81.0, nightly is 0.78.4 — there is no 0.82+ line at all, so bumping the pin within 0.81.x buys nothing.

When that lands:

1. Bump REACT_NATIVE_MACOS_VERSION / REACT_NATIVE_VERSION in scripts/init-macos-test-app.ts (they are peer-locked; keep them in lockstep).
2. Re-add the MacOS 💻 label to the relevant PR — the job in .github/workflows/check.yml is already label-gated, so no workflow change is needed.
3. Expect to work through (3) above: JSI/IHermes compatibility against the newer react-native-macos.

A local workaround is possible in the meantime (patch react-native-macos's two Hermes scripts from vendor-hermes), but it papers over a gap that keeps widening with every further static_h change, and does nothing about (3). Preferred order is: wait for upstream, then bump.

Related: #372, #391 (captures the raw xcodebuild log so a script phase failure is diagnosable at all).

[kraenhansen]

Extra step once this is unblocked: move macOS onto the prebuilt Hermes archive

Apple platforms no longer build Hermes as part of the app build. A new prebuilt-hermes command builds the pinned commit once into an archive, which scripts/patch-hermes.rb hands to React Native via HERMES_ENGINE_TARBALL_PATH (branch claude/hermes-source-build-cache-zk13mc).

react-native-macos was deliberately left on the old source path, since the archive is only produced and exercised for the iOS platforms today:

if ENV['REACT_NATIVE_NODE_API_HERMES_FROM_SOURCE'].to_s == '1' || react_native_package == "react-native-macos"
  ENV['REACT_NATIVE_OVERRIDE_HERMES_DIR'] = node_api_run_cli("vendor-hermes", react_native_package)
else
  ENV['HERMES_ENGINE_TARBALL_PATH'] = node_api_run_cli("prebuilt-hermes", react_native_package)
end

So the re-enabling checklist in the issue body gains a fourth item — and note that item 3 (JSI header skew) is the same constraint that decides whether this works at all, since the archive is compiled against a specific package's ReactCommon/jsi:

4. Move macOS onto the archive too, once react-native-macos ≥ 0.82 is in place:
   • Drop the react_native_package == "react-native-macos" branch from packages/host/scripts/patch-hermes.rb, and pass --platform macosx for that package instead (prebuilt-hermes already takes it; hermes-prebuilt.ts deliberately keeps macosx out of the universal XCFramework because hermes-engine.podspec vendors macOS as a plain framework).
   • Add the Resolve prebuilt Hermes name / Cache prebuilt Hermes / Build prebuilt Hermes steps to the test-macos job in .github/workflows/check.yml, mirroring test-ios. Without them that job pays a full macOS Hermes build on every run.
   • Check that react-native-macos's vendored hermes-engine.podspec still honours HERMES_ENGINE_TARBALL_PATH and expects the same destroot/ layout. The archive is built for whichever React Native package the app resolves, so a react-native-macos archive gets its own name and never collides with the iOS one — but a podspec that reads the tarball differently would need handling here.
   • Extend .github/workflows/hermes-prebuilt.yml to publish the macOS archive alongside the iOS one, otherwise macOS consumers fall back to building locally.

---

Generated by Claude Code