Static Hermes for React Native

[piaskowyk]

Summary:

This PR proposes changes to React Native to adopt the latest version of static Hermes. I've already made required changes for Hermes code, which you can view facebook/hermes#1566

Here's an overview of what's included:

• Naming and Localization Updates: I've made several changes, including renaming libraries and updating the localization of binaries.
• Build Script and CI Enhancements: I've updated the paths and build flags to align with the latest requirements.
• Removal of Legacy Debugger: I've removed legacy debugger integration, as the latest Hermes version no longer supports these debugger symbols.

Remarks

• I've used a .hermesversion file as a temporary workaround to test static Hermes from a specific commit until the proper tag is created.
• I've used Static Hermes version from commit d6c8fe6f1a1135aa2528b775bbd4662c625c0088 - facebook/hermes@d6c8fe6 which is the newest commit for (08.01.2025)
• I haven't implemented an opt-in mechanism yet (also I don't know if it's necessary to implement) because I want to discuss my vision with you before proceeding.
• I acknowledge that these changes are potentially a bit intrusive, so I am open to discussion and any suggestions.

Benchmarks

The new implementation of Hermes offers a significant performance boost. Below are results of nBody benchmark.

Platform	Variant	Regular Hermes [ms]	Static Hermes [ms]	Improvements [%]
Android	Debug	1826.31	1222.32	33.07%
iOS	Debug	1286.91	858.08	33.32%
Android	Release	1087.47	727.5	33.10%
iOS	Release	892.15	541.65	39.28%

Tested on physical devices:

• Android - Google Pixel 6
• iOS - Phone 14

Benchmark source code

const PI = Math.PI;
const SOLAR_MASS = 4 * PI * PI;
const DAYS_PER_YEAR = 365.24;

class Body {
  x;
  y;
  z;
  vx;
  vy;
  vz;
  mass;

  constructor(
    x,
    y,
    z,
    vx,
    vy,
    vz,
    mass
  ) {
    this.x = x;
    this.y = y;
    this.z = z;
    this.vx = vx;
    this.vy = vy;
    this.vz = vz;
    this.mass = mass;
  }
}

function Jupiter() {
  return new Body(
    4.8414314424647209,
    -1.16032004402742839,
    -1.03622044471123109e-1,
    1.66007664274403694e-3 * DAYS_PER_YEAR,
    7.69901118419740425e-3 * DAYS_PER_YEAR,
    -6.90460016972063023e-5 * DAYS_PER_YEAR,
    9.54791938424326609e-4 * SOLAR_MASS
  );
}

function Saturn() {
  return new Body(
    8.34336671824457987,
    4.12479856412430479,
    -4.03523417114321381e-1,
    -2.76742510726862411e-3 * DAYS_PER_YEAR,
    4.99852801234917238e-3 * DAYS_PER_YEAR,
    2.30417297573763929e-5 * DAYS_PER_YEAR,
    2.85885980666130812e-4 * SOLAR_MASS
  );
}

function Uranus() {
  return new Body(
    1.2894369562139131e1,
    -1.51111514016986312e1,
    -2.23307578892655734e-1,
    2.96460137564761618e-3 * DAYS_PER_YEAR,
    2.3784717395948095e-3 * DAYS_PER_YEAR,
    -2.96589568540237556e-5 * DAYS_PER_YEAR,
    4.36624404335156298e-5 * SOLAR_MASS
  );
}

function Neptune() {
  return new Body(
    1.53796971148509165e1,
    -2.59193146099879641e1,
    1.79258772950371181e-1,
    2.68067772490389322e-3 * DAYS_PER_YEAR,
    1.62824170038242295e-3 * DAYS_PER_YEAR,
    -9.5159225451971587e-5 * DAYS_PER_YEAR,
    5.15138902046611451e-5 * SOLAR_MASS
  );
}

function Sun() {
  return new Body(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, SOLAR_MASS);
}

const bodies = [Sun(), Jupiter(), Saturn(), Uranus(), Neptune()];

function offsetMomentum(): void {
  let px = 0;
  let py = 0;
  let pz = 0;
  const size = bodies.length;
  for (let i = 0; i < size; i++) {
    const body = bodies[i];
    const mass = body.mass;
    px += body.vx * mass;
    py += body.vy * mass;
    pz += body.vz * mass;
  }

  const body = bodies[0];
  body.vx = -px / SOLAR_MASS;
  body.vy = -py / SOLAR_MASS;
  body.vz = -pz / SOLAR_MASS;
}

