docs: clarify the Android Hermes vendoring steps (#411)

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.


Claude-Session: https://claude.ai/code/session_01HX4imsygeawVtsmoP1sj3F

Co-authored-by: Claude <noreply@anthropic.com>

Author: kraenhansen

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.

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.