Org Skills

react-native-architecture

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.

Download .zip Raw Source
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.

npx skills add AGCO-Global/org-skills --skill react-native-architecture
# user-level instead of project-level:
npx skills add AGCO-Global/org-skills --skill react-native-architecture -g

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.

Skill contents

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.

References

Deeper material the agent loads only when needed.