Hermes + Napi

Author: CedricGuillemet

.github/workflows/build-macos.yml

@@ -18,11 +18,22 @@ on:
         required: false
         type: boolean
         default: false
+      js-engine:
+        # When unset we let Core/Node-API/CMakeLists.txt pick the per-platform
+        # default (JavaScriptCore on macOS).  Pass "Hermes" to fetch and link
+        # against facebook/hermes (static_h branch); pass "V8"/"Chakra"/etc.
+        # to override.
+        required: false
+        type: string
+        default: ''
 
 jobs:
   build:
     runs-on: ${{ inputs.runs-on }}
-    timeout-minutes: 15
+    # Hermes builds take roughly 4x as long as a JSC build because the
+    # umbrella `hermesvm_a` static lib drags in the full Hermes compiler
+    # pipeline.  Allow a wider window when Hermes is selected.
+    timeout-minutes: ${{ inputs.js-engine == 'Hermes' && 60 || 15 }}
     steps:
       - uses: actions/checkout@v5
 
@@ -33,7 +44,8 @@ jobs:
         run: |
           cmake -B Build/macOS -G Xcode \
             -D ENABLE_SANITIZERS=${{ inputs.enable-sanitizers && 'ON' || 'OFF' }} \
-            -D ENABLE_THREAD_SANITIZER=${{ inputs.enable-thread-sanitizer && 'ON' || 'OFF' }}
+            -D ENABLE_THREAD_SANITIZER=${{ inputs.enable-thread-sanitizer && 'ON' || 'OFF' }} \
+            ${{ inputs.js-engine != '' && format('-D NAPI_JAVASCRIPT_ENGINE={0}', inputs.js-engine) || '' }}
 
       - name: Build
         run: cmake --build Build/macOS --target UnitTests --config RelWithDebInfo

.github/workflows/build-win32.yml

@@ -13,7 +13,10 @@ on:
 jobs:
   build:
     runs-on: windows-latest
-    timeout-minutes: 15
+    # Hermes pulls in a large LLVH/Boost.Context/BCGen chain through
+    # `hermesvm_a`; on `windows-latest` the full configure+build comfortably
+    # exceeds the standard 15-minute window.  Keep other engines snappy.
+    timeout-minutes: ${{ inputs.js-engine == 'Hermes' && 60 || 15 }}
     steps:
       - uses: actions/checkout@v5
 

.github/workflows/ci.yml

@@ -32,6 +32,12 @@ jobs:
       platform: x64
       js-engine: V8
 
+  Win32_x64_Hermes:
+    uses: ./.github/workflows/build-win32.yml
+    with:
+      platform: x64
+      js-engine: Hermes
+
   # ── UWP ───────────────────────────────────────────────────────
   UWP_x64_Chakra:
     uses: ./.github/workflows/build-uwp.yml
@@ -109,6 +115,17 @@ jobs:
       runs-on: macos-26
       enable-thread-sanitizer: true
 
+  # Hermes on macOS: only one variant — Hermes is expensive to build, and
+  # we already cover both Xcode toolchains for JSC.  Pinning to 26.4 keeps
+  # the matrix on the newer toolchain that downstream embedders care about
+  # most; bump if needed.
+  macOS_Xcode264_Hermes:
+    uses: ./.github/workflows/build-macos.yml
+    with:
+      xcode-version: '26.4'
+      runs-on: macos-26
+      js-engine: Hermes
+
   # ── iOS ───────────────────────────────────────────────────────
   iOS_Xcode164:
     uses: ./.github/workflows/build-ios.yml

CMakeLists.txt

