react-native-playbook

React Native Playbook (Expo + TypeScript)

This is the literal procedure for working in an Expo + React Native codebase. The single most expensive class of mistake in this stack is treating it like web React: the second most expensive is proposing native changes without first knowing whether the project runs in Expo Go or a dev client. Both are killed by following the loop in order.

Operating loop

1. Read the project's identity files before any opinion. In this order:
   • package.json — the expo package version tells you the SDK line (e.g. ~51.x → SDK 51). Note whether expo-dev-client, @shopify/flash-list, react-native-reanimated, and react-native-safe-area-context are installed.
   • app.json / app.config.ts|js — existing plugins array, permissions (ios.infoPlist, android.permissions), bundleIdentifier/package, newArchEnabled if present.
   • Repo root — ios/ or android/ directories present means the native projects are checked in (bare or prebuilt); absent means CNG/managed.
   • Lockfile — pnpm-lock.yaml/yarn.lock/package-lock.json decides the package manager. Never create a second lockfile.
2. Classify the runtime before proposing any native change.
   • No expo-dev-client, no ios//android/ dirs → the team runs Expo Go: only Expo SDK modules and pure-JS libraries work. Anything else is an escalation (see decision tree A) and must be stated as one.
   • expo-dev-client present or eas.json with build profiles → dev client: config plugins and native modules work, but every change to app.json plugins or native deps requires a rebuild, not a reload.
3. Detect the router. app/ directory + expo-router in package.json → Expo Router (file-based; new screens are new files under app/). Otherwise @react-navigation/native → React Navigation (screens register in a navigator; params typed in the param list).
4. Read 2–3 neighboring screens/components in the area you're changing. Match their styling approach (StyleSheet.create vs a styling lib), import order, and data-fetching pattern. Do not import a pattern the repo doesn't already use.
5. Install dependencies only via npx expo install <pkg> — it pins the version compatible with the project's SDK. A bare npm install of an RN-adjacent package is how version-mismatch build failures start.
6. Build the smallest slice, then run the checks (see Verification recipe). Any change touching layout, lists, keyboard, or navigation gets named per-platform verification steps in your report — iOS and Android differ on exactly those four things.
7. In your report, separate JS-reloadable changes from rebuild-required changes. Editing a component = reload. Adding a native dep, a config plugin, or changing app.json native keys = new build (npx expo prebuild + native run, or an EAS build). Saying which one applies is part of being done.