Documentation menu

React Native Setup

Build compatible native dependencies, link the Hera FFI library, and launch a registered JavaScript component.

Before configuring the native host, prepare compatible builds of React Native, Hermes, the supporting C++ libraries, and Hera FFI for the same target architecture. These dependencies meet at native boundaries, so using one toolchain environment helps keep their headers, libraries, and runtime expectations consistent.

Build Hera First

Begin with the Hera build guide to produce the Rust artifacts that the native project links against. CMake prefers static FFI linkage by default. To use a shared library explicitly, set RN_HOST_FFI_PREFER_STATIC=OFF; otherwise it looks for a neighboring static archive and fails if none is available.

Do not silently mix a new header with an older library. ABI differences can compile successfully and still corrupt message or glyph data at runtime.

Configure the Native Host

The following configures CMake inside an already prepared builder environment, using the shared debug artifact from the target build:

cmake -S /work/react-native/rn_host \
      -B /work/react-native/rn_host/build \
      -DRN_HOST_FFI_LIB=/work/target/aarch64-unknown-linux-gnu/debug/libhera_ffi.so \
      -DRN_HOST_FFI_PREFER_STATIC=OFF
cmake --build /work/react-native/rn_host/build --target rn_host

If the builder cross-compiles, pass its toolchain configuration and target dependency paths along with the FFI path. The RN_ROOT, RN_HERMES_ROOT, RN_HERMES_LIB, and library/include cache variables in CMakeLists.txt must point to compatible dependencies already built in that environment. CMake uses those artifacts rather than provisioning them.

The old react-native/build_all.sh wrapper is absent from this checkout. Use the current CMake project rather than relying on that historical path.

Register an Application Component

Create a JavaScript bundle that registers the component name passed to the host:

import React from 'react';
import {AppRegistry, Text, View} from 'react-native';

function Example() {
  return (
    <View style={{padding: 24, backgroundColor: '#ffffff'}}>
      <Text style={{fontSize: 24}}>Hello from Hera</Text>
    </View>
  );
}

AppRegistry.registerComponent('Example', () => Example);

Bundle the application with the Metro configuration for its pinned React Native tree. The registration name becomes the runtime entry point, so the next command uses --component Example to select the Example component registered above.

Launch the Host

rn_host --socket /tmp/hera.sock \
        --bundle /path/to/example.bundle.js \
        --component Example \
        --surface Example

The host requires a socket path, bundle path, and registered component name to establish the session and start the application. You can also name the connection with --client or enable transaction tracing with --trace-mount when investigating mounting behavior.

Verify the component support boundaries before assuming a platform component will work unchanged. Use verification after changing Fabric or FFI integration.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • react-native/rn_host/CMakeLists.txt
  • react-native/rn_host/src/main.cpp
  • react-native/rn_host/src/platform/core/options.h