|
| 1 | +--- |
| 2 | +description: "Cursor rules for file-based routing with Expo Router in React Native and Expo apps (web + native)." |
| 3 | +globs: ["app/**/*.{ts,tsx,js,jsx}", "**/_layout.{ts,tsx}"] |
| 4 | +alwaysApply: false |
| 5 | +--- |
| 6 | + |
| 7 | +# Expo Router |
| 8 | + |
| 9 | +Expo Router is file-based routing for React Native. Every file inside `app/` becomes a route. Layouts wrap nested routes. The same code runs on iOS, Android, and web. |
| 10 | + |
| 11 | +## Directory structure |
| 12 | + |
| 13 | +- `app/_layout.tsx` is the root layout. It runs once at app start and must render `<Slot />`, `<Stack />`, `<Tabs />`, or `<Drawer />`. |
| 14 | +- `app/index.tsx` is the home route (`/`). |
| 15 | +- Nested folders create nested URLs: `app/settings/profile.tsx` → `/settings/profile`. |
| 16 | +- `app/_layout.tsx` inside a subfolder defines a layout scoped to that subtree. |
| 17 | +- Files starting with `_` are not routes (they're layouts or helpers). |
| 18 | +- Files starting with `+` are special (e.g., `+not-found.tsx`, `+native-intent.tsx`). |
| 19 | + |
| 20 | +## Layouts: Stack, Tabs, and groups |
| 21 | + |
| 22 | +```tsx |
| 23 | +// app/_layout.tsx |
| 24 | +import { Stack } from "expo-router"; |
| 25 | +export default function RootLayout() { |
| 26 | + return ( |
| 27 | + <Stack> |
| 28 | + <Stack.Screen name="index" options={{ title: "Home" }} /> |
| 29 | + <Stack.Screen name="(tabs)" options={{ headerShown: false }} /> |
| 30 | + <Stack.Screen name="modal" options={{ presentation: "modal" }} /> |
| 31 | + </Stack> |
| 32 | + ); |
| 33 | +} |
| 34 | +``` |
| 35 | + |
| 36 | +- Use `<Tabs>` for bottom tab navigators, `<Stack>` for pushed screens, `<Drawer>` for side drawers (requires `expo-router/drawer`). |
| 37 | +- Wrap a layout in a route group `(name)` to share a layout without affecting the URL: `app/(tabs)/home.tsx` → `/home`. Groups are how you avoid `/tabs/home` URLs. |
| 38 | + |
| 39 | +## Dynamic and catch-all routes |
| 40 | + |
| 41 | +- `app/post/[id].tsx` → `/post/123`. Read with `useLocalSearchParams<{ id: string }>()`. |
| 42 | +- `app/blog/[...slug].tsx` is a catch-all, captures `slug` as `string[]`. |
| 43 | +- Optional catch-all: `app/blog/[[...slug]].tsx` matches both `/blog` and `/blog/a/b`. |
| 44 | + |
| 45 | +## Linking and navigation |
| 46 | + |
| 47 | +- `<Link href="/settings">` is the declarative way. It compiles to `<a>` on web, `<Pressable>` on native. |
| 48 | +- `useRouter()` gives imperative `router.push()`, `router.replace()`, `router.back()`, `router.dismiss()`. |
| 49 | +- Prefer `<Link>` for static destinations — it gets correct accessibility on web. |
| 50 | +- Use `router.replace()` for auth flows so the user can't swipe-back to the login screen. |
| 51 | + |
| 52 | +## Search params and typed routes |
| 53 | + |
| 54 | +- Read query params with `useLocalSearchParams<{ q?: string }>()`. They are always strings. |
| 55 | +- For type safety across the whole router, enable typed routes in `app.json`: `"experiments": { "typedRoutes": true }`. Then `href` is autocompleted and unknown paths are type errors. |
| 56 | +- `useGlobalSearchParams` (rarely needed) reads params from the closest matching route, not the current screen. |
| 57 | + |
| 58 | +## Modals and presentation styles |
| 59 | + |
| 60 | +- Modal: `<Stack.Screen name="modal" options={{ presentation: "modal" }} />`. On iOS this slides up; on web it renders as a normal page (style yourself if you want overlay behavior). |
| 61 | +- Transparent modal: `presentation: "transparentModal"` with a Pressable backdrop. |
| 62 | +- Always provide a close affordance — modals on Android close on hardware back, but not all web browsers respect that. |
| 63 | + |
| 64 | +## Authentication patterns |
| 65 | + |
| 66 | +- Use `<Redirect href="/login" />` inside layouts to gate subtrees. |
| 67 | +- For an auth context, wrap providers in `app/_layout.tsx` so they're available to every route. |
| 68 | +- After login, call `router.replace("/(tabs)")` so the auth stack isn't in history. |
| 69 | +- Don't read auth state inside the layout's render and conditionally render `<Redirect>` and routes in the same pass — extract a guard component to avoid flicker. |
| 70 | + |
| 71 | +## Web compatibility |
| 72 | + |
| 73 | +- Files must compile for native AND web. Don't import native-only APIs at the top of a route file — lazy-load with `Platform.OS === 'web'` checks or use `.web.tsx` / `.native.tsx` extensions. |
| 74 | +- For SEO on web, set `<head>` tags inside the route: `import { Stack } from "expo-router"; <Stack.Screen options={{ title: "Page title" }} />` translates to `<title>` on web. |
| 75 | +- Deep linking: configure `scheme` in `app.json`. The router uses the same URL structure on web and native — `/post/123` matches both. |
| 76 | + |
| 77 | +## Common pitfalls |
| 78 | + |
| 79 | +- "Route not found": every leaf route file must default-export a component. Layouts must default-export too. |
| 80 | +- "useLocalSearchParams undefined": params are strings only. Parse to numbers manually. They are `undefined` on the first render of a freshly-pushed route — guard for it. |
| 81 | +- "Two routes match": avoid having both `app/post/[id].tsx` and `app/post/index.tsx` if the index should redirect — use `<Redirect>` explicitly. |
| 82 | +- "Tabs render briefly during auth check": move the auth check into a layout that renders a loading state, not into the tab screens themselves. |
| 83 | +- "Web hot reload loses scroll": expected — use `scrollRestoration` patterns or `react-native-screens` scroll restoration on web. |
| 84 | + |
| 85 | +## Don'ts |
| 86 | + |
| 87 | +- Don't use React Navigation `useNavigation()` types directly. Use `useRouter()` from `expo-router` so types match. |
| 88 | +- Don't manually call `useEffect(() => router.push(...))` for redirects on first render. Use `<Redirect>` instead — it's synchronous and SSR-safe. |
| 89 | +- Don't put business logic in `_layout.tsx`. Layouts should be thin and only set up navigators, providers, and gates. |
| 90 | + |
| 91 | +## Reference |
| 92 | + |
| 93 | +- Docs: https://docs.expo.dev/router/introduction/ |
| 94 | +- API: https://docs.expo.dev/router/reference/ |
0 commit comments