Search across all documentation pages
File-based routing conventions and deep-link hygiene for Expo Router on Expo SDK 57. These rules keep navigation predictable as the app/ tree grows, prevent auth and param bugs from malformed URLs, and ensure store builds handle universal links correctly on iOS and Android.
app/ or adding a new route group - layout mistakes are expensive to unwind.app/, Link, router.push, or app.config scheme settings.Route files re-export feature screens: app/(tabs)/orders/index.tsx imports OrdersScreen from features/orders - no hooks, fetch calls, or Redux in route files.
app/.One root _layout.tsx owns global providers: Theme, auth session, query client, and error boundaries mount once at app/_layout.tsx - not repeated in every nested layout.
<Slot /> or stack - document the sequence in README.QueryClientProvider in tab and stack layouts.Nested layouts handle chrome only: Tab _layout.tsx defines icons and tab bar; stack _layout.tsx sets headerShown and transitions - not feature data fetching.
useFocusEffect refetch belongs in the screen component, not _layout.tsx.Use route groups for organization, not runtime behavior: (auth), (tabs), and (modals) group files without affecting the URL path - parentheses folders are for structure.
order-detail.tsx → /order-detail.app/team-a/feature-b/...).Index routes for list hubs; dynamic segments for entities: orders/index.tsx lists orders; orders/[id].tsx shows one order - predictable REST-like URLs aid deep linking and analytics.
[...slug].tsx for CMS or legacy URL support - validate segments immediately./orders/123 not /orders?id=123).Colocate loading and error UI with routes when using Suspense boundaries: orders/[id].tsx can export a parallel orders/[id]/loading.tsx or handle skeletons in the screen - do not leave blank flashes during navigation.
isLoading prop; route wires suspense if adopted.renderRouter for critical stacks.Prefer href objects over string paths: router.push({ pathname: '/orders/[id]', params: { id } }) - typed routes catch typos at compile time when experiments.typedRoutes is enabled.
experiments: { typedRoutes: true } in app.config for SDK 57 projects.router.push('/orders/' + id) without param validation.Use Link for declarative navigation; router for imperative: Link preserves accessibility and prefetch semantics - imperative router.replace only after mutations or auth redirects.
router.replace after login/logout - push duplicates auth screens on back gesture.router.push inside onPress when Link with asChild and Pressable suffices.Centralize route constants in one module: routes.ts exports href builders - features import orderDetailHref(id) instead of scattering path strings.
packages/navigation for white-label apps with identical route shapes.'/settings/account' in twelve files.Modal and presentation routes are explicit: Full-screen modals get a (modals) group or presentation: 'modal' in stack options - half-implemented overlays confuse Android back behavior.
Modal vs a route-based modal.Protect authenticated routes in layout, not per-screen guards: (app)/_layout.tsx checks session and redirects to /(auth)/login - individual screens should not each duplicate auth checks.
router.replace.if (!user) return null in every protected screen without redirect.Handle initial URL and cold-start deep links once: useURL() or Expo Router's linking config resolves the launch URL - do not parse Linking.getInitialURL() in every screen.
myapp://orders/42 from outside the app.Declare scheme in app.config before shipping custom URL schemes: scheme: "acme" enables acme:// links - must match marketing and QA documentation.
scheme: ["acme", "acme-dev"] for environment variants - not one scheme for all builds.npx uri-scheme list after prebuild.Configure associated domains for universal links (iOS) and app links (Android): ios.associatedDomains and android.intentFilters in app.config - hand-editing native files breaks on CNG prebuild.
expo-router plugin and documented associated-domain plugins.apple-app-site-association hosted and validated.Validate route params at the feature boundary: Zod (or similar) parses useLocalSearchParams() before rendering - malformed deep links show a friendly error, not a redbox.
const { id } = orderParamsSchema.parse(params) in OrderDetailScreen.Never trust query-string input for security decisions: Deep-link ?admin=true does not grant admin - authorize on the server and in session state.
if (params.promo) applying discounts without server validation.Document supported deep-link matrix in README: Path, required params, auth requirement, and example URL per route - support and marketing depend on this table.
Fallback route for unknown paths: [...unmatched].tsx or +not-found.tsx shows recoverable UI with a link home - default 404 redboxes hurt store reviews.
myapp://does-not-exist in Maestro smoke.Lazy-load heavy tab screens when tabs are rarely visited: Dynamic import() for settings sub-screens or admin tools - not for primary revenue tabs users open every session.
Avoid navigation state in global mutable singletons: Pass params via router or feature stores - module-level let pendingOrderId breaks on fast navigations and OTA reloads.
global.pendingDeepLink set in one file, read in another.Reset stack on logout: router.dismissAll() or replace to auth stack - back gesture must not return to authenticated screens with a cleared token.
Do not block first paint on navigation font/icon loading: Load tab icons from static assets; defer custom font routes until root layout finishes useFonts.
null until fonts load - child routes do not duplicate font gates.if (!fontsLoaded) return null mid-hook-order in a screen (hooks rule violation).E2E smoke covers three deep-link paths: Launch, auth-gated path, and primary entity detail - Maestro YAML against EAS preview builds, not Expo Go alone.
appId to bundle identifier from app.config.PR checklist for routing changes: Renamed file? Updated deep-link matrix? Param schema test? Android back on modals? - attach to routing PR template.
Always in features/ - app/ is a routing table. Route files import and re-export screens; they do not fetch data or own hooks beyond trivial wiring.
Set experiments: { typedRoutes: true } in app.config and use href objects with router.push and Link. Run npx expo customize tsconfig.json if the template has not already.
In a dedicated layout ((app)/_layout.tsx or (auth)/_layout.tsx) that checks session once and calls router.replace. Avoid per-screen useEffect redirects that race on cold start.
Custom schemes (acme://) are easier to test but can be hijacked on some Android versions. Universal/app links (https://app.acme.com/...) are required for email and web-to-app campaigns - configure both for production apps.
Parse useLocalSearchParams() with Zod at the top of the feature screen. Show a 404 or error state on failure. Add Jest tests for the schema - not Maestro for every invalid param.
Route-based modals participate in deep linking and Android back - prefer them for shareable flows. RN Modal is fine for ephemeral pickers with no URL representation. Document the choice in an ADR.
Yes in JS via OTA, but old URLs break unless you add redirects in [...unmatched].tsx or keep alias files. Treat route paths as a public API - version breaking changes.
One root plus one per major navigator (tabs, auth stack, modals group) is typical. More than four nested layouts usually means the tree should be flattened or route groups reorganized.
Yes on RN 0.86 and SDK 57 - navigation rules are unchanged. Test gestures and screen transitions on mid-tier Android when enabling New Architecture.
Expo Router supports redirect exports in route files for simple cases. Auth gates with async session hydration still belong in layout components that wait for auth state before rendering children.
Use @testing-library/react-native renderRouter for integration tests on critical stacks. Unit-test param schemas separately. Reserve Maestro for full deep-link cold-start flows.
Adding JS routes is OTA-safe. Changing scheme, associated domains, or intent filters requires a new native build and store submission.
Store the initial URL from useURL() or linking config in memory, complete login, then router.replace to the stored path. Clear the pending value after navigation to prevent loops.
app/ and project scaffolding rulesStack versions: This page was written for React 19.2.3, React Native 0.86.0, and Expo SDK 57 (
expo~57.0.4).
Reviewed by Chris St. John·Last updated Jul 9, 2026