@@ -28,6 +28,14 @@ FetchContent_Declare(CMakeExtensions
 FetchContent_Declare(googletest
     URL "https://github.com/google/googletest/archive/refs/tags/v1.17.0.tar.gz"
     EXCLUDE_FROM_ALL)
+FetchContent_Declare(hermes
+    GIT_REPOSITORY https://github.com/facebook/hermes.git
+    # Pinned to the tip of the `static_h` branch as of 2026-06-03 so CI is
+    # reproducible.  Bump this SHA when you intentionally want to pick up
+    # upstream Hermes changes — keep it on the static_h branch (Static
+    # Hermes is the variant our NAPI integration targets).
+    GIT_TAG 348582831f50954895da8e80cc91112d51036c69
+    EXCLUDE_FROM_ALL)
 FetchContent_Declare(ios-cmake
     GIT_REPOSITORY https://github.com/leetal/ios-cmake.git
     GIT_TAG 4.4.1
@@ -144,6 +152,33 @@ if(BABYLON_DEBUG_TRACE)
     add_definitions(-DBABYLON_DEBUG_TRACE)
 endif()
 
+if(NAPI_JAVASCRIPT_ENGINE STREQUAL "Hermes")
+    # Configure Hermes static_h options BEFORE making it available so that
+    # cache variables take effect.  We disable the parts of Hermes we don't
+    # need (the unit-test suite, debugger) to keep build time reasonable and
+    # to avoid pulling extra targets into our build tree.  Notably we leave
+    # HERMES_ENABLE_NAPI ON (the default) — that's the whole point of
+    # integrating Hermes here.
+    #
+    # HERMES_ENABLE_TOOLS must stay ON: even when HERMES_ENABLE_TEST_SUITE is
+    # OFF, Hermes unconditionally adds external/node-api-cts and
+    # external/node-api-tests whenever HERMES_ENABLE_NAPI is on, and those
+    # subdirectories reference the `hermes` CLI tool target via
+    # $<TARGET_FILE:hermes>.  CMake fails to generate if the target doesn't
+    # exist, so we let Hermes build its tools.  None of them ship in our
+    # final binaries because they're EXCLUDE_FROM_ALL via FetchContent.
+    set(HERMES_ENABLE_TOOLS ON CACHE BOOL "" FORCE)
+    set(HERMES_ENABLE_TEST_SUITE OFF CACHE BOOL "" FORCE)
+    set(HERMES_ENABLE_DEBUGGER OFF CACHE BOOL "" FORCE)
+    set(HERMES_BUILD_APPLE_FRAMEWORK OFF CACHE BOOL "" FORCE)
+    set(HERMES_ENABLE_NAPI ON CACHE BOOL "" FORCE)
+    # Hermes ships its own bundled gtest as `llvh-gtest` (a different
+    # CMake target name from googletest's `gtest`), so the two coexist
+    # without clashing.  We never link llvh-gtest into our UnitTests
+    # executable, so there's no duplicate-symbol issue at link time.
+    FetchContent_MakeAvailable_With_Message(hermes)
+endif()
+
 if(NAPI_JAVASCRIPT_ENGINE STREQUAL "V8" AND JSRUNTIMEHOST_CORE_APPRUNTIME_V8_INSPECTOR)
     FetchContent_MakeAvailable_With_Message(asio)
     add_library(asio INTERFACE)

Core/AppRuntime/Include/Babylon/AppRuntime.h

@@ -67,6 +67,15 @@ namespace Babylon
         // extra logic around the invocation of a dispatched callback.
         void Execute(Dispatchable<void()> callback);
 
+        // Engine-specific hook called from Dispatch immediately after a user
+        // callback completes.  Most engines auto-drain microtasks at scope
+        // exit, so the implementation is a no-op for Chakra/V8/JSC/JSI.
+        // Hermes does NOT auto-drain; its implementation calls
+        // `Napi::DrainJobs(env)` so Promise continuations and queueMicrotask
+        // callbacks scheduled during the user callback actually run before
+        // the next top-level dispatch.
+        void DrainMicrotasks(Napi::Env env);
+
         Options m_options;
 
         class Impl;

Core/AppRuntime/Source/AppRuntime.cpp

@@ -109,6 +109,13 @@ namespace Babylon
     {
         m_impl->Append([this, func{std::move(func)}](Napi::Env env) mutable {
             Execute([this, env, func{std::move(func)}]() mutable {
+                // Some engines (notably Hermes) require an open NAPI handle
+                // scope before any napi_* call that materializes a value.
+                // The other engines (V8/Chakra/JSC) already provide an outer
+                // scope at the RunEnvironmentTier level, so this extra
+                // scope is harmless there but mandatory for Hermes.
+                Napi::HandleScope scope{env};
+
                 try
                 {
                     func(env);
@@ -122,6 +129,13 @@ namespace Babylon
                     assert(false);
                     std::abort();
                 }
+
+                // Drain engine-level microtasks/jobs queued during the
+                // callback (Promise continuations, queueMicrotask, etc.) so
+                // they run before the next top-level Dispatch.  No-op for
+                // engines that drain automatically; Hermes needs an explicit
+                // pump.
+                DrainMicrotasks(env);
             });
         });
     }

Core/AppRuntime/Source/AppRuntime_Chakra.cpp

@@ -71,4 +71,11 @@ namespace Babylon
         // Detach must come after JsDisposeRuntime since it triggers finalizers which require env.
         Napi::Detach(env);
     }
+
+    void AppRuntime::DrainMicrotasks(Napi::Env)
+    {
+        // Chakra drains promise continuations through its
+        // JsSetPromiseContinuationCallback hook (see RunEnvironmentTier).
+        // No explicit pump needed here.
+    }
 }

Core/AppRuntime/Source/AppRuntime_Hermes.cpp

@@ -0,0 +1,28 @@
+#include "AppRuntime.h"
+#include <napi/env.h>
+
+namespace Babylon
+{
+    void AppRuntime::RunEnvironmentTier(const char*)
+    {
+        // All Hermes runtime + napi_env setup is encapsulated inside the napi
+        // library's env_hermes.cc (see Napi::Attach/Detach).  Keeping the
+        // engine-specific machinery there avoids dragging Hermes headers into
+        // AppRuntime's translation unit.
+        Napi::Env env = Napi::Attach();
+
+        Run(env);
+
+        Napi::Detach(env);
+    }
+
+    void AppRuntime::DrainMicrotasks(Napi::Env env)
+    {
+        // Hermes does not auto-drain its job queue.  Promise continuations,
+        // queueMicrotask callbacks, and pending NAPI finalizers all run via
+        // Runtime::drainJobs().  We pump it after each user callback so async
+        // code (Promises, Mocha's async tests, polyfill schedulers, etc.)
+        // observes the same "between turns" semantics it gets on V8/Chakra.
+        Napi::DrainJobs(env);
+    }
+}

Core/AppRuntime/Source/AppRuntime_JSI.cpp

@@ -45,4 +45,9 @@ namespace Babylon
 
         Napi::Detach(env);
     }
+
+    void AppRuntime::DrainMicrotasks(Napi::Env)
+    {
+        // JSI/V8 backed JSI auto-drains microtasks per scope.
+    }
 }

Core/AppRuntime/Source/AppRuntime_JavaScriptCore.cpp

@@ -23,4 +23,9 @@ namespace Babylon
         // Detach must come after JSGlobalContextRelease since it triggers finalizers which require env.
         Napi::Detach(env);
     }
+
+    void AppRuntime::DrainMicrotasks(Napi::Env)
+    {
+        // JavaScriptCore drains microtasks automatically at script boundaries.
+    }
 }