Agent instructionsScan: pass
Expo React Native CLAUDE.md
CLAUDE.md for an Expo SDK 52+ app with expo-router and EAS: install rules, platform gotchas, jest-expo unit tests, and Maestro E2E flows.
Add a trust badge to your README
[](https://waxmark.app/items/expo-react-native-claude-md/scan)
# {{PROJECT_NAME}}
Expo (SDK 52+) app with TypeScript, `expo-router` file-based navigation, and EAS for builds and updates. New Architecture is on (SDK default). Deep-link scheme `{{APP_SCHEME}}://`, bundle id `{{BUNDLE_ID}}`. Package manager: the one that owns the lockfile in this repo; never mix.
## Commands
| Task | Command |
|------|---------|
| Install a package | `npx expo install <pkg>` (picks the SDK-compatible version; never plain `npm install` for native or Expo packages) |
| Start dev server | `npx expo start` (`--ios`, `--android`, `--web` to open a target) |
| Check project health | `npx expo-doctor` |
| Typecheck | `npx tsc --noEmit` |
| Lint | `npx expo lint` |
| Unit tests | `npx jest` (one file: `npx jest src/features/cart`) |
| E2E | `maestro test .maestro/` (one flow: `maestro test .maestro/login.yaml`) |
| Native build locally | `npx expo run:ios` / `npx expo run:android` (regenerates `ios/` and `android/` via prebuild) |
| Cloud build | `eas build --profile development --platform ios` (profiles in `eas.json`) |
| OTA update | `eas update --branch preview --message "<what changed>"` |
Definition of done: `npx tsc --noEmit`, `npx expo lint`, and `npx jest` exit 0, and `npx expo-doctor` reports no issues if you touched `package.json` or `app.json`. Paste the jest summary.
## Routing (expo-router)
- Routes are files under `app/`. `app/_layout.tsx` is the root layout (providers, fonts, splash). Groups in parentheses `app/(tabs)/`, dynamic segments `app/post/[id].tsx`, modals via `<Stack.Screen options={{ presentation: 'modal' }}>`.
- Navigate with `router.push('/post/123')` or `<Link href="/post/123">`. Typed routes are on (`experiments.typedRoutes` in `app.json`); fix type errors on hrefs instead of casting.
- Screen components in `app/` are thin: they read params with `useLocalSearchParams()` and render a feature component from `src/features/<name>/`. No business logic in `app/`.
- Every new route needs a deep-link check: `npx uri-scheme open "{{APP_SCHEME}}://post/123" --ios`.
## Platform gotchas
- Platform-specific files: `Button.ios.tsx`, `Button.android.tsx`, `Button.web.tsx`; Metro picks the right one. Use `Platform.select({ ios: ..., android: ..., default: ... })` for small differences, a split file for large ones.
- Web is a target: no `require('react-native').NativeModules` access without a `Platform.OS !== 'web'` guard, and every native-only package needs a web fallback or a `.web.tsx` stub.
- Expo Go cannot load custom native modules. If a change adds a package with native code, say so in the report and build a development client (`eas build --profile development`).
- Safe areas: wrap screens in `SafeAreaView` from `react-native-safe-area-context`, not the one from `react-native`.
- Android back button and iOS swipe-back behave differently; test both when changing navigation.
- Keyboard: use `KeyboardAvoidingView` with `behavior={Platform.OS === 'ios' ? 'padding' : 'height'}`.
- Images: `expo-image` with explicit `style` dimensions; never `<Image>` from `react-native` for remote URLs.
- `app.json` changes to `plugins`, `ios.*`, or `android.*` require a new native build; an OTA update will not pick them up.
## Environment and config
- Public config via `EXPO_PUBLIC_*` env vars (inlined at build time; never a secret). Everything else is fetched from the API at runtime.
- `app.config.ts` reads `process.env.APP_VARIANT` to set `name`, `bundleIdentifier`/`package`, and `scheme` per variant (`development`, `preview`, `production`). Match these to `eas.json` profiles.
- Do not edit `ios/` or `android/` directly; they are generated by prebuild. Native changes go through config plugins in `plugins/` or `app.config.ts`.
- EAS project id `{{EAS_PROJECT_ID}}` lives in `app.config.ts` under `extra.eas.projectId`; do not change it.
## Testing
- Unit: `jest-expo` preset (`"preset": "jest-expo"` in `jest.config.js`), `@testing-library/react-native`. Query with `getByRole`/`getByText`; prefer `screen.getByRole('button', { name: /save/i })`. Use `testID` only when there is no accessible name.
- Mock native modules in `jest.setup.ts`, not per test. Mock the API client at `src/api/client.ts`, not `fetch`.
- Hooks and stores get their own tests; screen tests check rendering and navigation calls (`jest.mock('expo-router')`).
- E2E: one Maestro flow per critical path in `.maestro/*.yaml` (`appId: {{BUNDLE_ID}}`, then `launchApp`, `tapOn`, `inputText`, `assertVisible`). Flows must pass on both an iOS simulator and an Android emulator before a release build.
## Do not
- Do not upgrade the Expo SDK; that is a separate, human-led task (`npx expo install expo@latest` then `npx expo install --fix`).
- Do not add `react-native-*` packages that are not in the Expo SDK or React Native Directory without noting New Architecture support in the report.
- Do not run `eas build --profile production`, `eas submit`, or `eas update --branch production`.
- Do not commit `.env`, `google-services.json`, or `GoogleService-Info.plist`.