Expo (React Native)

Pathrule2 Rules • 2 Memories • 1 Skill

A guardrail bundle for modern Expo (SDK 56+) React Native projects on the New Architecture. It keeps Expo Router navigation typed and predictable, treats the app config as the single source of native truth via Continuous Native Generation, and prevents the classic OTA crash where a JavaScript update references native code that isn't in the installed binary. Built for teams shipping with EAS Build and EAS Update.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

Treat ios/ and android/ as generated output

runtimeVersion gates OTA vs binary builds

Roll out EAS Updates gradually and test on a branch first

expo-react-native-review

app/

Use Expo Router typed navigation, not React Navigation imports

Rules

Treat ios/ and android/ as generated output/roothighstrictNever hand-edit native folders in a CNG project; change app config and config plugins instead.

1	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.
2
3	- Express native config (permissions, plist/manifest entries, schemes, icons, splash) through the `expo` app config and config plugins, not by patching native files.
4	- For library-specific native side effects, add or use an Expo config plugin instead of editing `AppDelegate` or `MainApplication` directly.
5	- 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.
6	- Verify a change survives by running `npx expo prebuild --clean` before relying on it.

Use Expo Router typed navigation, not React Navigation imports/apphighadvisoryRoute through the file system and the typed Link/router API; avoid raw react-navigation calls.

1	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.
2
3	- Navigate with `<Link href="...">` and `useRouter()` from `expo-router`; do not import navigators or `useNavigation` from `@react-navigation/*` directly.
4	- Keep typed routes enabled (`experiments.typedRoutes` / the SDK 56 default) and let the generated `.expo/types` drive `href` autocompletion.
5	- Prefer `useLocalSearchParams()` over `useGlobalSearchParams()`. The global hook re-renders on every navigation event and causes cascading updates across the tree.
6	- Organize routes with route groups like `(tabs)` and `(auth)` to structure the tree without changing the URL, and use `_layout.tsx` for shared shells.

Memories

runtimeVersion gates OTA vs binary builds/rootOTA ships only JS; native changes require a new binary and a bumped runtimeVersion.

1	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.
2
3	- 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.
4	- Never bump `runtimeVersion` for a JS-only fix; that would orphan existing installs from the update.
5	- Prefer the `fingerprint` runtime version policy so the value is computed deterministically from native inputs instead of bumped by hand.
6	- 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.

Roll out EAS Updates gradually and test on a branch first/rootPublish to a preview branch, then roll out by percentage and watch error rates before going to all users.

1	A bad OTA can break every install at once, so updates ship through a staged pipeline rather than straight to production.
2
3	- Publish to a non-production channel first with `eas update --branch preview` and smoke-test on a dev/preview build before promoting.
4	- 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.
5	- Map channels to environments (for example `production`, `preview`, `staging`) and point each build profile at the right channel in `eas.json`.
6	- 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.

Skills

expo-react-native-review/rootPre-merge checklist for Expo SDK 56 apps covering CNG, typed routing, EAS Build, and OTA safety.

1	---
2	name: expo-react-native-review
3	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.
4	---
5
6	# Expo (React Native) review
7
8	- [ ] No hand edits to `ios/` or `android/`; native changes go through `app.config` and config plugins (CNG).
9	- [ ] `npx expo prebuild --clean` still produces the intended native project.
10	- [ ] All navigation uses `expo-router` (`Link`, `useRouter`); no direct `@react-navigation/*` navigation calls.
11	- [ ] Typed routes are enabled and generated route types are committed/ignored consistently; `href` values resolve.
12	- [ ] `useLocalSearchParams` is used instead of `useGlobalSearchParams` unless a global subscription is truly needed.
13	- [ ] Route groups and `_layout.tsx` keep the `app/` tree organized without leaking group names into URLs.
14	- [ ] New native dependencies or prebuild changes bumped `runtimeVersion` (or use the `fingerprint` policy).
15	- [ ] JS-only fixes did NOT change `runtimeVersion`, so existing installs still receive the update.
16	- [ ] The update was published to a preview branch and smoke-tested before any production promotion.
17	- [ ] Production rollout is staged by percentage with an error-rate watch and a rollback path.
18	- [ ] Project targets a current SDK (56+) on the New Architecture; no New Architecture opt-out is assumed.
19	- [ ] `eas.json` build profiles map to the correct update channels per environment.

Why this pattern

AI agents edit native files directly and push OTA updates that reference native modules missing from the installed binary, crashing production apps.

Built for Teams building cross-platform Expo apps with EAS Build and EAS Update..

Keeps your assistant from:

Hand-editing ios/ and android/ folders that prebuild regenerates and wipes
Pushing an EAS Update with native changes without bumping runtimeVersion, crashing live users
Importing from react-navigation directly and bypassing Expo Router typed routes

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-06-09