This document provides a high-level introduction to React Native, covering its purpose, repository structure, architectural paradigms, and key components. It establishes foundational context for understanding the framework's evolution from the legacy Bridge architecture to the modern JSI/Fabric/TurboModules architecture.
For detailed information on specific subsystems:
React Native is a framework for building native mobile applications using React and JavaScript. Applications render to platform-native views (Android ViewGroup/View, iOS UIView) rather than web views. The entry point is the react-native package which exports components and APIs through packages/react-native/index.js1-444
| Characteristic | Implementation |
|---|---|
| JavaScript-Driven | Application logic in JavaScript/TypeScript, executed by Hermes or JavaScriptCore |
| Native Rendering | React components map to ViewManager classes on Android, RCTComponentView on iOS |
| Cross-Platform | Shared code in Libraries/, platform-specific in .android.js and .ios.js files |
| React Paradigm | Standard React hooks and components exported from packages/react-native/index.js32-364 |
| Native Modules | JavaScript-to-native communication via NativeModules (legacy) or TurboModuleRegistry (JSI) |
The codebase organization:
packages/react-native/Libraries/packages/react-native/ReactAndroid/packages/react-native/React/, packages/react-native/ReactApple/packages/react-native/ReactCommon/packages/react-native/scripts/Sources: packages/react-native/package.json1-230 packages/react-native/index.js1-444 package.json1-125
React Native uses Yarn workspaces defined in package.json41-44 The root package version is 1000.0.0 (development only), while published packages use 0.85.0-main versioning.
Workspace Configuration:
Package Dependencies:
| Package | Key Dependencies | Purpose |
|---|---|---|
react-native | @react-native/codegen, @react-native/gradle-plugin | Main framework, exports API |
@react-native/codegen | @babel/parser, hermes-parser | Generates native module interfaces |
@react-native/metro-babel-transformer | @react-native/babel-preset, hermes-parser | Transforms JS for Metro |
@react-native/dev-middleware | @react-native/debugger-frontend, ws | Dev server, debugging proxy |
@react-native/community-cli-plugin | @react-native/dev-middleware, metro | CLI integration |
Sources: package.json1-125 packages/react-native/package.json1-230 packages/react-native-codegen/package.json1-56 packages/community-cli-plugin/package.json1-60 packages/dev-middleware/package.json1-56
React Native's architecture consists of three main layers: the JavaScript API surface, a communication layer (Bridge or JSI), and native platform implementations. The framework supports both legacy Bridge-based and modern Bridgeless architectures simultaneously.
React Native Architecture Layers:
Key Architecture Components:
| Layer | Bridge Mode | Bridgeless Mode |
|---|---|---|
| JavaScript API | packages/react-native/index.js32-370 exports components via lazy getters | Same API surface, implementation-agnostic |
| Communication | MessageQueue serializes calls to JSON, async only | JSI provides direct C++ bindings, sync/async |
| Android Host | ReactInstanceManager ReactAndroid.api243-278 manages lifecycle | ReactHost interface ReactAndroid.api204-237 ReactHostImpl implementation |
| Android Context | BridgeReactContext ReactAndroid.api567-569 wraps bridge | BridgelessReactContext wraps JSI runtime |
| UI Management | Legacy UIManager | FabricUIManager FabricUIManager.java114-115 coordinates all UI operations |
| View Registry | ViewManagerRegistry holds ViewManager implementations | Same, but accessed via Fabric mounting layer |
Sources: packages/react-native/index.js1-370 packages/react-native/ReactAndroid/api/ReactAndroid.api1-433 packages/react-native/ReactAndroid/src/main/java/com/facebook/react/fabric/FabricUIManager.java114-246
React Native has undergone a fundamental architectural evolution from the asynchronous Bridge-based architecture to the synchronous JSI-based architecture. Both systems coexist in the current codebase to support gradual migration.
The legacy Bridge uses asynchronous message passing between JavaScript and native code through JSON serialization.
Bridge Mode Architecture:
Bridge Architecture Classes:
| Component | Android Class | Key Methods | Purpose |
|---|---|---|---|
| Instance Manager | ReactInstanceManager ReactAndroid.api243-278 | createReactContextInBackground(), attachRootView() | Manages React instance lifecycle |
| Bridge Core | CatalystInstance ReactAndroid.api575-601 | callFunction(), invokeCallback() | Routes calls between JS and native |
| Context | BridgeReactContext extends ReactContext | Provides getNativeModule() access | Runtime context with bridge reference |
| Module Registry | NativeModuleRegistry ReactAndroid.api54-59 | processPackage(), build() | Registers native modules from packages |
| Native Module | BaseJavaModule ReactAndroid.api551-565 | @ReactMethod annotated methods | Exposes native functionality to JS |
Characteristics:
Sources: packages/react-native/ReactAndroid/api/ReactAndroid.api243-601
The Bridgeless architecture eliminates the JSON bridge in favor of direct JSI (JavaScript Interface) bindings, enabling synchronous calls and zero-copy data access.
Bridgeless Mode Architecture:
Bridgeless Architecture Classes:
| Component | Android Class | Key Methods | Purpose |
|---|---|---|---|
| Host Interface | ReactHost ReactAndroid.api204-237 | start(), createSurface(), reload() | Defines bridgeless lifecycle contract |
| Host Implementation | ReactHostImpl (internal) | Implements ReactHost interface | Manages JSI runtime and surfaces |
| Context | BridgelessReactContext | Provides TurboModule access | Runtime context with JSI reference |
| Default Host | DefaultReactHost DefaultReactHost.kt36-113 | getDefaultReactHost() | Factory for creating ReactHost instances |
| TurboModule Manager | ReactPackageTurboModuleManagerDelegate ReactAndroid.api349-366 | getModule(), getLegacyModule() | Manages TurboModule lifecycle |
| Surface | ReactSurface interface | start(), stop() | Represents a React rendering surface |
Characteristics:
Sources: packages/react-native/ReactAndroid/api/ReactAndroid.api204-366 packages/react-native/ReactAndroid/src/main/java/com/facebook/react/defaults/DefaultReactHost.kt36-113
Application Integration:
The ReactDelegate ReactAndroid.api131-159 class provides a unified interface that can work with either:
ReactNativeHost for Bridge mode ReactAndroid.api316-341ReactHost for Bridgeless mode ReactAndroid.api204-237Applications can switch between modes by providing the appropriate host implementation to ReactActivityDelegate ReactAndroid.api89-124
Sources: packages/react-native/ReactAndroid/api/ReactAndroid.api61-341
React Native has undergone a fundamental architectural evolution from the asynchronous Bridge-based architecture to the synchronous JSI-based architecture. Both systems coexist in the current codebase to support gradual migration.
Legacy Bridge Call Flow:
Legacy Bridge Characteristics:
| Aspect | Implementation |
|---|---|
| JS → Native | NativeModules.[ModuleName].<FileRef file-url="https://github.com/facebook/react-native/blob/352d73be/method" undefined file-path="method">Hii</FileRef> → MessageQueue → JSON → native |
| Native → JS | Callback IDs in queue, invoked with result data |
| Threading | JS thread (JSContext) separate from native UI thread |
| Type Safety | Runtime checks only, no compile-time validation |
| Entry Points | JS: Libraries/BatchedBridge/NativeModules.js, Android: CatalystInstance, iOS: RCTBridge |
| Performance | JSON serialization overhead, async-only calls |
Code References:
Libraries/BatchedBridge/MessageQueue.jsLibraries/BatchedBridge/NativeModules.jsReactAndroid/src/main/java/com/facebook/react/bridge/CatalystInstance.javaReact/Base/RCTBridge.h, React/CxxBridge/RCTCxxBridge.mmSources: packages/react-native/index.js269-271
JSI/TurboModule Call Flow:
JSI Architecture Characteristics:
| Aspect | Implementation |
|---|---|
| JS → Native | Direct C++ function call via jsi::HostObject, no serialization |
| Native → JS | Synchronous returns or jsi::Function callbacks |
| Threading | Can call synchronously from JS thread with proper locking |
| Type Safety | Codegen generates C++ headers from Flow/TypeScript specs |
| Code Generation | @react-native/codegen → .h files implementing TurboModule base |
| Performance | Zero-copy data access, direct memory manipulation |
Code References:
ReactCommon/jsi/jsi/jsi.h (C++ abstract interface)Libraries/TurboModule/TurboModuleRegistry.js (JS), ReactCommon/react/nativemodule/core/ (C++)ReactCodegen/ directoryReactAndroid/src/main/java/com/facebook/react/turbomodule/ReactApple/React/CoreModules/Sources: packages/react-native/index.js331-333 packages/react-native/package.json161-169 packages/react-native-codegen/package.json1-56
Fabric is React Native's new rendering system that works in conjunction with the Bridgeless architecture. It replaces the legacy UIManager with a C++-based renderer that directly manipulates the shadow tree.
Fabric Rendering Flow:
Fabric Key Classes:
| Component | Class | Responsibility |
|---|---|---|
| UI Coordinator | FabricUIManager FabricUIManager.java114-115 | Central coordinator for all UI operations in Fabric |
| Mount Dispatcher | MountItemDispatcher FabricUIManager.java179 | Queues and dispatches mount operations |
| Mount Executor | MountingManager FabricUIManager.java177 | Executes view operations on UI thread |
| Surface Manager | SurfaceMountingManager FabricUIManager.java486-498 | Manages one React root surface |
| View Registry | ViewManagerRegistry FabricUIManager.java180 | Maps component names to ViewManagers |
| Component Example | ReactScrollViewManager ReactScrollViewManager.kt54-68 | ViewManager for ScrollView component |
Fabric Benefits:
Sources: packages/react-native/ReactAndroid/src/main/java/com/facebook/react/fabric/FabricUIManager.java114-246 packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactScrollViewManager.kt54-68
React Native supports two JavaScript engines, with Hermes as the default for production builds.
| Engine | Implementation | Configuration |
|---|---|---|
| Hermes | Bytecode-compiled engine, optimized for React Native | Versions in sdks/.hermesversion, sdks/.hermesv1version |
| JavaScriptCore | WebKit's JS engine (system-provided on iOS) | Fallback/development mode |
Runtime Initialization:
The JavaScript environment is set up through polyfills and core modules:
Polyfills and Initialization:
@react-native/js-polyfills/console.js provides console.log, console.warn, etc.@react-native/js-polyfills/error-guard.js wraps callbacks with error boundariesrn-get-polyfills.jsHermes Configuration:
android.enableHermes in Gradlehermes_enabled flaghermes-compiler package dependency in react-nativeSources: packages/polyfills/package.json1-33 packages/react-native/package.json178 packages/react-native/rn-get-polyfills.js1-14
React Native components map directly to native platform views through the ViewManager system. Components defined in JavaScript are instantiated as native views by platform-specific ViewManager implementations.
Component-to-Native Mapping:
Core Components and Their Native Implementations:
| JavaScript Component | Android ViewManager | Android View | Key Features |
|---|---|---|---|
ScrollView | ReactScrollViewManager ReactScrollViewManager.kt54-68 | ReactScrollView ReactScrollView.java78-89 | Vertical scrolling, snap-to-interval, pull-to-refresh |
HorizontalScrollView | ReactHorizontalScrollViewManager ReactHorizontalScrollViewManager.kt48-68 | ReactHorizontalScrollView ReactHorizontalScrollView.java74-85 | Horizontal scrolling, paging |
Text | ReactTextViewManager | ReactTextView ReactTextView.java60-84 | Styled text, nested text, selectable |
Image | ReactImageManager ReactImageManager.kt33-40 | ReactImageView | Remote/local images, Fresco integration |
View | ViewManager (base class) | Platform View/ViewGroup | Base container component |
ViewManager Lifecycle:
ViewManager classes handle the complete lifecycle of native views:
createViewInstance(ThemedReactContext) instantiates the native view@ReactProp annotated methods receive prop updates@ReactMethod methods handle imperative commands from JSEventDispatcherprepareToRecycleView() resets view state for reuse (Fabric optimization)Example ViewManager Methods:
Sources: packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactScrollView.java70-154 packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/scroll/ReactScrollViewManager.kt54-196 packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/text/ReactTextView.java60-103 packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/image/ReactImageManager.kt33-99
The react-native package (packages/react-native/) serves as the primary export and contains:
Libraries/)ReactAndroid/)React/, ReactApple/)ReactCommon/)scripts/)Entry Point: index.js exports the public API surface.
Sources: packages/react-native/package.json1-230
The @react-native/codegen package generates type-safe native interfaces from Flow/TypeScript specifications.
Process:
Configuration: codegenConfig in package.json defines generation targets.
Sources: packages/react-native-codegen/package.json1-56 packages/babel-plugin-codegen/package.json1-34
| Package | Purpose |
|---|---|
@react-native/metro-babel-transformer | Transforms JavaScript for Metro bundler |
@react-native/babel-preset | Babel configuration with React Native plugins |
@react-native/metro-config | Default Metro bundler configuration |
@react-native/gradle-plugin | Gradle plugin for Android builds |
Metro Configuration: packages/metro-config/src/index.flow.js defines resolver settings, transformation options, and polyfill injection.
Sources: packages/react-native-babel-transformer/package.json1-37 packages/react-native-babel-preset/package.json1-65 packages/metro-config/src/index.flow.js54-110
| Package | Purpose |
|---|---|
@react-native/dev-middleware | HTTP server for debugging, proxies Chrome DevTools Protocol |
@react-native/debugger-frontend | Chrome DevTools UI for React Native |
The development server runs on port 8081 (configurable via RCT_METRO_PORT environment variable) and provides:
Sources: packages/metro-config/src/index.flow.js74-76 packages/debugger-frontend/package.json1-25
| Package | Purpose |
|---|---|
@react-native/js-polyfills | JavaScript polyfills (console, error guard) |
@react-native/assets-registry | Asset management system |
@react-native/normalize-colors | Color normalization utilities |
@react-native/virtualized-lists | Optimized list components |
Sources: packages/polyfills/package.json1-33 packages/assets/package.json1-31 packages/normalize-color/package.json1-27
React Native uses Flow for internal type checking and provides TypeScript definitions for public APIs.
The repository uses Flow ^0.294.0 with strict mode enabled. Key configuration:
index.js.flow, type definitions in flow/ and flow-typed/.ios and .android extensionsSources: .flowconfig1-101
Public API types are exported from:
types/ - Legacy TypeScript definitionstypes_generated/ - Generated from Flow via code generationreact-native-strict-api - Strict API export conditionConditional Exports: The package.json uses export conditions to provide strict vs. legacy types:
Sources: packages/react-native/package.json31-69 packages/react-native/types/__typetests__/index.tsx1-1500
React Native provides integrated development and debugging tools accessible through the development server.
Development Server Stack:
Development Commands (from root package.json):
| Command | Purpose | Implementation |
|---|---|---|
yarn start | Start Metro bundler | Runs packages/rn-tester start |
yarn android | Build and run Android | Runs packages/rn-tester android |
yarn build | Build all packages | scripts/build/build.js |
yarn test | Run Jest tests | Jest with custom config |
yarn lint | ESLint all files | eslint --max-warnings 0 . |
yarn flow-check | Flow type checking | flow check |
| Tool | Configuration | Purpose |
|---|---|---|
| Jest | jest-preset.js in react-native | JavaScript unit tests |
| ESLint | @react-native/eslint-config | JS/TS linting |
| Flow | .flowconfig (strict mode) | Type checking (internal) |
| TypeScript | types/tsconfig.json | Type checking (public API) |
| Prettier | Version 3.6.2 | Code formatting |
| clang-format | Version 1.8.0 | C++ formatting |
| ktfmt | Gradle plugin | Kotlin formatting |
Sources: package.json7-39 packages/dev-middleware/package.json1-56 packages/community-cli-plugin/package.json1-60 packages/eslint-config-react-native/package.json1-48
React Native uses a coordinated versioning system across all packages in the monorepo.
| Component | Version | Purpose |
|---|---|---|
Root package (package.json) | 1000.0.0 | Development only, not published |
| Published packages | 0.85.0-main | Synchronized across all @react-native/* packages |
| Release branches | 0.73-stable, 0.74-stable, etc. | Stable release lines |
Android Build:
packages/react-native/build.gradle.kts.so libraries.aar) published to MaveniOS Build:
packages/react-native/React-Core.podspecscripts/react_native_pods.rb with use_react_native! functionJavaScript Build:
@react-native/metro-babel-transformer@react-native/metro-config@react-native/codegen generates native interfaces at build timeScripts in scripts/releases/:
set-version.js - Updates version across all packagestrigger-react-native-release.js - Initiates release workflowSources: package.json1-125 packages/react-native/package.json1-230 packages/react-native/package.json76-79
React Native is a comprehensive framework consisting of:
The framework continues to evolve with the new architecture (JSI/Fabric/TurboModules) becoming the recommended approach while maintaining backward compatibility with the legacy Bridge architecture.
Sources: package.json1-128 packages/react-native/package.json1-230 .flowconfig1-101 CHANGELOG.md1-194
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.