chore: better gradle setup #188

artus9033 · 2025-07-17T11:32:19Z

This PR introduces the following:

a new script to the host package (react-native-node-api): consumerSettings.gradle that shall be included in the demo app's settings.gradle; the integration has been described on the bottom of this post & in the ANDROID.md docs
fixes the hermes.ts script which set isEnabled to ora spinners based on the silent mode flag value, which wasn't really a silent mode but just turned off animations of the spinners, by replacing these with isSilent to ensure a true silent mode
adds a postinstall script to the root workspace package.json to automatically npm run build all packages upon install for ease of development

There unfortunately is no way to set env vars from Gradle scripts, therefore automation of export of REACT_NATIVE_OVERRIDE_HERMES_DIR is impossible to be achieved. If this is meant to be a temporary setup, then I would leave this step as manual for the consumer; if this is meant to be permanent, I would send a PR to RN, adding optional secondary resolution of custom Hermes path in those files using Gradle Properties instead, if this is worth the effort. CC @paradowstack @kraenhansen

Gradle script integration code to be added to any app's settings.gradle:

// customize the path to match your node_modules location
apply(from: "../../../node_modules/react-native-node-api/android/consumerSettings.gradle")
applyNodeAPISettings(settings)

changeset-bot · 2025-07-17T11:32:22Z

🦋 Changeset detected

Latest commit: 9077adf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@react-native-node-api/test-app	Patch
react-native-node-api	Patch
cmake-rn	Patch
ferric-cli	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

…script execution

packages/host/android/consumerSettings.gradle

docs/ANDROID.md

docs/IOS.md

package.json

package-lock.json

packages/host/src/node/cli/hermes.ts

docs/ANDROID.md

kraenhansen · 2025-07-17T23:25:00Z

apps/test-app/android/settings.gradle

@@ -19,3 +19,7 @@ apply(from: {
    throw new GradleException("Could not find `react-native-test-app`");
 }())
 applyTestAppSettings(settings)
+
+// customize the path to match your node_modules location
+apply(from: "../../../node_modules/react-native-node-api/android/consumerSettings.gradle")


I wonder now ... how this ever worked 🤔

Oh - I get it now.

The React Native Test App doesn't need this, because of https://github.com/microsoft/react-native-test-app/blob/d06a4ea4abd4dc31231b1c28c253873ce7f80215/test-app.gradle#L55-L65 and

react-native-node-api/apps/test-app/android/gradle.properties

Line 47 in acf1a7c

react.buildFromSource=true

Right, that's already set up thanks to RNTA's scripts - I wasn't aware that you had it configured from my talk to @paradowstack before I jumped into the scripts. Do you think we should leave it there / maybe commented, as a reference sample, additionally to the MD docs? I think some may be concerned that the sample app does not contain this configuration if they browse its source for reference.

docs/ANDROID.md

kraenhansen · 2025-07-17T23:30:14Z

docs/ANDROID.md

+
+To integrate automatic setup of Hermes engine, a special env variable (`REACT_NATIVE_OVERRIDE_HERMES_DIR`) must be set to a proper path. Since Gradle does not really support loading `.env` files, this must be automated by the consumer. We provide the script `react-native-node-api vendor-hermes --silent` which will output a single line, the path to Hermes directory.
+
+Each time you run Android Studio, make sure this is in place.


Suggested change

Each time you run Android Studio, make sure this is in place.

Each time you run Android Studio or start the Android app from a terminal, make sure this is in place.

I'd only change 'start' to 'build' - applied 👍

docs/ANDROID.md

kraenhansen · 2025-07-17T23:34:15Z

First off - thanks a ton for your interest in the project!

I recognize that your PR is in draft and there's a few things that I'd like for you to address before merging this.

artus9033 · 2025-07-18T08:25:03Z

Sure thing, thank you for the feedback & insights @kraenhansen . All we discussed is applied in the latest commit. I left one comment to discuss the test-app's settings.gradle

kraenhansen

Code seems fine 👍 I'm curious if this is actually an improvement in DX and would like a bit more feedback before merging, if that's okay?

kraenhansen · 2025-07-22T10:57:43Z

README.md

@@ -27,6 +27,10 @@

 See the document on ["how it works"](./docs/HOW-IT-WORKS.md) for a detailed description of what it's like to write native modules using this package.

+### Quick start
+
+To get started, first install the dependencies with `npm i` and then build all packages using `npm run build`.


Actually, I intended the "bootstrap" script to be the one you run to build both TypeScript and prebuilds, but it does take a while 🤔

