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

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:

[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.
[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.
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:

Bump REACT_NATIVE_MACOS_VERSION / REACT_NATIVE_VERSION in scripts/init-macos-test-app.ts (they are peer-locked; keep them in lockstep).
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.
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).

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:

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

Use the prebuilt Hermes archive for iOS builds

Use the prebuilt Hermes archive for iOS builds (#441)

Status update (2026-10-31): react-native-macos 0.83.0 is out, but it doesn't unblock macOS

react-native-macos@0.83.0 is now latest. I checked its npm tarball against the three failures listed in the issue body.

Fixed in 0.83.0

Build Hermesc: sdks/hermes-engine/utils/build-hermesc-xcode.sh now passes -DCMAKE_BUILD_TYPE=Release.
Build Hermes: build-hermes-xcode.sh builds --target hermesvm and copies lib/hermesvm.framework, and hermes-engine.podspec vendors hermesvm.framework for macOS.

The matching versions would be react-native-macos@0.83.0 with react-native@0.83.10, which it peer-pins exactly, and react@^19.2.0.

Still blocking: (3) JSI skew, and it's worse than this issue expected

The issue body expected (3) to affect only the host module's IHermes include. In fact Hermes itself won't compile:

build-hermes-xcode.sh passes -DJSI_DIR=${REACT_NATIVE_PATH}/ReactCommon/jsi. Hermes' root CMakeLists.txt gives JSI_DIR priority over its own API/jsi, so the pinned static_h Hermes (5a795c9f) gets compiled against react-native-macos 0.83's JSI.
The pinned API/hermes/hermes.cpp overrides roughly 30 JSI methods that RN 0.83's jsi.h doesn't declare, such as createUint8Array, createTypeError and the other create*Error methods, serialize/deserialize, and IRuntime/setRuntimeData. Hermes' jsi.h has 95 pure virtuals; RN 0.83's has 59.
API/hermes/hermes.h includes <jsi/hermes-interfaces.h>, which RN 0.83 doesn't ship. 0.83 has only the older jsi/hermes.h. packages/host/cpp/CxxNodeApiHostModule.cpp includes the same missing header.
The IHermes UUID is the same in both versions (0xe85cfa22…), so the runtime castInterface would still work. The break is entirely at compile time.

How far each react-native release's ReactCommon/jsi/jsi is from the pinned Hermes' API/jsi/jsi (excluding test/):

react-native	ships `hermes-interfaces.h`	files that differ
0.83.10 (react-native-macos 0.83.0's peer)	no	7
0.84.1 / 0.85.3	yes	6
0.86.3	yes	1
0.87.1	yes	0

Item 4 (moving macOS onto the prebuilt Hermes archive) doesn't get around this, because the archive is compiled against the same ReactCommon/jsi.

Revised gate

Re-enabling macOS now needs react-native-macos built on React Native ≥ 0.87, the first release whose JSI matches the pinned Hermes (0.86 is close: one file differs). "≥ 0.82" is no longer enough. Today react-native-macos has nothing newer than 0.83.0 on any dist-tag, including nightly, while core react-native is at 0.88.1.

The workaround would be to bring back the JSI-header overlay that #372 removed, this time for react-native-macos only. That would force all of RN 0.83 to compile against roughly 0.87-level JSI, and ReactInstance.cpp would see IHermes defined twice, once from jsi/hermes.h and once from hermes-interfaces.h. That's the kind of widening local patch this issue argues against, so I haven't pursued it. The re-enabling checklist in the issue body still applies, with "≥ 0.82" read as "≥ 0.87".

Generated by Claude Code

Use the prebuilt Hermes archive for iOS builds (#441)

Navigation Menu

Repository navigation

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

Status

Why it fails

What gates re-enabling macOS

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

Status update (2026-10-31): react-native-macos 0.83.0 is out, but it doesn't unblock macOS

Fixed in 0.83.0

Still blocking: (3) JSI skew, and it's worse than this issue expected

Revised gate

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

Status

Why it fails

What gates re-enabling macOS

Activity

kraenhansen commented on Aug 13, 2026

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

kraenhansen commented on Oct 31, 2026

Status update (2026-10-31): react-native-macos 0.83.0 is out, but it doesn't unblock macOS

Fixed in 0.83.0

Still blocking: (3) JSI skew, and it's worse than this issue expected

Revised gate

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions