From 95ea591d7ddbfb94c5131cadcf276d2a6d3f2bac Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 12 Aug 2026 13:21:06 +0000 Subject: [PATCH] docs: clarify the Android Hermes vendoring steps MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Android setup has two separate requirements — building React Native from source and pointing it at the vendored Hermes — and the doc ran them together without saying why either is needed. - Split them into their own sections and say up front that this is the manual equivalent of what `pod install` does on Apple platforms. - Note that apps based on react-native-test-app get the dependency substitutions from `react.buildFromSource=true` instead of editing settings.gradle themselves, as apps/test-app does. - Spell out that REACT_NATIVE_OVERRIDE_HERMES_DIR is read from the environment (Gradle cannot set it for its own build), so it has to be exported for every shell — or for the environment Android Studio is launched from — and what goes wrong without it. Also drop the last two references to a "patched" Hermes from the host README, left over from before we adopted Hermes' first-party Node-API. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01HX4imsygeawVtsmoP1sj3F --- docs/ANDROID.md | 38 ++++++++++++++++++++++++++++++++++++-- packages/host/README.md | 4 ++-- 2 files changed, 38 insertions(+), 4 deletions(-) diff --git a/docs/ANDROID.md b/docs/ANDROID.md index 4b285812..6fddd15a 100644 --- a/docs/ANDROID.md +++ b/docs/ANDROID.md @@ -1,8 +1,13 @@ # Android support -## Building Hermes from source +Android needs two things that iOS gets automatically during `pod install`: +React Native has to be built from source, and the build has to be pointed at the +Hermes we vendor. Both are described below. -Because we build Hermes from source (a pinned commit carrying its Node-API implementation), we need to build React Native from source too. +## Building React Native from source + +Because we build Hermes from source (a pinned commit carrying its Node-API +implementation), we need to build React Native from source too. Follow [the React Native documentation on how to build from source](https://reactnative.dev/contributing/how-to-build-from-source#update-your-project-to-build-from-source). @@ -23,6 +28,14 @@ In particular, you will have to edit the `android/settings.gradle` file as follo > + } > ``` +If your app is based on [`react-native-test-app`](https://github.com/microsoft/react-native-test-app), +you don't need to edit `settings.gradle` yourself: it applies the same +substitutions when `react.buildFromSource=true` is set in +`android/gradle.properties`. That is how the test app in this repository builds — +see [`apps/test-app/android/gradle.properties`](../apps/test-app/android/gradle.properties). + +## Vendoring Hermes + To fetch the pinned Hermes, you need to run from your app package: ``` @@ -37,6 +50,27 @@ This can be combined into a single line: export REACT_NATIVE_OVERRIDE_HERMES_DIR=$(npx react-native-node-api vendor-hermes --silent) ``` +React Native reads this as an environment variable, and Gradle cannot set one +for its own build, so it has to be exported in whatever ends up invoking Gradle: + +- the terminal you run `./gradlew` or `npx react-native run-android` from, for + every new shell, +- or the environment Android Studio is launched from — starting it from a shell + that has the variable set is the simplest way to get it there. + +Re-running the command is cheap: it re-uses the existing clone and just prints +its path. If the variable is missing, the build fails early with a message +repeating the command to run. + +Without the override, React Native downloads and builds its own Hermes, which +does not carry the Node-API implementation this package links against — the +build then fails to find `hermes_napi_create_env`. + +> [!NOTE] +> On Apple platforms this is automated: the podspec vendors Hermes during +> `pod install` when the variable isn't already set, so there is no manual step +> there. + ## Cleaning your React Native build folders If you've accidentally built your app without the vendored Hermes, you can clean things up by deleting the `ReactAndroid` build folder. diff --git a/packages/host/README.md b/packages/host/README.md index db57dfdc..cda6517e 100644 --- a/packages/host/README.md +++ b/packages/host/README.md @@ -47,7 +47,7 @@ The plugin rewrites the `require("./addon.node")` (and `require("bindings")("add ### 3. Build your app - **iOS:** run `pod install` as usual — addons found in your dependencies are linked as part of it. Re-run it whenever you add or remove a dependency shipping an addon. -- **Android:** requires a few extra steps, since React Native has to be built from source against the patched Hermes. See [the Android documentation](https://github.com/callstackincubator/react-native-node-api/blob/main/docs/ANDROID.md). +- **Android:** requires a few extra steps, since React Native has to be built from source against the vendored Hermes. See [the Android documentation](https://github.com/callstackincubator/react-native-node-api/blob/main/docs/ANDROID.md). ## Usage @@ -79,6 +79,6 @@ This prints every Node-API module it finds in your dependencies and the name it ## Documentation - [Auto-linking](https://github.com/callstackincubator/react-native-node-api/blob/main/docs/AUTO-LINKING.md) — how prebuilt binaries are discovered, copied and renamed. -- [Android support](https://github.com/callstackincubator/react-native-node-api/blob/main/docs/ANDROID.md) — building React Native from source with the patched Hermes. +- [Android support](https://github.com/callstackincubator/react-native-node-api/blob/main/docs/ANDROID.md) — building React Native from source with the vendored Hermes. - [Usage](https://github.com/callstackincubator/react-native-node-api/blob/main/docs/USAGE.md) — for library authors wanting to ship a Node-API module. - [How it works](https://github.com/callstackincubator/react-native-node-api/blob/main/docs/HOW-IT-WORKS.md) — the path from `import` to native code.