React Native & Expo

React Native

MANDATORY FOR ALL AI AGENTS: When generating React Native code you MUST follow every convention below. Expo is the default — do NOT generate bare React Native projects unless an ADR justifies it. Server state MUST go through TanStack Query; client state through Zustand or Jotai. useState lifted into Context is NOT a state management strategy. Never place framework code in domain/ or application/ — see mobile-architecture.md.

Project-agnostic: samples use a placeholder Expense domain. Replace with your actual domain.

Companion command: /mobile-init-project — creates the Expo project, app.config.ts, eas.json and the baseline dependency set below.

This is the mobile counterpart of spring-boot.md: the framework integration guide. Architecture rules live in mobile-architecture.md; code conventions in typescript-code-style.md.

1. Runtime baseline

The New Architecture (Fabric renderer, TurboModules, JSI, Codegen) is no longer a choice.

There is no migration to plan on a new project — you start on the New Architecture. The one thing that still matters: verify every third-party native library supports it before adopting it. The ecosystem has caught up, but abandoned packages have not.

Version numbers age. Verify the current SDK against the Expo release notes before pinning; the rules in this guide do not change with the version.

⚠️ The project must not live inside iCloud Drive, Dropbox or any file-sync client — iOS codesigning fails there and xattr -cr cannot fix it. See mobile-release.md §2.

⚠️ newArchEnabled no longer exists in ExpoConfig as of SDK 57 — the New Architecture is unconditional. Setting it is a type error.

2. Expo is the default

Use Expo with development builds — not Expo Go. Expo Go cannot load custom native modules, so every project outgrows it within weeks. Start with a dev build and skip the migration.

Choosing bare RN requires an ADR stating which specific capability Expo cannot provide. “More control” is not a reason.

app.config.ts, not app.json

Use the TypeScript form so environment values are typed and computed:

1
import type { ExpoConfig } from 'expo/config'
2

3
export default ({ config }): ExpoConfig => ({
4
  ...config,
5
  name: process.env.APP_VARIANT === 'production' ? 'Expense' : 'Expense (dev)',
6
  slug: 'expense',
7
  scheme: 'expense',
8
  ios: { bundleIdentifier: bundleIdFor(process.env.APP_VARIANT) },
9
  android: { package: bundleIdFor(process.env.APP_VARIANT) },
10
  plugins: ['expo-router', 'expo-secure-store'],
11
})

Different bundle identifiers per variant let dev and production coexist on one device. Do this from day one; retrofitting it invalidates installs.

⚠️ Everything in app.config.ts ships inside the binary and is readable. No secrets. See mobile-security.md.

3. Library selection

Every addition to this list is an ADR. Two libraries doing the same job is a defect.

4. State — the rule that matters most

Server state and client state are different problems. Do not store them in the same place.

This is the single most common architectural mistake in React Native apps.

Putting an API response into Zustand means reimplementing caching, invalidation, retries, deduplication and background refetch by hand — badly.

1
// ui/hook/useExpenses.ts — server state
2
export function useExpenses(period: Period) {
3
  const { listExpenses } = useContainer()
4
  return useQuery({
5
    queryKey: ['expenses', period],
6
    queryFn: () => listExpenses(period),
7
    staleTime: 30_000,
8
  })
9
}

1
// ui/store/filterStore.ts — client state
2
export const useFilterStore = create<FilterState>()((set) => ({
3
  category: 'all',
4
  setCategory: (category) => set({ category }),
5
}))

Select narrowly from Zustand. const store = useFilterStore() re-renders on every field change:

1
// ✅ re-renders only when category changes
2
const category = useFilterStore((s) => s.category)

Context is for dependency injection, not for state. The container provider from mobile-architecture.md §6 is a correct use: its value never changes, so it never re-renders the tree.

5. Navigation — Expo Router

File-based routing. Deep links, typed routes and universal links come for free.

1
app/
2
├── _layout.tsx              root: providers, container, theme
3
├── (tabs)/
4
│   ├── _layout.tsx
5
│   ├── index.tsx            → /
6
│   └── settings.tsx         → /settings
7
├── expense/
8
│   └── [id].tsx             → /expense/:id
9
└── +not-found.tsx

Enable typed routes in app.config.ts (experiments.typedRoutes) so a renamed screen breaks the build instead of producing a dead link at runtime.

Route files stay thin. They wire params and render a screen from ui/feature/. Business logic never lives in app/.

1
export default function ExpenseDetailRoute() {
2
  const { id } = useLocalSearchParams<{ id: string }>()
3
  const parsed = expenseIdSchema.safeParse(id)
4
  if (!parsed.success) return <NotFound />
5
  return <ExpenseDetailScreen id={parsed.data} />
6
}