Suggested change

To get started, first install the dependencies with `npm i` and then build all packages using `npm run build`.

To get started, first install the dependencies with `npm i` and then build all packages using `npm run bootstrap`.

kraenhansen · 2025-07-22T11:02:04Z

docs/ANDROID.md

+
+```groovy
+// customize the path to match your node_modules location
+apply(from: "../../../node_modules/react-native-node-api/android/app-settings.gradle")


When we introduce our own settings script it becomes a bit more magical IMO and I'm not 100% convinced this is an increase in DX 🤔 There's something "simple" in just instructing users to build React Native from source and defer to whatever upstream documentation is available for doing that, with a code-snippet to make it easier.

WDYT @shirakaba?

Right now we have asymmetry between the iOS and Android sides – iOS is set up automatically, while Gradle isn't. So I think we need to at least make things consistent.

If this were an Expo project, I'd probably arrange it as a config plugin called withBuildReactNativeFromSource, so that it involves no magic specific react-native-node-api and is just clearly a convenience function.

I think it's okay to defer to the upstream docs for building React Native from source. Maybe that part needn't be handled by our plugin, then?

Something I would like to improve the DX on, though, is this part:

export REACT_NATIVE_OVERRIDE_HERMES_DIR=`npx react-native-node-api vendor-hermes --silent`

It's a pain because it relies on shell stuff, so there's great potential for people to get it wrong (e.g. run it in the wrong directory or forget to export it again).

If this were an Expo project, I'd probably say that npx react-native-node-api vendor-hermes should just append the necessary env var into .env.local for you. But because React Native Community CLI projects don't have any standard env file that they source variables from, and because React Native strictly grabs that variable via System.getenv() (in both react-native-gradle-plugin and hermes-engine), I'm not sure we have any great options.

Any ideas?

kraenhansen · 2025-07-22T11:03:36Z

docs/ANDROID.md

+> [!IMPORTANT]
+> Each time you run Android Studio or build the Android app from a terminal, make sure the below is in place.
+
+Because we're using a version of Hermes patched with Node-API support, we need to build React Native from source. A special environment variable (`REACT_NATIVE_OVERRIDE_HERMES_DIR`) must be set to the path of a Hermes engine with Node-API support. Since Gradle does not support loading `.env` files directly, this must be automated by the consumer. We provide the `react-native-node-api vendor-hermes --silent` command, which will download Hermes and output the path to Hermes directory path as its only output.


Suggested change

Because we're using a version of Hermes patched with Node-API support, we need to build React Native from source. A special environment variable (`REACT_NATIVE_OVERRIDE_HERMES_DIR`) must be set to the path of a Hermes engine with Node-API support. Since Gradle does not support loading `.env` files directly, this must be automated by the consumer. We provide the `react-native-node-api vendor-hermes --silent` command, which will download Hermes and output the path to Hermes directory path as its only output.

Because we're using a version of Hermes patched with Node-API support, we need to build React Native and Hermes from source. A special environment variable (`REACT_NATIVE_OVERRIDE_HERMES_DIR`) must be set to the path of a Hermes engine with Node-API support. Since Gradle does not support loading `.env` files directly, this must be automated by the app developer. We provide the `react-native-node-api vendor-hermes --silent` command, which will download Hermes and output the path to Hermes directory path as its only output.

kraenhansen · 2025-07-22T11:05:04Z

docs/ANDROID.md

+export REACT_NATIVE_OVERRIDE_HERMES_DIR="$(npx react-native-node-api vendor-hermes --silent)"
+```
+
+This either needs to be done each time before Gradle / Android Studio invocation, or permanently in a shell init script such as `~/.zshrc` on Zsh (MacOS) or `~/.bashrc` on Bash (Linux).


I'm not sure this is a good suggestion. It has the potential to mess up people's setup, quite significantly - in a way which is really hard to debug.

Agreed, I think it'd be best to avoid mentioning the idea of populating the user profiles at all.

For Expo apps, we can recommend writing it into .env.local in the root of the project – it's a standard location read by all the Expo build scripts (Gradle included).

For non-Expo apps, I don't think we have any options. The React Native Community CLI template has no hits for .env or .env.local.

shirakaba

Have added some thoughts!

And thanks @artus9033, I was worrying about the DX on this part so this is a great PR to see. Let's keep talking about the ideal shape it should take.

shirakaba · 2025-07-22T23:28:22Z

docs/ANDROID.md