function advance(dt) {
  const size = bodies.length;

  for (let i = 0; i < size; i++) {
    const bodyi = bodies[i];
    let vxi = bodyi.vx;
    let vyi = bodyi.vy;
    let vzi = bodyi.vz;
    for (let j = i + 1; j < size; j++) {
      const bodyj = bodies[j];
      const dx = bodyi.x - bodyj.x;
      const dy = bodyi.y - bodyj.y;
      const dz = bodyi.z - bodyj.z;

      const d2 = dx * dx + dy * dy + dz * dz;
      const mag = dt / (d2 * Math.sqrt(d2));

      const massj = bodyj.mass;
      vxi -= dx * massj * mag;
      vyi -= dy * massj * mag;
      vzi -= dz * massj * mag;

      const massi = bodyi.mass;
      bodyj.vx += dx * massi * mag;
      bodyj.vy += dy * massi * mag;
      bodyj.vz += dz * massi * mag;
    }
    bodyi.vx = vxi;
    bodyi.vy = vyi;
    bodyi.vz = vzi;
  }

  for (let i = 0; i < size; i++) {
    const body = bodies[i];
    body.x += dt * body.vx;
    body.y += dt * body.vy;
    body.z += dt * body.vz;
  }
}

function energy() {
  let e = 0;
  const size = bodies.length;

  for (let i = 0; i < size; i++) {
    const bodyi = bodies[i];

    e +=
      0.5 *
      bodyi.mass *
      (bodyi.vx * bodyi.vx + bodyi.vy * bodyi.vy + bodyi.vz * bodyi.vz);

    for (let j = i + 1; j < size; j++) {
      const bodyj = bodies[j];
      const dx = bodyi.x - bodyj.x;
      const dy = bodyi.y - bodyj.y;
      const dz = bodyi.z - bodyj.z;

      const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
      e -= (bodyi.mass * bodyj.mass) / distance;
    }
  }
  return e;
}

function nbody() {
  const n = 400_000;
  //const n = 100;

  offsetMomentum();
  for (let i = 0; i < n; i++) {
    advance(0.01);
  }

  return energy();
}

function runTest() {
  const start = performance.now();
  const result = nbody();
  const end = performance.now();
  console.log(`energy: ${result}`);
  console.log(`time: ${end - start}`);
}

Changelog:

[GENERAL] [CHANGED] - Support for Static Hermes

Test Plan:

Just run RNTester app.

[huntie]

Hey @piaskowyk,

Removal of Legacy Debugger — unfortunately, we still depend on these codepaths in some apps in the Meta codebase. We're going to need some validation/updates on our side around this, so that's at least one blocker. Am taking a look to understand.

[piaskowyk]

Hey @huntie 👋
Thanks for taking a look at it! I understand consideration, of course. Is there anything I can do to make the migration easier for you? I'm open to collaboration if it can be helpful.

[cipolleschi]

Thanks for the PR and I apologize that this took so much time. It completely slipped from the list of PRs I had to review.

I'll have a closer look at it on Monday.

[cipolleschi]

Hi @piaskowyk, thanks for working on this. I think it is great work!
I have several thoughts:

1. The pr is a bit too big and i can see it will be hard to land it as it is. It touches too many parts and it will require the expertise of too many people to land it quickly. I understand you create it like this to show the whole picture, but I believe it will have more success if we manage to split it in smaller pieces.
2. We cannot really ship Static Hermes and replace Hermes completely. This kind of changes needs proper communications and feature-flags mechanisms for people that don't want to adopt the the technology immediately. There might be different reasons for that. For example, some critical applications might not want to risk to run an a different engine without experimenting with it before. And we should not prevent them from updating React Native because they don't want to use the new Engine.
3. At Meta, we consume Hermes from the latest commit on main. We should not depend on the .hermesversion file, which is instead used for numbered releases. That change needs to be reverted and we need to verify that everything keep building and running from the latest commit on main for SHermes
4. There is the point highlighted by @huntie. We need to keep the Legacy Debugger around. I don't know what this work entails so I'd defer that to the DevX team.
5. From CI, I can see that all the iOS tests on RNTester are failing. Of course we can't merge a PR that makes the CI fail! 😅

We are more than happy to collaborate to make the PR work in all the scenario we need! 😄

[piaskowyk]

Thanks for taking a look at it 🙌

1. Ok, I'll try to split the PR into smaller ones
2. Sure thing. I'll come up with some ideas to make the integration seamless for everyone
3. Since the main branch of https://github.com/facebook/hermes doesn’t contain Static Hermes changes, should I use the static_h branch as the "main" branch for React Native builds with Static Hermes?
4. Are there any sources or articles I can read to get more familiar with the legacy and modern debugger? It would help me avoid unintentional regressions related to debuggers.
5. 🫡

[cipolleschi]

Thanks for the answers! These are my thoughts on the open questions you have.

3. Since the main branch of facebook/hermes doesn’t contain Static Hermes changes, should I use the static_h branch as the "main" branch for React Native builds with Static Hermes?

Yep, seems reasonable. We can have a "RCT_USE_S_HERMES" flag that is passed to cocoapods and if it is set to "1", we use the latest commit from s_hermes branch.
On Android, we can add a similar useSHermes prop in the gradle.properties file and handle it from the RNGP.

