Basalt

Porting notes

What it takes to build React Native's C++ core somewhere it was not built before, and the handful of upstream facts that the build scripts depend on.

What it takes to build React Native's C++ core somewhere it was not built before, and the handful of upstream facts that the build scripts depend on.

This is the file native/bootstrap.sh, scripts/react-native.pin and .github/workflows/ci.yml point at. Everything here was arrived at by building rather than by reading, and each section says what breaks if you do not do it.

Building against an installed React Native

ReactCxxPlatform is not in the npm package. packages/react-native/package.json lists ReactCommon, ReactAndroid and ReactApple under files, and not ReactCxxPlatform, so an installed React Native does not carry the layer an out-of-tree C++ platform is built on, and react-native run-linux --build used to need a source checkout. Every app has an installed React Native and almost none has a checkout.

The upstream fix is one line, adding "ReactCxxPlatform" to that files array. It costs about 1% of the package. Nothing in the existing issues and pull requests mentioning ReactCxxPlatform raises the packaging question, and nothing has been opened from here: a one-line packaging change with one obscure consumer is easy to ignore, and this platform has no users yet to point at.

The workaround is to fetch the directory, not to vendor it. When React Native is an installed package with no ReactCxxPlatform, bootstrap does a sparse, blobless clone of that one directory at the tag matching the app's exact version: about 3MB and four seconds, a smaller bargain than the folly and Hermes downloads it already makes.

Fetching is forced rather than preferred. Carrying a copy in this package was the obvious answer and cannot work: that layer tracks ReactCommon closely, and main's copy fails against 0.87.1 on a ResizeObserver header that did not exist and a ReactInstance::createJSCallInvoker that had not been added. One copy cannot serve several React Natives, and a vendored copy would pin this package to a single version the way react-native-windows pins to one exact nightly. Fetching at the app's own version keeps the C++ and the JavaScript in step by construction.

A second, smaller gap, which the build found and a path check did not: ReactCommon/react/nativemodule/cputime ships its C++ but not its codegen spec, which lives under src/private/testing/fantom/specs/ and is reasonably excluded. The package therefore contains C++ that cannot be compiled from the package, and the failure reads as a missing NativeCPUTimeCxxSpec template, like a codegen bug rather than a packaging one. Nothing links that target, so this platform does not build it.

Porting a third-party native module

A module that works on a phone and not here is almost always a module whose native half nobody has written for a desktop. The JavaScript is already portable; what is missing is the thing behind TurboModuleRegistry.getEnforcing.

packages/basalt-async-storage is the worked example, and this is the recipe it produced.

1. Check that the module ships a spec. Its package.json says so:

"codegenConfig": {"name": "AsyncStorageSpec", "type": "modules", "jsSrcsDir": "src"}

A module without one is hand-written on every platform and has no interface to generate; a module with one has the same interface everywhere, and that is what you implement.

2. Let the build generate it. Nothing to do: buildHost runs React Native's codegen over the app's own dependencies whenever any of them declares a spec, and puts the result on the include path. You get a header-only CRTP base class:

#include <react/renderer/components/AsyncStorageSpec/AsyncStorageSpecJSI.h>

class AsyncStorageModule
    : public facebook::react::NativeAsyncStorageCxxSpec<AsyncStorageModule> { ... };

Its kModuleName is already the name the JavaScript asks for, and if the module changes a signature in a later release this stops compiling, which is the point of deriving from it rather than matching it by hand.

3. Write the implementation, and keep it portable if it can be. Method signatures come from the spec: a Promise<T> is a method returning jsi::Value, and core/JsiPromise.h builds a settled one, which is honest whenever the work underneath is synchronous. Anything that is really about data rather than about a platform API wants no per-desktop code at all.

4. Put it in core, guarded by the generated header. Not in a package of its own: see DECISIONS.md, where applying this project's own rule to a wrapper says core. The whole point is that an app runs npm install <the module> and it works, and a companion package it has to find out about is the opposite of that.

packages/basalt-core/native/CMakeLists.txt compiles the implementation only when the spec header exists, which happens only when the app installed the module, and appends the factory to BASALT_PACKAGE_TURBO_MODULES -- the same generated chain a capability package uses, which is what makes it reachable without all three hosts naming it. See core/PackageModules.h.

Nothing new ships: the app imports the module it already imports, and this is the half that was missing.

Where this does not apply. A module whose native half needs a permission, or hardware, or three separate implementations, is a capability package by the rule in DECISIONS.md -- basalt-notifications and basalt-skia are the shipped examples -- and a package needs a trusted publisher before it can go out. CONTRIBUTING.md has those three steps.

