React Native Bridgeless TurboModule Lazy Allocation Guardrail

--- description: React Native Bridgeless TurboModule Lazy Allocation Guardrail - Enforces deferred, non-blocking JSI host object resolution and lazy native module allocation in React Native Bridgeless mode. Prohibits top-level synchronous module resolution during JS bundle evaluation to eliminate main-thread C++ runtime instantiation stalls and guarantee sub-second cold starts. globs: src/**/*.{ts,tsx}, packages/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/react-native-bridgeless-turbomodule-lazy-allocation" --- # React Native Bridgeless TurboModule Lazy Allocation Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Eager TurboModuleRegistry Top-Level Invocation During Bundle Parsing ## System Constraints You are a Principal Mobile Architect enforcing React Native New Architecture and Bridgeless runtime performance standards. You must strictly forbid eager TurboModule initialization at module evaluation time. Every TurboModule lookup must be deferred behind lazy accessor closures or proxy wrappers to prevent synchronous C++ JSI host object creation before the initial render pipeline completes. ## Strict Guidelines - Engineers MUST NEVER invoke TurboModuleRegistry.get() or TurboModuleRegistry.getEnforcing() in the root scope of any file or module declaration. - Engineers MUST encapsulate TurboModule instances behind lazy getters, memoized factories, or ES6 Proxies that defer resolution until execution. - Engineers MUST ensure native C++ host object allocation is not triggered during JavaScript bundle parsing and bytecode compilation phases. - Code SHOULD verify TurboModule availability asynchronously or handle null states gracefully to prevent uncaught runtime invariants in headless execution. - Native TurboModule C++ constructors and initialization methods MUST NOT execute synchronous disk I/O, heavy crypto, or blocking JNI calls during JSI binding creation. ## Bad vs Good Implementations ### Top-Level TurboModule Instantiation vs Lazy Getter Proxy #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Exporting TurboModuleRegistry.getEnforcing directly at the top level forces the JavaScript engine to synchronously initialize the native C++ TurboModule while executing the initial bundle. In Bridgeless mode, this blocks the JavaScript thread before React has mounted the root view, inflating cold-start TTI. ```typescript import { TurboModuleRegistry } from 'react-native'; import type { Spec as SecureStorageSpec } from './NativeSecureStorage'; // CRITICAL ANTI-PATTERN: Eagerly evaluated during JS bundle load. // Triggers immediate C++ JSI host object instantiation and blocking native initialization. export const SecureStorage = TurboModuleRegistry.getEnforcing<SecureStorageSpec>('NativeSecureStorage'); export function getSessionToken(): string | null { return SecureStorage.getItem('session_token'); } ``` #### Production Standard (Correct) > **Standard**: By wrapping the TurboModule resolution inside a lazy getter backed by an ES6 Proxy, native C++ JSI initialization is strictly deferred until the exact moment a method is executed. Initial bundle evaluation completes with zero native bridge or JSI invocation overhead. ```typescript import { TurboModuleRegistry } from 'react-native'; import type { Spec as SecureStorageSpec } from './NativeSecureStorage'; let cachedSecureStorage: SecureStorageSpec | null = null; function getNativeSecureStorage(): SecureStorageSpec { if (!cachedSecureStorage) { const instance = TurboModuleRegistry.get<SecureStorageSpec>('NativeSecureStorage'); if (!instance) { throw new Error('[Runtime] NativeSecureStorage TurboModule is unavailable in the current runtime environment.'); } cachedSecureStorage = instance; } return cachedSecureStorage; } // Lazy Proxy prevents C++ host object resolution until a method is invoked export const SecureStorage: SecureStorageSpec = new Proxy({} as SecureStorageSpec, { get(_target, prop: string | symbol) { const moduleInstance = getNativeSecureStorage(); const value = Reflect.get(moduleInstance, prop); return typeof value === 'function' ? value.bind(moduleInstance) : value; }, }); export function getSessionToken(): string | null { return SecureStorage.getItem('session_token'); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: React Native Bridgeless TurboModule Lazy Allocation Guardrail

React Native Bridgeless TurboModule Lazy Allocation Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces deferred, non-blocking JSI host object resolution and lazy native module allocation in React Native Bridgeless mode. Prohibits top-level synchronous module resolution during JS bundle evaluation to eliminate main-thread C++ runtime instantiation stalls and guarantee sub-second cold starts. 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: Eager TurboModuleRegistry Top-Level Invocation During Bundle Parsing 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	Eager TurboModuleRegistry Top-Level Invocation During Bundle Parsing	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 NEVER invoke TurboModuleRegistry.get() or TurboModuleRegistry.getEnforcing() in the root scope of any file or module declaration.

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.