Rutas tipadas de Expo Router

Expo Router puede generar tipos de TypeScript desde tu árbol de archivos app/. Cuando las rutas tipadas están habilitadas, las cadenas href, las llamadas router.push y los hooks de parámetros se verifican contra rutas reales - por lo que cambiar el nombre de un archivo de pantalla se convierte en un error de compilación en lugar de un 404 en tiempo de ejecución.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

// app.json - habilita rutas tipadas (beta; requerido en scaffolds antiguos)
{
  "expo": {
    "experiments": {
      "typedRoutes": true
    }
  }
}

# Regenera los tipos de ruta e incluye tsconfig
npx expo customize tsconfig.json
npx expo start

import { Link, router } from "expo-router";
 
// Autocompletado y validación en tiempo de compilación
<Link href="/settings" />
router.push("/settings");

Cuándo usarlo:

• Aplicaciones Expo Router de varias pantallas donde los enlaces rotos deberían fallar en CI, no en un dispositivo.
• Equipos que renombran, mueven o agrupan rutas frecuentemente con segmentos (tabs) y (auth).
• Segmentos dinámicos como app/user/[id].tsx donde las claves de parámetros deben coincidir con el nombre del archivo.
• Navegación imperativa (router.push, router.replace) compartida entre hooks y enlaces profundos.
• Monorepos que verifican tipos en móvil sin iniciar el servidor de desarrollo de Metro.

Ejemplo funcional

Supongamos este árbol de archivos:

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: "Inicio" }} />
      <Stack.Screen name="settings" options={{ title: "Configuración" }} />
      <Stack.Screen name="user/[id]" options={{ title: "Usuario" }} />
    </Stack>
  );
}

// app/index.tsx - enlaces declarativos con tipos Href generados
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}>Inicio</Text>
 
      <Link href="/settings" style={styles.link}>
        Configuración
      </Link>
 
      <Text
        style={styles.link}
        onPress={() => router.push({ pathname: "/user/[id]", params: { id: "42" } })}
      >
        Usuario 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 - parámetros fuertemente tipados de la ruta
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}>Usuario {id}</Text>
    </View>
  );
}
 
const styles = StyleSheet.create({
  screen: { flex: 1, padding: 24 },
  title: { fontSize: 22, fontWeight: "600" },
});

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

Lo que esto demuestra:

• Las rutas estáticas (/settings) autocompletan y rechazan errores tipográficos como /setings.
• Las rutas dinámicas usan hrefs de objeto con pathname y params estrictamente tipados.
• useLocalSearchParams<"/user/[id]">() vincula nombres de parámetros al segmento basado en archivo.
• tsconfig.json incluye .expo/types y expo-env.d.ts para que tsc --noEmit vea los tipos generados.
• Tanto <Link href> como router.push comparten la misma unión Href generada.

Análisis profundo

Cómo funciona

• Metro + Expo CLI escanean el directorio app/ (o src/app/ cuando se usa un layout src de nivel superior) y construyen un manifiesto de rutas.
• Con experiments.typedRoutes: true, CLI escribe declaraciones generadas en .expo/types y un expo-env.d.ts ignorado por git en la raíz del proyecto.
• El tipo global Href (y la Route exportada) representan cada ruta válida en el proyecto.
• <Link href>, router.push, router.replace y useRouter() consumen Href - las cadenas inválidas generan un error en el IDE.
• Los tipos se actualizan cuando inicia el servidor de desarrollo; no se envían a git de forma predeterminada.

Lista de verificación de configuración

Hrefs estáticos vs dinámicos

import { Link } from "expo-router";
 
// Estático - href de cadena
<Link href="/settings" />
 
// Dinámico - href de objeto con parámetros que coinciden con el nombre del segmento de archivo
<Link href={{ pathname: "/user/[id]", params: { id: userId } }} />
 
// Las cadenas de template funcionan cuando la expresión se escribe como Href
const id = "42";
<Link href={`/user/${id}` as const} />

Parámetros de consulta

Los parámetros de consulta no están en el sistema de archivos - escríbelos manualmente:

import { useLocalSearchParams } from "expo-router";
 
// Solo consulta
const { q } = useLocalSearchParams<{ q?: string }>();
 
// Ruta + consulta - el primer genérico es la ruta, el segundo es la forma de consulta
const { id, tab } = useLocalSearchParams<"/user/[id]", { tab?: "posts" | "about" }>();

Navegación relativa con useSegments

Las rutas tipadas requieren hrefs absolutos. Construye rutas relativas a las pestañas a partir de los segmentos actuales:

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

Notas de TypeScript

import { type Href, type Route } from "expo-router";
 
// Href - objetivos de navegación válidos
const settings: Href = "/settings";
 
// Route - coincide con cualquier cadena de ruta válida en el proyecto
const route: Route = "/user/123";
 
// Segmentos tipados para una rama de layout específica
import { useSegments } from "expo-router";
const segments = useSegments<"/(tabs)/profile">();

• Los tipos generados se aplican en archivos .tsx - los módulos simples .ts pueden no obtener autocompletado de Href a menos que importen los tipos explícitamente.
• Después de mover o renombrar archivos de ruta, reinicia expo start si el IDE muestra autocompletado obsoleto.
• expo-env.d.ts también aumenta los tipos de React Native Web (p.ej. className en View) cuando las rutas tipadas están habilitadas.

Errores comunes

• Omitir npx expo customize tsconfig.json - tsc --noEmit en CI no puede ver .expo/types y cada href se convierte en string. Solución: Ejecuta customize en CI antes de la verificación de tipos.
• Href de cadena a rutas dinámicas - href="/user/[id]" se verifica como inválida porque falta id. Solución: Usa { pathname: "/user/[id]", params: { id } }.
• Nombres de clave de parámetro incorrectos - El archivo es [id].tsx pero los parámetros usan { userId: "1" }. Solución: Las claves de parámetros deben coincidir exactamente con los nombres de segmentos entre corchetes.
• Enviar expo-env.d.ts a git - Se regenera por máquina y desordena los diffs. Solución: Déjalo ignorado por git; regenera en CI con expo customize.
• Quitar .expo/types de tsconfig - El autocompletado se rompe silenciosamente; las rutas inválidas se compilan. Solución: Mantén tanto .expo/types/**/*.ts como expo-env.d.ts en include.
• Hrefs relativos ./ - Las rutas tipadas no soportan rutas relativas. Solución: Rutas absolutas o rutas construidas con useSegments().
• Tipos obsoletos después de una gran refactorización de ruta - El IDE aún sugiere rutas eliminadas. Solución: Reinicia el servidor de desarrollo; ejecuta npx expo customize tsconfig.json si las rutas include cambiaron.

Alternativas

Preguntas frecuentes

<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" } });

Relacionado

• TypeScript en RN Basics - useLocalSearchParams<Params>() manual antes de tipos generados
• Escritura de navegación y parámetros de ruta - validación de parámetros y superposición de React Navigation
• Rutas tipadas - Guía de sección de Expo Router sobre enlaces y href
• Link & href - patrones de navegación declarativa
• Grupos de ruta y organización de app - cómo (groups) afectan las rutas generadas
• Escritura de respuestas de API y Zod - valida parámetros de enlace profundo en tiempo de ejecución

Versiones de stack: Esta página fue escrita para React 19.2.3, React Native 0.86.0 y Expo SDK 57 (expo ~57.0.4).