# React Native New Architecture + Native Modules (Scale) — AI Agent Guidelines & Architecture Rules > Rules for a large React Native app on the New Architecture: Expo dev client or bare, Expo Modules API and Turbo Modules for native code, a generated API client, performance budgets and staged releases. > Technologies: React Native, Expo, TypeScript, Swift, Kotlin --- ## AGENTS.md ```markdown # Project Architecture & Guidelines (React Native New Architecture at Scale) ## 1. System Architecture - **Runtime**: React Native 0.87 on the New Architecture (Fabric, Turbo Modules, bridgeless) with Hermes. On Expo, SDK 57 with a custom dev client; the New Architecture cannot be turned off from SDK 55 on. - **Navigation**: Expo Router or React Navigation, typed routes, deep links that match the web URLs. - **Native code**: Expo Modules API (Swift and Kotlin) for new modules; Turbo Modules with Codegen specs where a module must be framework-agnostic. Native changes go through config plugins, not hand-edited `ios/` and `android/` folders, unless the project is bare. - **Data**: The product API through a client generated from its OpenAPI document; TanStack Query for server state; MMKV for small local state. - **Releases**: EAS Build or your own CI, staged rollouts in both stores, OTA updates for JavaScript-only fixes. ## 2. File Layout - `app/` or `src/screens/`: Routes and screens only. - `src/features//`: Hooks, components and tests for one product area. - `modules//`: One native module each: `index.ts` (the typed interface), `ios/`, `android/`, and a test harness screen. - `packages/api-client/`: Generated from the API's OpenAPI document; never edited by hand. ## 3. Native Module Rules - Profile before writing native code. A module needs a measured reason: a startup, scroll or memory number that JavaScript cannot meet. - One TypeScript interface per module, written first. Implement iOS and Android against it one at a time. - Modules expose async functions and events, not shared mutable state. Heavy work runs off the JS and UI threads. - Every module has an owner per platform, listed in `CODEOWNERS`. ## 4. Performance & Reliability - Budgets in CI: cold start time, JS bundle size, and scroll frame drops on a reference list screen. A PR that breaks a budget fails. - Lists use FlashList; images use `expo-image` with caching. - Crash and ANR rates are tracked per release; staged rollouts halt automatically above a threshold. ## 5. Coding Standards - Strict TypeScript, zero `any`. API types come only from the generated client. - No business logic in native modules; they are adapters to platform capabilities. - Feature flags over long-lived branches or forks for platform-specific behaviour. ## 6. Testing Conventions - Jest and React Native Testing Library for components and hooks. - Maestro (or Detox) flows on a device farm for the flows that make money, on every release candidate. - Native modules have unit tests on each platform (XCTest or Swift Testing, JUnit) plus one integration flow through the JS interface. ## 7. Git Workflow & PR Conventions - Conventional Commits scoped to the feature or module: `perf(feed): native image prefetch module`. - A PR that adds a native module includes the profiling numbers that justified it. - Native changes need a new binary; label them so release managers know OTA is not enough. ``` --- ## CLAUDE.md ```markdown # CLAUDE.md — React Native New Architecture Commands & Conventions > Claude Code also reads `AGENTS.md` when no `CLAUDE.md` is present — keep this file for Claude-specific directives. ## Common Commands - `npx expo start --dev-client` - Start against the custom dev client - `npx expo prebuild --clean` - Regenerate native projects from config plugins (managed projects) - `npm test` - Jest unit and component tests - `maestro test maestro/` - Device flows - `npm run api:generate` - Regenerate `packages/api-client` from the API's OpenAPI document ## Code Style Guidelines - Do not write native code without a profiling result that justifies it. - Write the module's TypeScript interface first; implement one platform at a time. - Never edit `packages/api-client` by hand. ``` --- ## .cursor/rules/stack.mdc ```markdown --- description: React Native New Architecture app with native modules at scale globs: ["app/**/*.tsx", "src/**/*.ts", "src/**/*.tsx", "modules/**/*"] alwaysApply: true --- # React Native New Architecture at Scale - RN 0.87, New Architecture only (Fabric, Turbo Modules, bridgeless), Hermes. Expo SDK 57 dev client or bare. - Native code via Expo Modules API or Turbo Modules with Codegen; one TS interface per module, written first. - Profile before native code; budgets for startup, bundle size and scroll in CI. - Generated API client only; TanStack Query for server state; FlashList and expo-image. - Staged rollouts with automatic halt on crash rate. ``` --- ## Architecture Overview & Best Practices ## Architecture Overview Guidelines for a **large React Native app** on the **New Architecture**: a shared TypeScript layer for most of the product, **native modules** in Swift and Kotlin only where profiling demands them, a **generated API client**, and **staged releases** with performance budgets. ### Key Advantages - **The agent stays in TypeScript**: native code is isolated behind typed interfaces it can implement one platform at a time. - **Measured native code**: every module has a profiling number behind it, so the native surface stays small. - **Safe releases**: budgets in CI and staged rollouts catch regressions before most users see them.