What Is the ReactCommon Directory in React Native? A Deep Dive into the Cross-Platform C++ Core

The ReactCommon directory houses the cross-platform C++ core of React Native, providing shared infrastructure—including the JavaScript runtime executor, TurboModules system, Yoga layout engine, and renderer scheduler—that powers both iOS and Android from a single unified codebase.

The facebook/react-native repository organizes its native code into platform-specific directories like ReactAndroid and ReactApple, but the heavy lifting happens in ReactCommon. This directory contains the cross-platform C++ core that enables React Native to maintain feature parity across platforms while minimizing code duplication. Any code that must run on both iOS and Android (and future platforms) lives here, while platform-specific UI layers contain only thin glue code bridging this core to native view systems.

ReactCommon: The Shared Engine of React Native

ReactCommon serves as the platform-agnostic engine that abstracts away OS-specific details. According to the React Native source code, this directory aggregates reusable building blocks that power the entire stack independent of any particular host UI toolkit. By centralizing core logic in C++, the team ensures that critical systems—ranging from JavaScript execution to layout calculations—behave identically across all supported platforms.

Key Components and Responsibilities

Runtime Execution and Threading

The RuntimeExecutor system, defined in runtimeexecutor/ReactCommon/RuntimeExecutor.h, provides a thread-safe wrapper that lets native code schedule work on the JavaScript engine without holding a direct jsi::Runtime* pointer. This abstraction prevents threading issues when C++ code needs to interact with the JS runtime from background threads.

Dependency Injection

ContextContainer, located in react/utils/ContextContainer.h, acts as a simple dependency injection container for sharing objects across the C++ codebase. It stores and retrieves shared instances—such as configuration objects, bridge references, and module registries—allowing different parts of the core to access common resources without tight coupling.

TurboModules Infrastructure

The TurboModules system defines its abstract APIs and binding helpers in react/nativemodule/core/ReactCommon/TurboModule.h. This directory contains the platform-agnostic implementation of the TurboModule system, which provides high-performance native modules by bypassing the legacy bridge and using direct JSI (JavaScript Interface) calls.

Layout Engine (Yoga)

Yoga, Facebook’s cross-platform Flexbox implementation, lives in yoga/yoga/Yoga.h. This C++ library handles all layout calculations for React Native components, ensuring that flexbox behavior remains consistent between iOS and Android. The Yoga engine computes shadow node layouts before they are mounted to native views.

Renderer and Scheduler

The new React renderer’s core data structures—including shadow nodes, schedulers, and animation backends—reside in files like react/renderer/scheduler/Scheduler.h. These utilities are independent of the host UI framework and manage the reconciliation and commit phases of the React component lifecycle.

Logging and Diagnostics

Centralized logging utilities in logger/react_native_log.h provide platform-agnostic diagnostic helpers used by both iOS and Android. Additionally, performance tracing tools like react/performance/cdpmetrics/CdpMetricsReporter.h collect metrics for debugging and optimization across platforms.

Platform-Agnostic Helpers

Miscellaneous utilities such as MapBuilder (in react/common/MapBuilder.h), SystemClock, and SurfaceDelegate provide low-level abstractions for common operations that work identically across operating systems.

Practical Code Examples

Scheduling Work on the JavaScript Thread with RuntimeExecutor

// Obtain a RuntimeExecutor from the bridge (provided by the host app)
facebook::react::RuntimeExecutor runtimeExecutor = ...;

// Schedule a lambda that receives a mutable jsi::Runtime reference
runtimeExecutor([&](jsi::Runtime &jsiRuntime) {
  // Safe to interact with the JS runtime here
  jsiRuntime.global()
      .getPropertyAsFunction(jsiRuntime, "console")
      .call(jsiRuntime, "log", "Hello from native!");
});