USE_S_HERMES will have priority on USE_HERMES.
cc. @cortinico

4. Are there any sources or articles I can read to get more familiar with the legacy and modern debugger? It would help me avoid unintentional regressions related to debuggers.

This is a question for @huntie... But AFAIU, this is an internal limitation only, so I'd say that we should just keep the files you removed there until we cleared the ground internally and then we can remove them

[cortinico]

On Android, we can add a similar useSHermes prop in the gradle.properties file and handle it from the RNGP.

Yup it can be staticHermesEnabled on Android.

Also on Android the situation is a bit different as we prebuild Hermes for the user. I think the easiest and most straightforward solution is that we ask the Hermes team to point main to the static_h branch.

As an alternative, we can just update our builds to download from static_h rather than main here:

react-native/packages/react-native/ReactAndroid/hermes-engine/build.gradle.kts

Lines 80 to 85 in 4535e62

	var hermesVersion = "main"
	val hermesVersionFile = File(reactNativeRootDir, "sdks/.hermesversion")
	if (hermesVersionFile.exists()) {
	hermesVersion = hermesVersionFile.readText()
	}

If we want to make this toggleable for the users, we'll have to produce 2 Hermes artifacts (which I don't think it's worth the effort).

[hkochniss]

Can someone comment on a hopefully unwarrented worry about OTA updates like Expo Update not working anymore with static hermes? As I understand many companies, esp. startups chose RN for its back-then unique OTA capability (Flutter got it in late 23 thanks to shorebird.dev so it's not a unique selling point anymore today).

Seems to me that Static Hermes conflicts with the OTA usecase, as Apple seems to draw the line when it comes to "over the air binary downloads", at least they did so far with native Objective-C Apps that tried to download binary artifacts and dynamically executed them, and banned a lot of Apps who did that a while ago from the store. I guess somehow Apple sees bundled Runtime-Hermes as an "ok security boundary", akin to their own JSC and WkWebkit (I don't know the Hermes team pulled that off btw, kudos). ok seems classic Interpreter-based Hermes is ok as it does not "write to memory that is marked executable for security purposes": HackerNews comment

But static Hermes means no more Hermes interpreter.. right? So will OTA Updates still work, or is that not clarified yet?

Am I just seeing problems where there aren't any? Thanks for clarifcation.

[floydkim]

@hkochniss
I remember hearing about Static Hermes and OTA updates mentioned in a talk at React Universe Conf 2024. (Hermes: better performance with runtime bytecode translation — Tzvetan Mikov)
This talk introduced a new on-device bytecode translation, which allows OTA updates to function as they currently do. (Reference)
Unfortunately, it was mentioned that OTA updates might be difficult or even impossible with the AOT compilation approach. (Reference)

[hkochniss]

@hkochniss I remember hearing about Static Hermes and OTA updates mentioned in a talk at React Universe Conf 2024. (Hermes: better performance with runtime bytecode translation — Tzvetan Mikov) This talk introduced a new on-device bytecode translation, which allows OTA updates to function as they currently do. (Reference) Unfortunately, it was mentioned that OTA updates might be difficult or even impossible with the AOT compilation approach. (Reference)

Thanks for the answer, interesting talk. Still not sure this will be possible on iOS, given that executing raw assembly instructions without an Apple safeguard seems prohibited, maybe he meant "on Android only", as I don't see an Interpreter executing this assembly. Would like clarification from one of the core team members.

Basically see comment here

[cipolleschi]

@hkochniss There is a lot of confusion in the communication and it is largely our fault.

In 2023, we presented Static Hermes at RN EU, as a next generation of Hermes that was able to compile JS code to native code. This was an experimental version, not ready to be shipped.
In 2024, we presente a version of Hermes with bytecode translation that was running more optimized code. If you pay attention to the title of the talk, it just says Hermes, not Static Hermes.

What we are experimenting with at Meta and what could be maybe ready to be brought to the OSS community, is this second version. More than static Hermes, you should consider it a Hermes 2.0, or a New Hermes. But it will not have the Static Hermes connotation of compiling JS code to native code.

This PR aims to provide a way to use this New Hermes, with JIT and other optimizations, in React Native, but there won't be any JS --> Native compilation.

As far as we know, OTA will keep working fine with this new version of Hermes.

That said, we are still experimenting with the Static aspects of Hermes, but the team encountered issues that needs to be solved before having a version ready to be shipped. Some issues are related to having typed and untyped code in the same codebase, for example. For sure, we will look into the OTA aspect of Static Hermes before shipping it to the OSS.

If you want to learn more, Tzvetan was on the React Native Radio talking about Static Hermes last week.

[hkochniss]

@hkochniss There is a lot of confusion in the communication and it is largely our fault.

Many thanks for this excellent explenation, I think this helps a lot of people eventually understand the (current) direction and what to expect.