Expo Router Typed Routes

Expo Router can generate TypeScript types from your app/ file tree. When typed routes are enabled, href strings, router.push calls, and param hooks are checked against real routes - so a renamed screen file becomes a compile error instead of a runtime 404.

Recipe

Quick-reference recipe card - copy-paste ready.

// app.json - enable typed routes (beta; required on older scaffolds)
{
  "expo": {
    "experiments": {
      "typedRoutes": true
    }
  }
}

# Regenerate route types and tsconfig includes
npx expo customize tsconfig.json
npx expo start

import { Link, router } from "expo-router";
 
// Autocomplete and compile-time validation
<Link href="/settings" />
router.push("/settings");

When to reach for this:

• Multi-screen Expo Router apps where broken links should fail in CI, not on a device.
• Teams that rename, move, or group routes frequently with (tabs) and (auth) segments.
• Dynamic segments like app/user/[id].tsx where param keys must match the file name.
• Imperative navigation (router.push, router.replace) shared across hooks and deep links.
• Monorepos that typecheck mobile without starting the Metro dev server.

Working Example

Assume this file tree:

app/
  _layout.tsx
  index.tsx
  settings.tsx
  user/
    [id].tsx

// app/_layout.tsx
import { Stack } from "expo-router";
 
export default function RootLayout() {
  return (
    <Stack>
      <Stack.Screen name="index" options={{ title: "Home" }} />
      <Stack.Screen name="settings" options={{ title: "Settings" }} />
      <Stack.Screen name="user/[id]" options={{ title: "User" }} />
    </Stack>
  );
}

// app/index.tsx - declarative links with generated Href types
import { View, Text, StyleSheet } from "react-native";
import { Link, router } from "expo-router";
 
export default function HomeScreen() {
  return (
    <View style={styles.screen}>
      <Text style={styles.title}>Home</Text>
 
      <Link href="/settings" style={styles.link}>
        Settings
      </Link>
 
      <Text
        style={styles.link}
        onPress={() => router.push({ pathname: "/user/[id]", params: { id: "42" } })}
      >
        User 42
      </Text>
    </View>
  );
}
 
const styles = StyleSheet.create({
  screen: { flex: 1, padding: 24, gap: 12 },
  title: { fontSize: 22, fontWeight: "600" },
  link: { color: "#2563eb", fontSize: 16 },
});

// app/user/[id].tsx - strongly typed params from the route path
import { View, Text, StyleSheet } from "react-native";
import { useLocalSearchParams } from "expo-router";
 
export default function UserScreen() {
  const { id } = useLocalSearchParams<"/user/[id]">();
 
  return (
    <View style={styles.screen}>
      <Text style={styles.title}>User {id}</Text>
    </View>
  );
}
 
const styles = StyleSheet.create({
  screen: { flex: 1, padding: 24 },
  title: { fontSize: 22, fontWeight: "600" },
});

// tsconfig.json - after `npx expo customize tsconfig.json`
{
  "extends": "expo/tsconfig.base",
  "compilerOptions": { "strict": true },
  "include": [
    "**/*.ts",
    "**/*.tsx",
    ".expo/types/**/*.ts",
    "expo-env.d.ts"
  ]
}

What this demonstrates:

• Static routes (/settings) autocomplete and reject typos like /setings.
• Dynamic routes use object hrefs with pathname and strictly typed params.
• useLocalSearchParams<"/user/[id]">() ties param names to the file-based segment.
• tsconfig.json includes .expo/types and expo-env.d.ts so tsc --noEmit sees generated types.
• Both <Link href> and router.push share the same generated Href union.

Deep Dive

How It Works

• Metro + Expo CLI scan the app/ directory (or src/app/ when using a top-level src layout) and build a route manifest.
• With experiments.typedRoutes: true, CLI writes generated declarations into .expo/types and a git-ignored expo-env.d.ts at the project root.
• The global Href type (and exported Route) represent every valid path in the project.
• <Link href>, router.push, router.replace, and useRouter() consume Href - invalid strings error in the IDE.
• Types refresh when the dev server starts; they are not committed to git by default.

