---
name: react-native-new-architecture
description: "Use when building, refactoring, or reviewing a React Native New Architecture + Native Modules (Scale) project (React Native, Expo, TypeScript, Swift, Kotlin). 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."
license: MIT
metadata:
  source: https://stackitfast.com/rules/react-native-new-architecture
  version: "2026-10-04"
---

# React Native New Architecture + Native Modules (Scale) — Agent Skill

## When to use this skill
- Any task that scaffolds, modifies, refactors, or reviews code in a React Native New Architecture + Native Modules (Scale) codebase.
- Whenever the project depends on React Native, Expo, TypeScript, Swift, Kotlin.
- Apply these guidelines before proposing architecture, database, or deployment changes.

## Guidelines
# 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/<domain>/`: Hooks, components and tests for one product area.
- `modules/<name>/`: 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.

## Source
Maintained at https://stackitfast.com/rules/react-native-new-architecture — also available as AGENTS.md, CLAUDE.md, and Cursor .mdc.