Architect-level guidance for React Native and Expo apps — Expo managed vs bare vs brownfield, Expo Router structure and auth boundaries, state and offline-first data with TanStack Query, MMKV, SecureStore and SQLite, native module strategy, monorepo code sharing with web, theming and i18n, observability, and release engineering with EAS Build and EAS Update.
When agents use itUse this whenever the user is starting or restructuring a React Native / Expo project, asks "Expo or bare", how to add React Native to an existing native app, where a file or feature should live, how to share code between mobile and web, which storage or navigation library to use, whether to write a native module, or how to do OTA updates, runtimeVersion policies and staged rollouts safely. Also use it when a single screen question hides a platform decision such as offline sync, session storage or upgrading the Expo SDK. For day-to-day screen code use react-native-development.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill react-native-architecture -a github-copilot
# or with the org installer (adds .github/skills/react-native-architecture):
npx -y github:AGCO-Global/org-skills add skill react-native-architecture
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the frontend-react-native-skills plugin, which bundles all Frontend / React Native skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install frontend-react-native-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill react-native-architecture -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill react-native-architecture -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill react-native-architecture -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill react-native-architecture -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the react-native-architecture folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
Mobile is a different discipline from web: binaries ship through store review, users are offline, devices are slow, and a mistake takes a day to roll back — or a week if it is native. Design for that, and write every decision down with the condition that would flip it.
1. Decide first
Question
Default
Change when
Workflow
Expo managed with expo-dev-client and config plugins
A native SDK has no plugin and you cannot write one → bare, keeping the expo modules. Adding RN to an existing native app → brownfield with expo-brownfield (SDK 55+)
Architecture
New Architecture — the only one. RN 0.82 ignores newArchEnabled=false and SDK 55 removed the option
Never. A legacy-only dependency gets replaced, or wrapped through the interop layer, and the migration is dated
JS engine
Hermes
Evaluate Hermes V1 (SDK 55+) once your dependencies are clean; never JSC, which moved to a community package
Navigation
Expo Router (file-based, deep links and typed routes)
A large existing React Navigation codebase → stay on v7 rather than half-migrating
Styling
StyleSheet + a token file, or NativeWind if the team is Tailwind-fluent
Runtime multi-brand theming → Unistyles or Tamagui
Package manager
pnpm with isolated dependencies (supported since SDK 54)
A native library fails to resolve → nodeLinker: hoisted in pnpm-workspace.yaml as a documented fallback, not a default
Storage split
MMKV for settings and cache; expo-secure-store for tokens; Expo SQLite (+ Drizzle) for relational data
Sync-heavy offline product → WatermelonDB or a purpose-built outbox
Builds and updates
EAS Build + EAS Update, runtimeVersion on the fingerprint policy
Enterprise CI mandate → Fastlane on self-hosted runners, still with Expo modules
Sharing screens through react-native-web — only for genuinely simple UI; be honest that it fights you later
Write these into ARCHITECTURE.md as ADRs (§8). The Expo variant of the feature-first tree lives in the react-architecture skill as layouts.md.
2. Structure
app/ holds Expo Router routes only — thin files that render a screen from features/<feature>/screens/. shared/{ui,lib,hooks,theme} holds primitives, the API client, storage, analytics and tokens; shared/ never imports from features/. Local native code lives in modules/ as local Expo Modules with TypeScript bindings. Platform forks (.ios.tsx / .android.tsx) only for real divergence; Platform.select for small values. Enforce the boundaries with eslint-config-expo plus no-restricted-imports so the rule is checked, not remembered.
3. Navigation and auth boundaries
Group routes by access: (auth) and (app), gated in the root layout with <Stack.Protected guard={!!session}> (SDK 53+). Guards run on the client — the API authorises for real.
Session in expo-secure-store, read once at startup behind the splash, exposed through one useSession() hook. Refresh tokens rotate in a single place, and every 401 funnels to one handler.
Deep links and universal links configured on day one (scheme, associatedDomains, intentFilters); retrofitting them means re-releasing natively.
Modals as (modals) route groups so they are deep-linkable and back-aware; tabs ≤ 5, stacks nested inside tabs, never the reverse.
4. Data and offline-first
Assume the network fails. Server data goes in TanStack Query with the cache persisted to MMKV and networkMode: 'offlineFirst'; screens render cached data instantly and refetch behind a subtle "updated x ago" marker. Writes made offline either queue through the mutation cache with onlineManager, or — for anything the user must not lose — go into an explicit outbox table in SQLite with a retry worker.
Pick and document the conflict rule before writing code: last-write-wins, server-authoritative, or per-field merge. Show the user the conflict case; most teams discover it in production otherwise. Full decision table, persistence setup and the outbox sketch: references/offline-and-data.md.
5. Native modules — in this order
Expo SDK module (expo-camera, expo-location, expo-notifications, …) — config plugins, New Architecture support, upgraded with the SDK.
Community module with a config plugin — check the last release, open issues and New Architecture support before adopting.
Local Expo Module (npx create-expo-module --local) in Swift/Kotlin — the default for custom native code; small, typed, no bridge boilerplate.
Hand-written TurboModule or Fabric component — only for performance-critical rendering or wrapping a large existing native codebase.
Never patch node_modules without patch-package and a tracking issue. Never commit expo prebuild output unless the team has committed to bare. In a brownfield app, expo-brownfield keeps the RN surface isolated so the native app owns its own lifecycle.
Tokens in shared/theme, consumed through useTheme(); useColorScheme() supported from the first screen. Dynamic type tested at 200 %.
i18next + expo-localization; no hard-coded strings in screens; RTL checked with I18nManager.forceRTL in development.
Accessibility target stated in ARCHITECTURE.md: WCAG 2.2 AA plus platform guidelines (44 pt iOS / 48 dp Android touch targets, screen-reader labels on every control).
Compliance is architecture: iOS privacy manifest (PrivacyInfo.xcprivacy) and the Play data-safety form must match what the app actually collects; Android 16 edge-to-edge and predictive back are mandatory; decide certificate pinning and key rotation deliberately rather than by default.
7. Observability and quality gates
Crash reporting (Sentry) with source maps uploaded per build and per update, a root error boundary rendering a designed screen with "reload", remote feature flags so a risky feature can be killed without a store release, and cold-start plus screen-TTI marks reported from real devices. CI on every pull request: expo-doctor, tsc --noEmit, ESLint, unit tests, and an EAS Build preview.
8. Deliverable format (ADR)
## ADR-<n>: <decision>
Context: <team, existing native code, offline needs, store constraints, SDK version>
Decision: <default from §1, or the deviation>
Flips when: <the one condition that would change it>
Consequences: <what becomes easy, what becomes hard, migration and release cost>
Checklist
ARCHITECTURE.md holds the §1 decisions as ADRs, including the Expo SDK the project targets
Routes are thin; features own their screens, api and model; shared/ does not import features/
Auth gated with Stack.Protected, session in SecureStore, one 401 handler
Offline behaviour specified per screen, plus a written conflict rule
Storage split correct: SecureStore for secrets, MMKV for hot reads, SQLite for relational data
Native capability chosen by the §5 ladder; no patched node_modules without a tracking issue
runtimeVersion policy chosen deliberately; channels for development, preview and production
Update vs store-build rules written down, with a rollback runbook (eas update:rollback)
Privacy manifest and data-safety declarations match the SDKs actually shipped
packages/core free of react-native imports, enforced by lint
Anti-patterns
"Disable the New Architecture for now" → impossible since RN 0.82 / SDK 55; replace or wrap the dependency instead.
Forcing node-linker=hoisted by default → isolated pnpm works from SDK 54; hoist only a specific failing library and note why.
Tokens in AsyncStorage, MMKV or a persisted store → expo-secure-store.
Business logic in route files or _layout.tsx → features own logic; routes own composition.
Sharing screens with web through react-native-web as the plan → share logic; design mobile UI for touch.
Fetching with no offline story and calling it done → every screen names its cached, empty and offline behaviour.
runtimeVersion: appVersion with nobody bumping the version → fingerprint, which tracks native changes automatically.
Shipping a native change as an OTA update → EAS Update carries JS and assets only; native changes need a build.
The shared React and React Native anti-pattern list lives in the react-development skill as react-anti-patterns.md.
references/release-engineering.md — EAS Build profiles, channels and branches, runtimeVersion policies, bytecode-diffed updates, staged rollouts, rollback runbook, store compliance.
Sibling skills: react-native-development (screens), react-native-performance (startup and jank), react-native-testing (tests), react-architecture (the web side and the shared folder layout in layouts.md), frontend-code-review.
---
name: react-native-architecture
description: >
Architect-level guidance for React Native and Expo apps — Expo managed vs bare vs brownfield, Expo Router
structure and auth boundaries, state and offline-first data with TanStack Query, MMKV, SecureStore and
SQLite, native module strategy, monorepo code sharing with web, theming and i18n, observability, and
release engineering with EAS Build and EAS Update. Use this whenever the user is starting or restructuring
a React Native / Expo project, asks "Expo or bare", how to add React Native to an existing native app,
where a file or feature should live, how to share code between mobile and web, which storage or navigation
library to use, whether to write a native module, or how to do OTA updates, runtimeVersion policies and
staged rollouts safely. Also use it when a single screen question hides a platform decision such as offline
sync, session storage or upgrading the Expo SDK. For day-to-day screen code use react-native-development.
metadata:
technology: React Native
type: architecture
---
# React Native Architecture
> **Targets:** Expo SDK 54+ (57 current) · React Native 0.87 · Expo Router v7 · EAS Build/Update · **Verified:** 2026-09 against https://docs.expo.dev, https://expo.dev/changelog, https://reactnative.dev
Mobile is a different discipline from web: binaries ship through store review, users are offline, devices are slow, and a mistake takes a day to roll back — or a week if it is native. Design for that, and write every decision down with the condition that would flip it.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Workflow | **Expo managed** with `expo-dev-client` and config plugins | A native SDK has no plugin and you cannot write one → bare, keeping the `expo` modules. Adding RN to an existing native app → brownfield with `expo-brownfield` (SDK 55+) |
| Architecture | **New Architecture** — the only one. RN 0.82 ignores `newArchEnabled=false` and SDK 55 removed the option | Never. A legacy-only dependency gets replaced, or wrapped through the interop layer, and the migration is dated |
| JS engine | **Hermes** | Evaluate **Hermes V1** (SDK 55+) once your dependencies are clean; never JSC, which moved to a community package |
| Navigation | **Expo Router** (file-based, deep links and typed routes) | A large existing React Navigation codebase → stay on v7 rather than half-migrating |
| Styling | `StyleSheet` + a token file, or **NativeWind** if the team is Tailwind-fluent | Runtime multi-brand theming → Unistyles or Tamagui |
| Package manager | **pnpm with isolated dependencies** (supported since SDK 54) | A native library fails to resolve → `nodeLinker: hoisted` in `pnpm-workspace.yaml` as a documented fallback, not a default |
| Storage split | MMKV for settings and cache; `expo-secure-store` for tokens; Expo SQLite (+ Drizzle) for relational data | Sync-heavy offline product → WatermelonDB or a purpose-built outbox |
| Builds and updates | **EAS Build + EAS Update**, `runtimeVersion` on the `fingerprint` policy | Enterprise CI mandate → Fastlane on self-hosted runners, still with Expo modules |
| Code sharing with web | Monorepo sharing **logic** (`packages/core`: domain, API client, Zod schemas, query hooks) | Sharing screens through `react-native-web` — only for genuinely simple UI; be honest that it fights you later |
Write these into `ARCHITECTURE.md` as ADRs (§8). The Expo variant of the feature-first tree lives in the `react-architecture` skill as `layouts.md`.
## 2. Structure
`app/` holds Expo Router routes only — thin files that render a screen from `features/<feature>/screens/`. `shared/{ui,lib,hooks,theme}` holds primitives, the API client, storage, analytics and tokens; `shared/` never imports from `features/`. Local native code lives in `modules/` as local Expo Modules with TypeScript bindings. Platform forks (`.ios.tsx` / `.android.tsx`) only for real divergence; `Platform.select` for small values. Enforce the boundaries with `eslint-config-expo` plus `no-restricted-imports` so the rule is checked, not remembered.
## 3. Navigation and auth boundaries
- Group routes by access: `(auth)` and `(app)`, gated in the root layout with `<Stack.Protected guard={!!session}>` (SDK 53+). Guards run on the client — the API authorises for real.
- Session in `expo-secure-store`, read once at startup behind the splash, exposed through one `useSession()` hook. Refresh tokens rotate in a single place, and every 401 funnels to one handler.
- Deep links and universal links configured on day one (`scheme`, `associatedDomains`, `intentFilters`); retrofitting them means re-releasing natively.
- Modals as `(modals)` route groups so they are deep-linkable and back-aware; tabs ≤ 5, stacks nested inside tabs, never the reverse.
## 4. Data and offline-first
Assume the network fails. Server data goes in TanStack Query with the cache persisted to MMKV and `networkMode: 'offlineFirst'`; screens render cached data instantly and refetch behind a subtle "updated x ago" marker. Writes made offline either queue through the mutation cache with `onlineManager`, or — for anything the user must not lose — go into an explicit outbox table in SQLite with a retry worker.
Pick and document the conflict rule before writing code: last-write-wins, server-authoritative, or per-field merge. Show the user the conflict case; most teams discover it in production otherwise. Full decision table, persistence setup and the outbox sketch: `references/offline-and-data.md`.
## 5. Native modules — in this order
1. **Expo SDK module** (`expo-camera`, `expo-location`, `expo-notifications`, …) — config plugins, New Architecture support, upgraded with the SDK.
2. **Community module with a config plugin** — check the last release, open issues and New Architecture support before adopting.
3. **Local Expo Module** (`npx create-expo-module --local`) in Swift/Kotlin — the default for custom native code; small, typed, no bridge boilerplate.
4. **Hand-written TurboModule or Fabric component** — only for performance-critical rendering or wrapping a large existing native codebase.
Never patch `node_modules` without `patch-package` and a tracking issue. Never commit `expo prebuild` output unless the team has committed to bare. In a brownfield app, `expo-brownfield` keeps the RN surface isolated so the native app owns its own lifecycle.
## 6. Cross-cutting: theming, i18n, accessibility, security
- Tokens in `shared/theme`, consumed through `useTheme()`; `useColorScheme()` supported from the first screen. Dynamic type tested at 200 %.
- `i18next` + `expo-localization`; no hard-coded strings in screens; RTL checked with `I18nManager.forceRTL` in development.
- Accessibility target stated in `ARCHITECTURE.md`: WCAG 2.2 AA plus platform guidelines (44 pt iOS / 48 dp Android touch targets, screen-reader labels on every control).
- Compliance is architecture: iOS privacy manifest (`PrivacyInfo.xcprivacy`) and the Play data-safety form must match what the app actually collects; Android 16 edge-to-edge and predictive back are mandatory; decide certificate pinning and key rotation deliberately rather than by default.
## 7. Observability and quality gates
Crash reporting (Sentry) with source maps uploaded per build and per update, a root error boundary rendering a designed screen with "reload", remote feature flags so a risky feature can be killed without a store release, and cold-start plus screen-TTI marks reported from real devices. CI on every pull request: `expo-doctor`, `tsc --noEmit`, ESLint, unit tests, and an EAS Build preview.
## 8. Deliverable format (ADR)
```
## ADR-<n>: <decision>
Context: <team, existing native code, offline needs, store constraints, SDK version>
Decision: <default from §1, or the deviation>
Flips when: <the one condition that would change it>
Consequences: <what becomes easy, what becomes hard, migration and release cost>
```
## Checklist
- [ ] `ARCHITECTURE.md` holds the §1 decisions as ADRs, including the Expo SDK the project targets
- [ ] Routes are thin; features own their screens, api and model; `shared/` does not import `features/`
- [ ] Auth gated with `Stack.Protected`, session in SecureStore, one 401 handler
- [ ] Offline behaviour specified per screen, plus a written conflict rule
- [ ] Storage split correct: SecureStore for secrets, MMKV for hot reads, SQLite for relational data
- [ ] Native capability chosen by the §5 ladder; no patched `node_modules` without a tracking issue
- [ ] `runtimeVersion` policy chosen deliberately; channels for development, preview and production
- [ ] Update vs store-build rules written down, with a rollback runbook (`eas update:rollback`)
- [ ] Privacy manifest and data-safety declarations match the SDKs actually shipped
- [ ] `packages/core` free of `react-native` imports, enforced by lint
## Anti-patterns
- **"Disable the New Architecture for now"** → impossible since RN 0.82 / SDK 55; replace or wrap the dependency instead.
- **Forcing `node-linker=hoisted` by default** → isolated pnpm works from SDK 54; hoist only a specific failing library and note why.
- **Tokens in AsyncStorage, MMKV or a persisted store** → `expo-secure-store`.
- **Business logic in route files or `_layout.tsx`** → features own logic; routes own composition.
- **Sharing screens with web through `react-native-web` as the plan** → share logic; design mobile UI for touch.
- **Fetching with no offline story and calling it done** → every screen names its cached, empty and offline behaviour.
- **`runtimeVersion: appVersion` with nobody bumping the version** → `fingerprint`, which tracks native changes automatically.
- **Shipping a native change as an OTA update** → EAS Update carries JS and assets only; native changes need a build.
- The shared React and React Native anti-pattern list lives in the `react-development` skill as `react-anti-patterns.md`.
## Go deeper
- `references/offline-and-data.md` — persistence setup, mutation queue vs outbox, conflict strategies, SQLite/Drizzle, cache lifetimes.
- `references/release-engineering.md` — EAS Build profiles, channels and branches, `runtimeVersion` policies, bytecode-diffed updates, staged rollouts, rollback runbook, store compliance.
- Sibling skills: `react-native-development` (screens), `react-native-performance` (startup and jank), `react-native-testing` (tests), `react-architecture` (the web side and the shared folder layout in `layouts.md`), `frontend-code-review`.