Architecture Overview

​

Core Architecture Components

​

JavaScript Interface (JSI)

• Synchronous method invocation - Native methods can be called directly from JavaScript
• Direct memory access - JavaScript can hold references to C++ objects
• Type safety - Strong typing across the JavaScript/native boundary
• Multiple JavaScript engines - Not tied to JavaScriptCore, supports Hermes and V8

​

Fabric Renderer

• Synchronous layout - Layout can be computed synchronously on any thread
• Type-safe view updates - Strongly typed props and state
• Priority-based rendering - Support for concurrent React features
• Improved shadow tree - Immutable shadow nodes with efficient diffing

• Component registry and descriptors
• Shadow tree management
• Mounting and diffing
• Event handling

​

TurboModules

• Lazy initialization - Modules are only loaded when first accessed
• Codegen integration - Type definitions automatically generate native interfaces
• JSI-powered - Direct function calls without bridge serialization
• Better performance - Eliminates JSON serialization overhead

​

Codegen

• Single source of truth - Define APIs once in JavaScript
• Compile-time validation - Type errors caught during build
• Reduced boilerplate - Automatically generates native glue code
• Cross-platform consistency - Same interface for iOS and Android

​

Threading Model

​

JavaScript Thread

• React renders and reconciles component trees
• State updates are processed
• Event handlers execute
• Async operations are coordinated

​

UI Thread (Main Thread)

• Mounting views and applying mutations
• Processing user input
• Drawing and animation
• Native module operations that require main thread

​

Background Threads

• Layout calculation - Yoga layout engine computes flexbox layouts
• Image decoding - Image assets are decoded off the main thread
• Network requests - HTTP operations run asynchronously
• Native module work - TurboModules can specify thread requirements

​

RuntimeExecutor

using RuntimeExecutor = std::function<void(
  std::function<void(jsi::Runtime &runtime)> &&callback
)>;

​

Data Flow

1. JavaScript Render - React components render based on props and state
2. Shadow Tree Creation - Fabric creates immutable shadow nodes representing the UI
3. Layout Calculation - Yoga computes layout on background thread
4. Diffing - New shadow tree is diffed against the previous version
5. Mutation List - Changes are collected into a mounting transaction
6. UI Update - Mutations are applied to native views on the UI thread

​

Event Handling Flow

1. Native Event - User interaction occurs on the UI thread
2. Event Emission - Event is dispatched through the EventEmitter
3. Event Beat - Events are batched and synchronized with the event loop
4. JavaScript Callback - Event handler executes on JavaScript thread
5. State Update - Handler may trigger React state changes
6. Re-render - Process repeats with updated state

​

Runtime Architecture

• Task Queue - Manages execution of JavaScript tasks with priorities
• Microtask Queue - Executes promise callbacks and queueMicrotask calls
• Rendering Updates - Flushes UI updates atomically at end of event loop tick
• Long Task Monitoring - Integrates with PerformanceObserver for monitoring

​

Memory Management

​

Shadow Nodes

• Copy-on-write - Mutations create new nodes sharing unchanged subtrees
• Reference counting - Automatic memory management via std::shared_ptr
• Layout cache - Computed layouts are cached on shadow nodes

​

Runtime Shadow Node Reference Updates (RSNRU)

• Maintains references to the latest shadow node revisions
• Improves layout cache hit rates
• Keeps native state fresh across commits

​

JSI Object Lifecycle

• JavaScript values must be used on the correct thread
• jsi::Value objects are move-only for safety
• Host objects are reference-counted and can be shared

​

Build System

​

C++ Core

• CMake (Android) - Builds native C++ libraries
• CocoaPods (iOS) - Integrates C++ code into iOS apps
• Shared code - Same C++ implementation for both platforms

​

Codegen Integration

• Build-time generation - Codegen runs during native build
• Schema validation - Type definitions are validated
• Platform-specific output - Generates appropriate native bindings

​

Migration from Legacy Architecture

​

Performance Characteristics

• Startup time - TurboModules reduce initialization overhead by 30-40%
• Interaction latency - Synchronous JSI calls eliminate bridge delays
• Memory usage - Lazy loading and efficient shadow tree reduce footprint
• Frame rate - Priority-based scheduling prevents dropped frames
• List performance - Efficient diffing and mounting improve ScrollView performance

​

Developer Experience

​

Type Safety

// Define once in TypeScript/Flow
export interface Spec extends TurboModule {
  readonly getConstants: () => {initialValue: number};
  getUser(id: string): Promise<User>;
}

​

Debugging

• Synchronous errors - Stack traces are more accurate
• React DevTools - Full support for Fabric components
• JSI debugging - Native debuggers can inspect JavaScript objects
• Performance profiling - Better integration with native profilers

​

Web Alignment

• Event loop - Follows HTML specification event loop model
• Promises and microtasks - Standard JavaScript async semantics
• Web APIs - Support for MutationObserver, IntersectionObserver, etc.
• Performance APIs - PerformanceObserver for monitoring

​

Next Steps