Remove Hermes vendoring once React Native ships a Hermes with Node-API

[kraenhansen]

Tracking the removal of vendor-hermes and everything that hangs off it, gated on React Native shipping a Hermes that carries Node-API.

Why we vendor today

After #372 we no longer patch Hermes — we build it from a pinned commit on the static_h branch, which carries the first-party Node-API implementation under API/napi (target hermesNapi). The pin lives in packages/host/src/node/cli/hermes.ts, and the host calls into it directly (hermes_napi_create_env in packages/host/cpp/CxxNodeApiHostModule.cpp, with the hermes_napi_host struct mirrored in packages/host/cpp/HermesNapiHost.hpp).

React Native's own Hermes doesn't have that code yet, which is the only reason we need REACT_NATIVE_OVERRIDE_HERMES_DIR — and therefore the only reason consumers have to build React Native from source at all.

The gate

React Native doesn't tag every nightly, so read the head of the default branch rather than a release:

1. packages/react-native/sdks/hermes-engine/version.properties on the default branch of react/react-native → HERMES_VERSION_NAME.
2. Check whether facebook/hermes at tag hermes-v$HERMES_VERSION_NAME has an API/napi/ directory.

State as of 2026-08-12:

• HERMES_VERSION_NAME=260318099.0.1
• API/napi/hermes_napi.h → 404 at hermes-v260318099.0.1, while API/hermes/hermes.h resolves at the same tag — so the tag exists and simply carries no Node-API.

That's the cheap signal to poll. Something like:

version=$(curl -fsSL https://raw.githubusercontent.com/react/react-native/main/packages/react-native/sdks/hermes-engine/version.properties | sed -n 's/^HERMES_VERSION_NAME=//p')
curl -fsSLo /dev/null "https://raw.githubusercontent.com/facebook/hermes/hermes-v$version/API/napi/hermes_napi.h" && echo "Node-API has landed in RN's Hermes ($version)"

Necessary, but not sufficient

The version check tells us the source has Node-API in it; before dropping anything we still need the shipped artifacts to expose it:

• the hermes-engine AAR's libhermesvm.so must export hermes_napi_create_env (Hermes has to build the hermesNapi target and keep it visible under its global -fvisibility=hidden, cf. napi: give hermes_napi.h public API C linkage facebook/hermes#2106 — see the pin comment in hermes.ts),
• the same for the Hermes framework shipped through the podspec on Apple platforms,
• hermes_napi.h (or an equivalent public header) needs to reach us through prefab / the framework headers, so HermesNapiHost.hpp can include it instead of mirroring the struct,
• IHermes::getVMRuntimeUnsafe() still has to be reachable from the JSI runtime.

The real acceptance test is the test app building and passing against a stock React Native with no REACT_NATIVE_OVERRIDE_HERMES_DIR set and no build-from-source configuration.

What removal touches

• packages/host/src/node/cli/hermes.ts — the vendor-hermes command, plus its registration in packages/host/src/node/cli/program.ts (a breaking CLI change, so it wants a major changeset)
• packages/host/android/build.gradle:7-17 — the REACT_NATIVE_OVERRIDE_HERMES_DIR guard, and packages/host/src/node/gradle.test.ts, which asserts that error
• packages/host/scripts/patch-hermes.rb and its require_relative in the podspec
• .github/workflows/check.yml:330-333 — the vendoring step in the Android job
• apps/test-app/android/gradle.properties — react.buildFromSource=true becomes unnecessary
• packages/host/cpp/HermesNapiHost.hpp — include the real hermes_napi.h instead of mirroring hermes_napi_host, which also removes the "re-diff on every pin bump" hazard
• docs/ANDROID.md — most of it disappears; Android stops needing a source build (see docs: clarify the Android Hermes vendoring steps #411 for its current state)
• README.md (the supported-versions note), packages/host/README.md, AGENTS.md § Critical Build Dependencies
• packages/host/package.json — the react-native peer dependency can widen from a single nightly to a real range

Related

• Provide prebuilds for Hermes patched with Node-API #177 — prebuilt Node-API Hermes, the interim mitigation if this takes a while
• macOS test app is blocked on react-native-macos ≥ 0.82 (Hermes static_h build scripts) #392 — react-native-macos blocked on the same story
• chore: better gradle setup #188 — the consumer-side Gradle settings helper, which becomes moot along with the source-build requirement