Setup Checklist

Static vs Dynamic Hrefs

import { Link } from "expo-router";
 
// Static - string href
<Link href="/settings" />
 
// Dynamic - object href with params matching the file segment name
<Link href={{ pathname: "/user/[id]", params: { id: userId } }} />
 
// Template strings work when the expression is typed as Href
const id = "42";
<Link href={`/user/${id}` as const} />

Query Parameters

Query params are not in the file system - type them manually:

import { useLocalSearchParams } from "expo-router";
 
// Query only
const { q } = useLocalSearchParams<{ q?: string }>();
 
// Route + query - first generic is the route, second is query shape
const { id, tab } = useLocalSearchParams<"/user/[id]", { tab?: "posts" | "about" }>();

Relative Navigation with useSegments

Typed routes require absolute hrefs. Build tab-relative paths from the current segments:

import { Link, useSegments } from "expo-router";
 
export function ProfileTabLink() {
  const [group] = useSegments(); // e.g. "(tabs)" or "(auth)"
  return <Link href={`/${group}/profile`}>Profile</Link>;
}

TypeScript Notes

import { type Href, type Route } from "expo-router";
 
// Href - valid navigation targets
const settings: Href = "/settings";
 
// Route - matches any valid route string in the project
const route: Route = "/user/123";
 
// Typed segments for a specific layout branch
import { useSegments } from "expo-router";
const segments = useSegments<"/(tabs)/profile">();

• Generated types apply in .tsx files - plain .ts modules may not get Href autocomplete unless they import the types explicitly.
• After moving or renaming route files, restart expo start if the IDE shows stale autocomplete.
• expo-env.d.ts also augments React Native Web types (e.g. className on View) when typed routes are enabled.

Gotchas

• Skipping npx expo customize tsconfig.json - tsc --noEmit in CI cannot see .expo/types and every href becomes string. Fix: Run customize in CI before typecheck.
• String href to dynamic routes - href="/user/[id]" typechecks as invalid because id is missing. Fix: Use { pathname: "/user/[id]", params: { id } }.
• Wrong param key names - File is [id].tsx but params use { userId: "1" }. Fix: Param keys must match bracket segment names exactly.
• Committing expo-env.d.ts - It is regenerated per machine and clutters diffs. Fix: Leave it gitignored; regenerate in CI with expo customize.
• Removing .expo/types from tsconfig - Autocomplete silently breaks; invalid routes compile. Fix: Keep both .expo/types/**/*.ts and expo-env.d.ts in include.
• Relative ./ hrefs - Typed routes do not support relative paths. Fix: Absolute paths or useSegments()-built paths.
• Stale types after a big route refactor - IDE still suggests deleted routes. Fix: Restart the dev server; run npx expo customize tsconfig.json if include paths changed.

Alternatives

FAQs

<Link href={{ pathname: "/user/[id]", params: { id: "42" } }} />

const id = "42";
router.push(`/user/${id}`);

import { useRouter } from "expo-router";
 
const router = useRouter();
router.push("/settings");
router.replace({ pathname: "/user/[id]", params: { id: "1" } });

Related

• TypeScript in RN Basics - manual useLocalSearchParams<Params>() before generated types
• Typing Navigation & Route Params - param validation and React Navigation overlap
• Typed Routes - Expo Router section guide to links and href
• Link & href - declarative navigation patterns
• Route Groups & Organizing app - how (groups) affect generated paths
• Typing API Responses & Zod - validate deep-link params at runtime

External Related Links

• docs.expo.dev - official Expo docs (recommended framework)
• reactnative.dev/docs - full RN documentation
• react.dev - core React concepts RN builds on

Stack versions: This page was written for React 19.2.3, React Native 0.86.0, and Expo SDK 57 (expo ~57.0.4).

383k393a3c3q3e393a3o1r3e3k3x383c3e3k221y1u3x1v1t1v1z1t20