# Pathrule Pattern: Expo (React Native) (1.0.0) # ::pathrule:package:expo-react-native ### [RULE] Treat ios/ and android/ as generated output (path: /) This is a Continuous Native Generation (CNG) project, so the `ios/` and `android/` directories are regenerated from `app.json`/`app.config.ts` and `package.json` by `npx expo prebuild`. Editing them by hand creates changes that are silently wiped on the next prebuild. - Express native config (permissions, plist/manifest entries, schemes, icons, splash) through the `expo` app config and config plugins, not by patching native files. - For library-specific native side effects, add or use an Expo config plugin instead of editing `AppDelegate` or `MainApplication` directly. - Keep `ios/` and `android/` out of version control when prebuild is the source of truth; if they are committed, treat them as build artifacts and never the place to make a change. - Verify a change survives by running `npx expo prebuild --clean` before relying on it. --- ### [RULE] Use Expo Router typed navigation, not React Navigation imports (path: /app) Files under `app/` are the routing layer. Each file is a route and navigation must go through Expo Router's typed API so broken links fail at compile time, not at runtime. - Navigate with `` and `useRouter()` from `expo-router`; do not import navigators or `useNavigation` from `@react-navigation/*` directly. - Keep typed routes enabled (`experiments.typedRoutes` / the SDK 56 default) and let the generated `.expo/types` drive `href` autocompletion. - Prefer `useLocalSearchParams()` over `useGlobalSearchParams()`. The global hook re-renders on every navigation event and causes cascading updates across the tree. - Organize routes with route groups like `(tabs)` and `(auth)` to structure the tree without changing the URL, and use `_layout.tsx` for shared shells. --- ### [MEMORY] runtimeVersion gates OTA vs binary builds (path: /) EAS Update delivers only the JavaScript bundle and assets, never native code. An update is only served to a binary whose `runtimeVersion` matches the one the update was published against, so the contract is: native change means new binary, JS-only change means OTA. - Bump `runtimeVersion` whenever you add or change native code (new native dependency, prebuild config change, SDK upgrade) so old binaries do not receive a JS bundle that references modules they lack. - Never bump `runtimeVersion` for a JS-only fix; that would orphan existing installs from the update. - Prefer the `fingerprint` runtime version policy so the value is computed deterministically from native inputs instead of bumped by hand. - Pushing native-dependent JS over OTA to a mismatched binary is the classic production crash this stack guards against. See `/app` for navigation rules and `/modules` for native module conventions. --- ### [MEMORY] Roll out EAS Updates gradually and test on a branch first (path: /) A bad OTA can break every install at once, so updates ship through a staged pipeline rather than straight to production. - Publish to a non-production channel first with `eas update --branch preview` and smoke-test on a dev/preview build before promoting. - Use percentage rollouts: release to a small slice of users, watch the update's error rate on the EAS dashboard, and cancel or roll back if it spikes. - Map channels to environments (for example `production`, `preview`, `staging`) and point each build profile at the right channel in `eas.json`. - SDK 55+ bundle diffing only ships the delta between bundles, so frequent small updates are cheap; lean on small, reversible updates over large risky ones. --- ### [SKILL] expo-react-native-review (path: /) --- name: expo-react-native-review description: Review checklist for Expo (React Native) changes on SDK 56 and the New Architecture. Run before merging any change that touches app config, native modules, Expo Router routes, or EAS Build/Update configuration. --- # Expo (React Native) review - [ ] No hand edits to `ios/` or `android/`; native changes go through `app.config` and config plugins (CNG). - [ ] `npx expo prebuild --clean` still produces the intended native project. - [ ] All navigation uses `expo-router` (`Link`, `useRouter`); no direct `@react-navigation/*` navigation calls. - [ ] Typed routes are enabled and generated route types are committed/ignored consistently; `href` values resolve. - [ ] `useLocalSearchParams` is used instead of `useGlobalSearchParams` unless a global subscription is truly needed. - [ ] Route groups and `_layout.tsx` keep the `app/` tree organized without leaking group names into URLs. - [ ] New native dependencies or prebuild changes bumped `runtimeVersion` (or use the `fingerprint` policy). - [ ] JS-only fixes did NOT change `runtimeVersion`, so existing installs still receive the update. - [ ] The update was published to a preview branch and smoke-tested before any production promotion. - [ ] Production rollout is staged by percentage with an error-rate watch and a rollback path. - [ ] Project targets a current SDK (56+) on the New Architecture; no New Architecture opt-out is assumed. - [ ] `eas.json` build profiles map to the correct update channels per environment.