+export REACT_NATIVE_OVERRIDE_HERMES_DIR="$(npx react-native-node-api vendor-hermes --silent)"
+```
+
+This either needs to be done each time before Gradle / Android Studio invocation, or permanently in a shell init script such as `~/.zshrc` on Zsh (MacOS) or `~/.bashrc` on Bash (Linux).


Agreed, I think it'd be best to avoid mentioning the idea of populating the user profiles at all.

For Expo apps, we can recommend writing it into .env.local in the root of the project – it's a standard location read by all the Expo build scripts (Gradle included).

For non-Expo apps, I don't think we have any options. The React Native Community CLI template has no hits for .env or .env.local.

shirakaba · 2025-07-22T23:31:52Z

packages/host/android/app-settings.gradle

+ext.applyNodeAPISettings = { DefaultSettings settings ->
+    def searchDirectory = rootDir.toPath()
+    do {
+        def p = searchDirectory.resolve("node_modules/react-native")


Instead of walking the file system, could we use actual Node module resolution, like the Expo Android template demonstrates?

Caution: I'm not clear whether the reactNativeDir variable is populated in projects made with the React Native Community CLI, so it'd be safest to just re-evaluate the path inside this Gradle script.

shirakaba · 2025-07-23T00:11:42Z

docs/ANDROID.md

+
+```groovy
+// customize the path to match your node_modules location
+apply(from: "../../../node_modules/react-native-node-api/android/app-settings.gradle")


This path (../../../node_modules) assumes a monorepo structure, so won't work on a regular repo.

Can we use proper Node module resolution instead? As demonstrated here.

shirakaba · 2025-07-23T00:28:09Z

docs/ANDROID.md

+
+```groovy
+// customize the path to match your node_modules location
+apply(from: "../../../node_modules/react-native-node-api/android/app-settings.gradle")


Right now we have asymmetry between the iOS and Android sides – iOS is set up automatically, while Gradle isn't. So I think we need to at least make things consistent.

If this were an Expo project, I'd probably arrange it as a config plugin called withBuildReactNativeFromSource, so that it involves no magic specific react-native-node-api and is just clearly a convenience function.

I think it's okay to defer to the upstream docs for building React Native from source. Maybe that part needn't be handled by our plugin, then?

Something I would like to improve the DX on, though, is this part:

export REACT_NATIVE_OVERRIDE_HERMES_DIR=`npx react-native-node-api vendor-hermes --silent`

It's a pain because it relies on shell stuff, so there's great potential for people to get it wrong (e.g. run it in the wrong directory or forget to export it again).

If this were an Expo project, I'd probably say that npx react-native-node-api vendor-hermes should just append the necessary env var into .env.local for you. But because React Native Community CLI projects don't have any standard env file that they source variables from, and because React Native strictly grabs that variable via System.getenv() (in both react-native-gradle-plugin and hermes-engine), I'm not sure we have any great options.

Any ideas?

shirakaba · 2025-07-23T00:37:52Z

There unfortunately is no way to set env vars from Gradle scripts, therefore automation of export of REACT_NATIVE_OVERRIDE_HERMES_DIR is impossible to be achieved. If this is meant to be a temporary setup, then I would leave this step as manual for the consumer; if this is meant to be permanent, I would send a PR to RN, adding optional secondary resolution of custom Hermes path in those files using Gradle Properties instead, if this is worth the effort.

This does seem like a real problem. I've also run into Gradle's limitation here in the past. One approach would be to modify the React Native Community CLI so that it sources .env and .env.local just like Expo does, and we could write into it. I've opened an issue for that here: react-native-community/cli#2692.

But I agree that allowing these to be configured as Gradle properties sounds like the ideal approach, as it's accessible by plugins. Would also be good to cover all Hermes options that are currently only configurable by env vars (e.g. HERMES_ENGINE_TARBALL_PATH, which we could use to offer a prebuilt Hermes).

artus9033 added 2 commits July 17, 2025 12:52

chore: postinstall script to build all packages

511e61a

fix: properly handle silent mode in hermes.ts

9f3ed85

artus9033 requested review from kraenhansen, thymikee and paradowstack July 17, 2025 11:32

artus9033 added 2 commits July 17, 2025 15:13

chore: fix node version on last supported (22) due to by-default-cjs …

4c0cc1d

…script execution

chore: simplify settings.gradle script, extend docs

6b62848

artus9033 force-pushed the chore/better-gradle-setup branch from 8b3614a to 6b62848 Compare July 17, 2025 15:06

chore: added changeset

c755b10