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_expectin 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_PIis used seven times inreact/renderer/components/view/conversions.h, to convert degrees fortransform: rotate. It is a POSIX extension rather than standard C++, and MSVC's<cmath>defines it only behind_USE_MATH_DEFINES.- A missing
<cstdint>inHttpUtils.h, and another inReactCxxPlatform/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.