React Native 0.76+ Bridgeless TurboModule Specification and Thread-Safety Standard

--- description: React Native 0.76+ Bridgeless TurboModule Specification and Thread-Safety Standard - Enforces strict Codegen-backed TurboModule contracts in React Native 0.76+ New Architecture with Bridgeless Mode enabled. Prohibits legacy NativeModules bridge invocations, uncontrolled synchronous JSI execution on the main UI/Fabric render pipeline, and non-thread-safe C++ mutable state across JavaScript and native runtime threads. globs: src/**/*.{ts,tsx}, specs/**/*.{ts,tsx}, android/app/src/main/jni/**/*.{cpp,h}, ios/**/*.{mm,h} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-native-076-bridgeless-turbomodules" --- # React Native 0.76+ Bridgeless TurboModule Specification and Thread-Safety Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Invoking legacy NativeModules bridge or running blocking synchronous JSI methods on the Fabric UI commit path. ## System Constraints You are a Principal Software Architect enforcing React Native 0.76+ Bridgeless Architecture standards. In React Native 0.76+, Bridgeless mode is enabled by default, permanently deprecating NativeModules, bridge delegates, and uncontrolled JSI global injections. You must ensure all native interactions declare formal React Native Codegen specs using TurboModuleRegistry, maintain strict Fabric UI thread isolation, and prevent blocking synchronous JSI executions on render threads. ## Strict Guidelines - Engineers MUST ALWAYS define TurboModules using React Native Codegen specifications extending TurboModuleRegistry.Spec. - Engineers MUST NOT import or invoke NativeModules from 'react-native', as Bridgeless mode does not initialize the legacy asynchronous JSON-RPC C++ bridge. - Code MUST offload expensive calculations to background queues (GCD queues on iOS, ExecutorService on Android) before resolving JSI HostFunction Promises. - Services MUST NEVER invoke synchronous JSI HostFunctions directly inside high-frequency Fabric rendering or layout measurement cycles without strict microsecond execution guarantees. - Components NEVER access JSI runtime globals directly from window/globalThis; all cross-boundary interactions must be encapsulated behind typed TurboModule interfaces. ## Bad vs Good Implementations ### TurboModule Codegen Specification vs Legacy NativeModules #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accessing NativeModules bypasses React Native Codegen, relies on the disabled legacy bridge in 0.76 Bridgeless mode, and lacks compile-time type verification across the JSI boundary. ```typescript import { NativeModules } from 'react-native'; // Legacy async bridge call; fails or degrades runtime in RN 0.76 Bridgeless mode export const getDeviceEntropy = async (): Promise<string> => { const { SecureEntropyModule } = NativeModules; if (!SecureEntropyModule) { throw new Error('SecureEntropyModule not linked'); } return await SecureEntropyModule.generateEntropy(); }; ``` #### Production Standard (Correct) > **Standard**: Uses TurboModuleRegistry with Codegen interface specification, enabling zero-bridge direct C++ JSI host object binding with static compile-time type generation. ```typescript import type { TurboModule } from 'react-native'; import { TurboModuleRegistry } from 'react-native'; export interface Spec extends TurboModule { generateEntropy(): Promise<string>; getSyncSalt(): string; } export default TurboModuleRegistry.getEnforcing<Spec>('SecureEntropyModule'); ``` ### Thread-Safe Async Native Work vs Blocking Main Thread JSI Execution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling synchronous native methods executing heavy operations directly stalls the JavaScript/Fabric UI pipeline, violating React 18/19 concurrent rendering guarantees. ```typescript // Executing heavy cryptographic or disk I/O synchronously on the JSI thread import SecureEntropyModule from './NativeSecureEntropyModule'; export function deriveSessionKey(): string { // Anti-pattern: Blocking synchronous call stalls Fabric UI frame budget return SecureEntropyModule.getSyncSalt(); } ``` #### Production Standard (Correct) > **Standard**: Asynchronous TurboModule methods execute asynchronously, dispatching compute to native thread pools while preserving 60/120fps UI frame budgets on the Fabric render thread. ```typescript // Offloading workload asynchronously via TurboModule Promise contract import SecureEntropyModule from './NativeSecureEntropyModule'; export async function deriveSessionKey(): Promise<string> { // Concurrently resolves on native background thread without stalling Fabric UI commit const entropy = await SecureEntropyModule.generateEntropy(); return entropy; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native 0.76+ Bridgeless TurboModule Specification and Thread-Safety Standard

React Native 0.76+ Bridgeless TurboModule Specification and Thread-Safety Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict Codegen-backed TurboModule contracts in React Native 0.76+ New Architecture with Bridgeless Mode enabled. Prohibits legacy NativeModules bridge invocations, uncontrolled synchronous JSI execution on the main UI/Fabric render pipeline, and non-thread-safe C++ mutable state across JavaScript and native runtime threads. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Invoking legacy NativeModules bridge or running blocking synchronous JSI methods on the Fabric UI commit path. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Invoking legacy NativeModules bridge or running blocking synchronous JSI methods on the Fabric UI commit path.	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS define TurboModules using React Native Codegen specifications extending TurboModuleRegistry.Spec.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.