⚠️ Route params are attacker-controlled. Any app on the device can open yourapp://expense/<anything>. Parse them (§boundary rules in mobile-architecture.md §7) and never trust them for authorization.

6. Data fetching

One HTTP client, in infrastructure/http/. Never call fetch from a component.

1
export function httpClient(config: HttpConfig): HttpClient {
2
  return {
3
    async get(path, init) {
4
      const controller = new AbortController()
5
      const timeout = setTimeout(() => controller.abort(), config.timeoutMs)
6
      try {
7
        const res = await fetch(`${config.baseUrl}${path}`, {
8
          ...init,
9
          signal: controller.signal,
10
          headers: { ...init?.headers, ...(await config.authHeader()) },
11
        })
12
        if (!res.ok) return err(toHttpError(res.status))
13
        return ok(await res.json())
14
      } catch (e) {
15
        return err(isAbort(e) ? { kind: 'Timeout' } : { kind: 'Network' })
16
      } finally {
17
        clearTimeout(timeout)
18
      }
19
    },
20
  }
21
}

Non-negotiable:

• Always set a timeout. fetch has no default; a hung request spins forever.
• Distinguish Timeout, Network, Unauthorized, Server — the UI reacts differently to each.
• Never console.log the response body in release. It leaks tokens and PII.
• Retries and backoff belong to TanStack Query or a decorator, not to the client.

7. Performance

Measure before optimizing. React.memo everywhere is worse than nothing — it adds comparison cost to components that were never the problem.

Lists

• FlashList over FlatList past a few hundred rows.
• Give it an accurate estimatedItemSize. A wrong estimate is worse than none.
• renderItem must be cheap and its component memoized. No .filter(), no date formatting, no object literals created inline per row.
• Stable keyExtractor. Never the array index.

Re-renders

• Narrow Zustand selectors (§4).
• useCallback / useMemo only when the value crosses a memo boundary or a dependency array. Otherwise it is noise.
• Never create objects or arrays inline in props of a memoized child.

Animation

Reanimated worklets run on the UI thread and keep animating while JS is busy. Animated from RN core does not. Use Reanimated for anything gesture-driven or continuous.

Startup

Cold start is the metric users feel.

• Lazy-load heavy screens.
• Do not block the splash screen on network calls.
• Keep the root layout thin — providers only.
• Trim the dependency tree; every native module costs startup time.

Images

expo-image with explicit dimensions and appropriately sized sources. Full-resolution photos in a list is the most common memory-pressure bug in RN apps.

Profiling

React DevTools Profiler, Flipper/Hermes tooling, and Expo’s performance monitor. Measure on a low-end physical Android device — never judge performance from an iPhone simulator on an M-series Mac.

8. Environment configuration

• Public, non-secret values: EXPO_PUBLIC_* env vars. They are inlined into the bundle and visible to anyone who unzips the app.
• Secrets: server-side only, or EAS Secrets for build-time credentials that never reach the bundle.
• Never commit .env files. Commit .env.example.
• Variants (dev / staging / production) differ by bundle identifier, app name and icon so they coexist on one device.

9. TypeScript configuration

1
{
2
  "extends": "expo/tsconfig.base",
3
  "compilerOptions": {
4
    "strict": true,
5
    "noUncheckedIndexedAccess": true,
6
    "exactOptionalPropertyTypes": true,
7
    "noImplicitOverride": true,
8
    "paths": {
9
      "@domain/*":         ["./src/domain/*"],
10
      "@application/*":    ["./src/application/*"],
11
      "@infrastructure/*": ["./src/infrastructure/*"],
12
      "@ui/*":             ["./src/ui/*"]
13
    }
14
  }
15
}

noUncheckedIndexedAccess is the one people disable and then regret: without it array[0] is typed as defined even when the array is empty. See typescript-code-style.md.

10. Tooling

This mirrors the Spotless/Detekt split in gradle.md: formatting and static analysis are separate jobs. All three run in CI and all three must fail the build.

⚠️ Install dev tooling with npx expo install, not npm install. Expo pins the tooling versions its preset supports; npm installs latest, which silently breaks. Two real failures observed on SDK 57:

Run npx expo install --check before trusting a green build.

11. Anti-patterns

12. Pre-merge checklist

• No fetch or storage access inside a component
• Server state in TanStack Query, client state in Zustand, no crossover
• Zustand selectors are narrow
• Route params parsed before use
• Every network call has a timeout and typed errors
• Lists use FlashList with an accurate estimatedItemSize
• No secrets in EXPO_PUBLIC_* or app.config.ts
• tsc --noEmit, ESLint and boundary rules pass
• npx expo install --check reports no outdated dependencies
• Verified on a low-end physical Android device