Expo Router skill for Codex

Done well means: the URL of every screen is predictable from the file tree, each layout owns exactly one navigator, auth gating happens in one place, and every deep link the app advertises has been opened on a simulator and lands on the right screen with a working back button.

Inspect first

cat AGENTS.md 2>/dev/null
grep -E '"expo-router"|"expo"' package.json
grep -E '"scheme"|typedRoutes|"origin"' app.json app.config.* 2>/dev/null
find app -name '*.tsx' -o -name '*.ts' | sort        # the route tree

Print the tree before editing; the file layout is the navigation config.

File conventions

File	URL	Notes
app/_layout.tsx	wraps everything	Root providers, fonts, root Stack
app/index.tsx	/
app/settings.tsx	/settings
app/user/[id].tsx	/user/42	useLocalSearchParams<{ id: string }>()
app/docs/[...slug].tsx	/docs/a/b/c	slug is string[]
app/(tabs)/_layout.tsx	no segment	Group: organises files, adds no path
app/+not-found.tsx	any unmatched URL	Always provide one
app/+native-intent.tsx	n/a	Rewrite incoming native deep links before routing
app/api/hello+api.ts	/api/hello	Server route; needs web.output: "server" and a host

Groups let two files share a URL shape with different navigators, e.g. (auth)/login.tsx and (app)/(tabs)/home.tsx.

Layouts

// app/_layout.tsx
import { Stack } from 'expo-router';
import { SessionProvider, useSession } from '@/auth/session';

export const unstable_settings = { anchor: '(app)' }; // screen under a deep-linked modal

function RootNavigator() {
  const { session, isLoading } = useSession();
  if (isLoading) return null;                          // or keep the splash screen up
  return (
    <Stack screenOptions={{ headerShown: false }}>
      <Stack.Protected guard={!!session}>
        <Stack.Screen name="(app)" />
        <Stack.Screen name="modal" options={{ presentation: 'modal', headerShown: true }} />
      </Stack.Protected>
      <Stack.Protected guard={!session}>
        <Stack.Screen name="(auth)" />
      </Stack.Protected>
    </Stack>
  );
}

export default function RootLayout() {
  return (
    <SessionProvider>
      <RootNavigator />
    </SessionProvider>
  );
}

// app/(app)/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';
import { Ionicons } from '@expo/vector-icons';

export default function TabsLayout() {
  return (
    <Tabs screenOptions={{ tabBarActiveTintColor: '#0a7' }}>
      <Tabs.Screen name="index" options={{ title: 'Home',
        tabBarIcon: ({ color, size }) => <Ionicons name="home" color={color} size={size} /> }} />
      <Tabs.Screen name="inbox" options={{ title: 'Inbox' }} />
    </Tabs>
  );
}

Rules:

• Protected routes (Stack.Protected / Tabs.Protected, available in recent SDKs) are the default for auth. When the guard flips, the router redirects away from screens that became inaccessible. On older SDKs, use <Redirect href="/login" /> in a group layout.
• Screens listed in a layout only configure options; files without an entry are still routable. Hide a tab with options={{ href: null }}.
• Put the nested Stack for a tab inside that tab’s folder ((tabs)/inbox/_layout.tsx) so pushing a detail screen keeps the tab bar.

Navigating and params

import { Link, router, useLocalSearchParams } from 'expo-router';

<Link href={{ pathname: '/user/[id]', params: { id: user.id } }}>Profile</Link>
router.push('/settings');
router.replace('/(app)/(tabs)');       // no back entry: use after login
router.dismissTo('/inbox');            // pop until a route, or push it if absent
if (router.canGoBack()) router.back();

const { id } = useLocalSearchParams<{ id: string }>();

Need	Use
Params of this screen	useLocalSearchParams (does not update when other screens change)
Params of the focused route anywhere	useGlobalSearchParams (re-renders on every navigation; use sparingly)
Current path for analytics	usePathname() + useEffect
Run code when a screen gains focus	useFocusEffect(useCallback(() => {...}, []))

• Params are strings (or string arrays). Parse and validate numbers, booleans and JSON. Pass IDs, never whole objects: anything in params ends up in the URL and in deep links.
• Enable typed routes with "experiments": { "typedRoutes": true } in app config; the dev server generates the types so a mistyped href fails tsc.

Deep links

1. Set scheme in app config ("scheme": "acme"). Changing it needs a new native build.
2. A link acme://user/42 resolves to app/user/[id].tsx with no extra code.
3. For universal links / Android App Links, add ios.associatedDomains and android.intentFilters with autoVerify, and host the AASA and assetlinks.json files. Domain setup belongs to $mobile-deep-links.
4. Rewrite legacy or third-party URL shapes in app/+native-intent.tsx:

export function redirectSystemPath({ path, initial }: { path: string; initial: boolean }) {
  try {
    const url = new URL(path, 'acme://app');
    if (url.pathname.startsWith('/p/')) return `/product/${url.pathname.slice(3)}`;
    return path;
  } catch {
    return '/';                                  // never throw here: the app would not open
  }
}

Test on simulators (the dev build must be installed):

npx uri-scheme open "acme://user/42" --ios
xcrun simctl openurl booted "acme://user/42"
adb shell am start -W -a android.intent.action.VIEW -d "acme://user/42" com.acme.app

Check both cold start (app killed) and warm start (app backgrounded). When a link deep inside a stack opens with no back button, set unstable_settings with an anchor or initialRouteName in that layout so a parent screen is inserted beneath it.

Migrating from React Navigation

• Map each navigator to a folder with a _layout.tsx; each screen component becomes a file whose default export is the screen.
• Replace navigation.navigate('Profile', { id }) with router.push({ pathname: '/user/[id]', params: { id } }). Replace route.params with useLocalSearchParams.
• Delete the manual linking config: file paths are the linking config. Keep a list of previously published URLs and redirect old shapes in +native-intent.tsx.
• Migrate one navigator at a time; the router is built on React Navigation, so screenOptions and most listeners carry over.

Gotchas

• A route file must default-export a component. Helpers in app/ become routes: keep components, hooks and utils outside app/.
• Two files resolving to the same URL ((a)/home.tsx and (b)/home.tsx) is ambiguous; the router warns and picks one. Keep URLs unique unless you mean shared routes.
• Navigating during the first render of the root layout throws “navigate before mounting”. Use <Redirect> or protected routes instead of router.replace in a top-level effect.
• Keep the splash screen visible (SplashScreen.preventAutoHideAsync()) until fonts and session load, or users see a flash of the login screen.
• router.push to the current route with new params pushes a duplicate; use router.setParams to update in place.

Verification

npx tsc --noEmit                 # with typedRoutes, catches broken hrefs
npx expo start                   # open each changed route; then test the deep links above
npx expo export --platform web   # if web is a target: static routes must render

Done when every new route opens from the UI and from its deep link (cold and warm), the back button returns somewhere sensible, signed-out users cannot reach protected screens, and unknown URLs show +not-found.

Output: route map

When adding or restructuring routes, report the resulting map:

| URL | File | Navigator | Auth |
|---|---|---|---|
| / | app/(app)/(tabs)/index.tsx | Tabs > Stack | signed in |
| /user/[id] | app/(app)/user/[id].tsx | Stack | signed in |
| /login | app/(auth)/login.tsx | Stack | signed out |
Deep links tested: acme://user/42 (cold, warm), https://acme.app/p/9 (rewritten)