A module may ask for more than one native module

async-storage is the worked example of this too. Its JavaScript has a .windows variant, this platform uses React Native's real platform names, so Metro resolves it on Windows -- and it asks for a different module, RNCAsyncStorage, with a callback interface declared in that file by hand rather than in the spec. A port that satisfied the generated spec passed on Linux and macOS and failed on Windows with Failed to load TurboModule.

So: read the module's JavaScript for platform variants before believing the spec is the whole interface, and answer every module it asks for on every desktop rather than only where it asks. Which one an app gets is the module's business, and a native half that is the same everywhere is one less thing that can differ.

The second interface is hand-written on both sides, so unlike the generated one it can drift. There is no compiler to catch that, only a scenario.

Two things that will catch you

Bridging<std::tuple> is one-way. It is BridgingStatic, which defines toJs and no fromJs, so a [key, value] pair can be answered and cannot be received. Take std::vector<std::vector<std::string>> going in and a tuple coming out.

Codegen writes structs only for named types. A spec with an inline object literal -- {key: string, value: string | null}[] -- generates none, and you write the Bridging<> specialisation yourself. It is about twenty lines and it is the only interface code in the package that is not generated.

Which React Natives are supported

supported-versions.json names, for each supported React Native, the Hermes to build. Bootstrap reads it before downloading or compiling anything and refuses an unsupported version in seconds, with a message saying what is supported and where to look.

Today that is React Native 0.86.x, 0.87.x and 0.88.x, verified against 0.86.3, 0.87.1 and 0.88.1, and main for development.

A pinned triple rather than following the app, because following the app meant every combination was its own experiment. Adding a version is now a deliberate act: build against it, run both suites, add an entry. It cannot be done by widening a range, and that is the point; 0.83 through 0.86 were once described as "expected to work", which was a prediction wearing the clothes of support. They are listed as untested and refused.

ReactCxxPlatform still comes from the app's exact version rather than from the table, and that is not an inconsistency: the table bounds which minors are supported, and the fetch keeps the C++ and the JavaScript exact within one.

Hermes on Windows

Windows is listed among the platforms Meta publishes a prebuilt Hermes for, and the prebuilt does not exist. So Windows builds Hermes from source, which needs four things, two of them upstream bugs.

HERMES_ALLOW_BOOST_CONTEXT=0. Hermes' vendored boost::context throws std::bad_alloc from its Windows stack allocator, and Hermes compiles with exceptions off. The POSIX allocator does not, which is why this is Windows-only. This is Hermes' own option for exactly that case, the one its ASAN and Emscripten builds use, and the whole path is behind #if HERMES_USE_BOOST_CONTEXT, so it is a clean fallback rather than a hole.

HERMES_EMPTY_BASES on VM::Environment. Static Hermes asserts that the C++ Environment and the C SHEnvironment are layout-identical. sizeof matches and the offsets do not, because Environment multiply-inherits from VariableSizeRuntimeCell and an empty base, llvh::TrailingObjects, and the MSVC ABI does not collapse empty bases the way the Itanium ABI does.

The fix is one word and Hermes already has it. Support/Compiler.h defines

#define HERMES_EMPTY_BASES __declspec(empty_bases)

with a comment saying it is necessary for PointerBase alignment under HERMESVM_CONTIGUOUS_HEAP, which is the mode this builds in, and the macro is applied to nothing at all in the entire tree. Dead code that was presumably attached to something once. Applying it to Environment clears the assertion.

Exceptions, for React Native's jsi. A POSIX assumption hiding inside a difference between two compilers' defaults, and the most interesting of the three.

jsi.cpp throws JSError. Hermes' cmake/modules/Hermes.cmake strips /EHsc out of CMAKE_CXX_FLAGS wholesale to avoid a D9025 warning, then puts /EHsc or /EHs-c- back on each of its own targets through hermes_update_compile_flags(). React Native's jsi is not one of its own targets: it arrives through JSI_DIR, never goes through that helper, and so ends up with no /EH flag at all, CMake's default having been removed on its behalf. clang with no flag defaults exceptions on; clang-cl with no flag defaults them off. The strip is safe on every platform Hermes is tested on and fatal on this one.

HERMES_ENABLE_EH=ON is the supported knob for Hermes' own targets, and it has to be HERMES_ENABLE_RTTI=ON alongside it, API/hermes/CMakeLists.txt refuses the mixed case outright. Worth knowing because the failure arrives as a configure error about ICU much further down the log, which is collateral and sends you looking in the wrong place.

