React Native New Architecture + Native Modules (Scale)

Curated rule Mobile App Updated Oct 2026 Which file does my tool read?

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.

React Native Expo TypeScript Swift Kotlin

Formats: 4 files
AGENTS.md: 40 lines
CLAUDE.md: 15 lines
Languages: TypeScript, Swift, Kotlin
Updated: Oct 2026
Used by: 4 projects

Install

Writes .claude/skills/react-native-new-architecture/SKILL.md

$ curl -s --create-dirs -o .claude/skills/react-native-new-architecture/SKILL.md https://stackitfast.com/rules/react-native-new-architecture/SKILL.md

Rule files

AGENTS.md· 40 lines · 2.9 KB

1	# Project Architecture & Guidelines (React Native New Architecture at Scale)
2
3	## 1. System Architecture
4	- 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.
5	- Navigation: Expo Router or React Navigation, typed routes, deep links that match the web URLs.
6	- 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.
7	- Data: The product API through a client generated from its OpenAPI document; TanStack Query for server state; MMKV for small local state.
8	- Releases: EAS Build or your own CI, staged rollouts in both stores, OTA updates for JavaScript-only fixes.
9
10	## 2. File Layout
11	- `app/` or `src/screens/`: Routes and screens only.
12	- `src/features/<domain>/`: Hooks, components and tests for one product area.
13	- `modules/<name>/`: One native module each: `index.ts` (the typed interface), `ios/`, `android/`, and a test harness screen.
14	- `packages/api-client/`: Generated from the API's OpenAPI document; never edited by hand.
15
16	## 3. Native Module Rules
17	- Profile before writing native code. A module needs a measured reason: a startup, scroll or memory number that JavaScript cannot meet.
18	- One TypeScript interface per module, written first. Implement iOS and Android against it one at a time.
19	- Modules expose async functions and events, not shared mutable state. Heavy work runs off the JS and UI threads.
20	- Every module has an owner per platform, listed in `CODEOWNERS`.
21
22	## 4. Performance & Reliability
23	- 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.
24	- Lists use FlashList; images use `expo-image` with caching.
25	- Crash and ANR rates are tracked per release; staged rollouts halt automatically above a threshold.
26
27	## 5. Coding Standards
28	- Strict TypeScript, zero `any`. API types come only from the generated client.
29	- No business logic in native modules; they are adapters to platform capabilities.
30	- Feature flags over long-lived branches or forks for platform-specific behaviour.
31
32	## 6. Testing Conventions
33	- Jest and React Native Testing Library for components and hooks.
34	- Maestro (or Detox) flows on a device farm for the flows that make money, on every release candidate.
35	- Native modules have unit tests on each platform (XCTest or Swift Testing, JUnit) plus one integration flow through the JS interface.
36
37	## 7. Git Workflow & PR Conventions
38	- Conventional Commits scoped to the feature or module: `perf(feed): native image prefetch module`.
39	- A PR that adds a native module includes the profiling numbers that justified it.
40	- Native changes need a new binary; label them so release managers know OTA is not enough.

Works with Cursor · Claude Code · Windsurf · AGY

Architecture notes

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.

Frequently asked questions

Should a large consumer app move from React Native to fully native?

Usually not because of one slow screen. Profile it, write one native module for the hot path, and keep the shared TypeScript layer where the agent works best. Going fully native makes sense when most of the product is platform integration, at which point the native SwiftUI and Compose rules apply.

Expo Modules API or Turbo Modules?

The Expo Modules API is the shorter path for app-specific modules: Swift and Kotlin with a typed JS interface and no C++ glue. Turbo Modules with Codegen fit modules meant to be published for any React Native app. Both run on the New Architecture.

Does this AGENTS.md work with Cursor, Claude Code and Windsurf?

Yes. AGENTS.md is the cross-tool standard read by Cursor, Claude Code, Windsurf, Codex and others. A .mdc file is included for Cursor's native rules format.

Used in production

Explore all stacks

Orca

Agentic Development Environment for Parallel Coding Agents · 6-20 people

Agent CLIs stay the user's own. Orca adds the orchestration layer around them: isolated git worktrees, a PTY daemon that outlives the UI, and a relay for mobile steering. It can support new agents without bundling them.

Open Code Review

Hybrid Deterministic + LLM Agent Code Review Tool · 20+ people

A single static Go binary keeps the review engine fast and easy to distribute through npm, CI and IDE plugins. Putting deterministic diff/context analysis before a narrow LLM loop keeps reviews precise and cheap in tokens compared with general-purpose agents.

CopilotKit

AI Copilot & Assistant SDK · 2-5 people

A shared AG-UI protocol plus a PlatformAdapter-based channel architecture let one agent implementation power web, mobile and chat-platform surfaces from a single Nx/pnpm monorepo instead of building a separate integration per surface.

Bluesky App

Mobile App · 20+ people

One Expo/React Native codebase keeps three platforms in lockstep from shared UI and state code, while link shortening, OG-card rendering and web serving are split into small standalone Go/Express services so the client is not coupled to backend concerns it does not own.

Where this stack fits

Stack It First recommends it at:

Mobile · Scale · Consumer

Walk the mobile roadmap

Every stack ships as files

More AI agent coding rules and skills

View all

expo-react-native-tailwind/AGENTS.mdExpo Router + React Native + NativeWindExpo · React Native · NativeWind expo-sqlite-local-first/AGENTS.mdExpo + SQLite + Drizzle (Local-First Mobile App)Expo · React Native · Expo Router swiftui-compose-native/AGENTS.mdNative iOS + Android (SwiftUI + Jetpack Compose, Shared Schema)Swift · SwiftUI · Kotlin astro-static-content/AGENTS.mdAstro Static Site + Content Collections + TailwindAstro · Tailwind CSS · TypeScript