Source: [RuntimeExecutor.h](https://github.com/facebook/react-native/blob/main/packages/react-native/ReactCommon/runtimeexecutor/ReactCommon/RuntimeExecutor.h)

Registering a Shared Object in ContextContainer

facebook::react::ContextContainer context;

// Register a config object that can be fetched later from any component
std::shared_ptr<const ReactNativeConfig> config = ...;
context.insert("ReactNativeConfig", config);

// Somewhere else in the code base:
auto retrievedConfig = context.at<std::shared_ptr<const ReactNativeConfig>>(
    "ReactNativeConfig");

Source: [ContextContainer.h](https://github.com/facebook/react-native/blob/main/packages/react-native/ReactCommon/react/utils/ContextContainer.h)

Using Yoga for Layout Calculations

#include <yoga/Yoga.h>

YGNodeRef root = YGNodeNew();
YGNodeStyleSetFlexDirection(root, YGFlexDirectionRow);
YGNodeStyleSetWidth(root, 300);
YGNodeStyleSetHeight(root, 200);

// Add a child node
YGNodeRef child = YGNodeNew();
YGNodeStyleSetFlexGrow(child, 1);
YGNodeInsertChild(root, child, 0);

// Compute layout
YGNodeCalculateLayout(root, YGUndefined, YGUndefined, YGDirectionLTR);

// Inspect the result
float childWidth = YGNodeLayoutGetWidth(child);
float childHeight = YGNodeLayoutGetHeight(child);

Source: [Yoga.h](https://github.com/facebook/react-native/blob/main/packages/react-native/ReactCommon/yoga/yoga/Yoga.h)

Declaring a TurboModule in C++

#include <ReactCommon/TurboModule.h>

class MyTurboModule : public facebook::react::TurboModule {
 public:
  MyTurboModule(const std::shared_ptr<CallInvoker> &jsInvoker)
      : facebook::react::TurboModule("MyTurboModule", jsInvoker) {}

  // Example method exposed to JS
  jsi::Value getDeviceInfo(jsi::Runtime &rt, const jsi::Value *args, size_t count) {
    return jsi::String::createFromUtf8(rt, "React Native Device");
  }
};

Source: [TurboModule.h](https://github.com/facebook/react-native/blob/main/packages/react-native/ReactCommon/react/nativemodule/core/ReactCommon/TurboModule.h)

Benefits of the ReactCommon Architecture

By centralizing core logic in the ReactCommon directory, the React Native team achieves several engineering advantages:

• Write once, compile everywhere – The same C++ codebase compiles to *.a/*.framework for iOS and .so for Android, eliminating duplicate implementations.
• Feature parity – New renderer or TurboModule features added once in ReactCommon automatically become available on all platforms.
• Reduced binary size and maintenance – No duplicated implementations across platform folders means smaller bundles and fewer bugs.
• Alternative host environments – The same core powers the new bridgeless mode, experimental Web targets, and other future runtimes without rewriting core logic.

Summary

• The ReactCommon directory is the cross-platform C++ core of React Native, distinct from platform-specific folders like ReactAndroid and ReactApple.
• It provides critical infrastructure including the RuntimeExecutor for thread-safe JS scheduling, ContextContainer for dependency injection, and TurboModule abstractions for high-performance native modules.
• Yoga, the Flexbox layout engine, lives here alongside the React renderer's Scheduler and shadow node system.
• Centralizing these components in C++ ensures consistent behavior, reduces duplication, and enables the New Architecture features across iOS and Android.

Frequently Asked Questions

What is the difference between ReactCommon and ReactAndroid/ReactApple?

ReactCommon contains platform-agnostic C++ code that runs on both iOS and Android, while ReactAndroid and ReactApple contain thin platform-specific glue code written in Java/Kotlin or Objective-C/C++. The platform folders handle native view mounting and OS-specific APIs, but delegate core logic to ReactCommon.

Can developers write custom TurboModules using ReactCommon?

Yes. Developers can implement custom TurboModules by creating C++ classes that inherit from facebook::react::TurboModule (defined in react/nativemodule/core/ReactCommon/TurboModule.h) and exposing methods using JSI (JavaScript Interface). This allows high-performance native modules that bypass the legacy bridge entirely.

Is Yoga only used for React Native?

No. While Yoga lives in the ReactCommon directory and powers React Native's layout system, it is a standalone cross-platform Flexbox implementation. It can be used independently in other C++ projects or platforms requiring consistent Flexbox layout calculations outside of React Native.

How does ReactCommon support the New Architecture (Bridgeless mode)?

ReactCommon provides the foundational C++ infrastructure that enables the New Architecture. The RuntimeExecutor, TurboModule system, and Fabric renderer (scheduler and shadow nodes) all reside here. In bridgeless mode, these components communicate directly via JSI without the asynchronous bridge, and ReactCommon supplies the platform-agnostic implementations that make this possible on both iOS and Android.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}