For the jsi target the flag has to come from CMAKE_CXX_FLAGS instead, spelled /EHs /EHc: exactly equivalent, and not the literal string their REPLACE looks for.

One trap, recorded because it cost a full rebuild: -DCMAKE_CXX_FLAGS=... replaces CMake's platform defaults rather than adding to them, and those defaults are where /DWIN32 /D_WINDOWS come from. Hermes' OSCompat.h keys its <unistd.h> include on _WINDOWS, so overriding the variable makes a Windows build start looking for POSIX headers. Pass the defaults back with it.

No -Werror=undef under clang-cl, from Hermes 260318099 (React Native 0.88). hermes_enable_werror_undef in cmake/modules/Hermes.cmake makes -Wundef an error for every GCC_COMPATIBLE compiler, and Hermes counts clang-cl as one. clang-cl does not define __GNUC__, and Hermes's vendored llvh tests it bare -- #if __GNUC__ && ... in Support/Compiler.h, four more in MathExtras.h -- so the first file that includes them stops the build. clang and GCC define the macro and never see it. Bootstrap adds AND NOT CLANG_CL to the macro's condition: the flag is a lint, and the headers are upstream's to fix.

clang-cl rather than cl

The two front ends fail differently on Hermes, and the difference decided the toolchain for the whole core build:

  • cl stops at 260 of 415 on __builtin_expect in Static Hermes' static_h.h: a GCC and Clang builtin MSVC does not have, and not something a flag can supply.
  • clang-cl has that builtin and gets past it, which is what makes the three fixes above sufficient rather than the first of a long list.

docs/DECISIONS.md also prefers clang wherever there is a choice, for independent reasons.

The three hosts are not held to the same warnings

React Native's own build flags carry -Werror on Linux and do not on macOS, and a header of ours compiled inside those translation units inherits the difference. So there is a class of error that cannot be reproduced on a Mac at all: the same file, the same compiler, different strictness.

The one that caught it, 2026-10-06. MenuEntry::separator() in core/PlatformServices.h built itself with a designated initializer naming three of the struct's fields. Adding two more fields made that incomplete:

PlatformServices.h:147: error: missing field 'role' initializer
[-Werror,-Wmissing-field-initializers]

Clean on AppKit, and all three Linux shards dead at the Build step. The fix was to assign the fields instead, which no new field can invalidate, and the lesson is narrow and worth keeping: in anything under core/, do not write a designated initializer that names some fields and not others. It is a Linux build error waiting for the next person who extends the struct, and they will not see it coming on a Mac.

Running the Linux host under macOS does not help here; it is the same build with the same flags this machine uses. Only CI, or a Linux box, applies the other set.

A host object is destroyed on Hermes's thread, not yours

From Hermes 260318099, which React Native 0.88 pins, a jsi::HostObject, a host function or a jsi::NativeState is not destroyed where the runtime let go of it. JsiProxy::~JsiProxy hands the last reference to a SerialExecutor, a finalizer thread Hermes starts for the purpose, and ~HermesRuntime joins that thread. A TurboModule is a host object, so its destructor runs there too.

So a module's destructor may not touch the UI, and may not wait for the UI thread. The first one that did was ~DesktopMenuModule, which rebuilt the default menu inline: NSMenu waits on the main thread, the main thread was in applicationWillTerminate joining the finalizer thread, and the host never quit. On 0.87 the same destructor ran on the thread that destroyed the runtime, which at quit was the main thread, so nothing showed.

What a destructor can do instead is clear what other threads reach it through under a lock, and post anything that touches a window with postToUiThread, which never waits. core/MenuModule.cpp does both. This applies to a capability package's modules as much as to this repository's.

Upstream portability bugs this build works around

Both are the same shape (a POSIX assumption in a header) and both are fixed from the command line rather than by editing React Native's tree:

  • M_PI is used seven times in react/renderer/components/view/conversions.h, to convert degrees for transform: rotate. It is a POSIX extension rather than standard C++, and MSVC's <cmath> defines it only behind _USE_MATH_DEFINES.
  • A missing <cstdint> in HttpUtils.h, and another in ReactCxxPlatform/react/runtime/ReactInstanceConfig.h, which this build force-includes around. The second appears only at React Native 0.86 on Linux: 0.87's copy of the header also includes <functional> and <memory>, which pull <cstdint> in on libstdc++, and libc++ supplies it on a Mac regardless.

docs/backlog/upstream.md carries these and the rest.

On this page