Rotas Tipadas do Expo Router

O Expo Router pode gerar tipos TypeScript a partir da sua árvore de arquivos app/. Quando as rotas tipadas estão ativadas, strings href, chamadas router.push e hooks de parâmetros são verificados contra rotas reais - assim, um arquivo de tela renomeado se torna um erro de compilação em vez de um 404 em tempo de execução.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// app.json - ative as rotas tipadas (beta; necessário em scaffolds mais antigos)
{
  "expo": {
    "experiments": {
      "typedRoutes": true
    }
  }
}

# Regenerar tipos de rota e inclusões do tsconfig
npx expo customize tsconfig.json
npx expo start

import { Link, router } from "expo-router";
 
// Autocomplete e validação em tempo de compilação
<Link href="/settings" />
router.push("/settings");

Quando usar isso:

• Aplicativos Expo Router com várias telas onde links quebrados devem falhar no CI, não no dispositivo.
• Equipes que renomeiam, movem ou agrupam rotas frequentemente com segmentos (tabs) e (auth).
• Segmentos dinâmicos como app/user/[id].tsx onde as chaves de parâmetros devem corresponder ao nome do arquivo.
• Navegação imperativa (router.push, router.replace) compartilhada entre hooks e deep links.
• Monorepos que fazem typecheck de mobile sem iniciar o servidor de desenvolvimento Metro.

Exemplo de Trabalho

Assuma esta árvore de arquivos:

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 - links declarativos com tipos Href gerados
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 - parâmetros fortemente tipados do caminho da rota
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 - após `npx expo customize tsconfig.json`
{
  "extends": "expo/tsconfig.base",
  "compilerOptions": { "strict": true },
  "include": [
    "**/*.ts",
    "**/*.tsx",
    ".expo/types/**/*.ts",
    "expo-env.d.ts"
  ]
}

O que isso demonstra:

• Rotas estáticas (/settings) autocompletam e rejeitam erros de digitação como /setings.
• Rotas dinâmicas usam hrefs de objeto com pathname e params estritamente tipados.
• useLocalSearchParams<"/user/[id]">() vincula os nomes dos parâmetros ao segmento baseado em arquivo.
• tsconfig.json inclui .expo/types e expo-env.d.ts para que tsc --noEmit veja os tipos gerados.
• Tanto <Link href> quanto router.push compartilham a mesma união Href gerada.

Mergulho Profundo

Como Funciona

• Metro + Expo CLI escaneiam o diretório app/ (ou src/app/ ao usar um layout de nível superior src) e constroem um manifesto de rota.
• Com experiments.typedRoutes: true, a CLI escreve declarações geradas em .expo/types e um expo-env.d.ts ignorado pelo git na raiz do projeto.
• O tipo global Href (e o exportado Route) representam todos os caminhos válidos no projeto.
• <Link href>, router.push, router.replace e useRouter() consomem Href - strings inválidas geram erro no IDE.
• Os tipos são atualizados quando o servidor de desenvolvimento inicia; eles não são commitados no git por padrão.

Checklist de Configuração

Hrefs Estáticos vs. Dinâmicos

import { Link } from "expo-router";
 
// Estático - href de string
<Link href="/settings" />
 
// Dinâmico - href de objeto com parâmetros correspondendo ao segmento do arquivo
<Link href={{ pathname: "/user/[id]", params: { id: userId } }} />
 
// Modelos de string funcionam quando a expressão é tipada como Href
const id = "42";
<Link href={`/user/${id}` as const} />

Parâmetros de Query

Parâmetros de query não estão no sistema de arquivos - tipifique-os manualmente:

import { useLocalSearchParams } from "expo-router";
 
// Apenas Query
const { q } = useLocalSearchParams<{ q?: string }>();
 
// Rota + query - o primeiro genérico é a rota, o segundo é a forma da query
const { id, tab } = useLocalSearchParams<"/user/[id]", { tab?: "posts" | "about" }>();

Navegação Relativa com useSegments

Rotas tipadas exigem hrefs absolutos. Construa caminhos relativos à aba a partir dos segmentos atuais:

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

Notas de TypeScript

import { type Href, type Route } from "expo-router";
 
// Href - destinos de navegação válidos
const settings: Href = "/settings";
 
// Route - corresponde a qualquer string de rota válida no projeto
const route: Route = "/user/123";
 
// Segmentos tipados para um ramo de layout específico
import { useSegments } from "expo-router";
const segments = useSegments<"/(tabs)/profile">();

• Tipos gerados se aplicam em arquivos .tsx - módulos .ts simples podem não obter autocomplete Href a menos que importem os tipos explicitamente.
• Após mover ou renomear arquivos de rota, reinicie expo start se o IDE mostrar autocomplete desatualizado.
• expo-env.d.ts também aumenta os tipos do React Native Web (ex: className em View) quando rotas tipadas estão ativadas.

Armadilhas

• Pular npx expo customize tsconfig.json - tsc --noEmit no CI não pode ver .expo/types e todo href se torna string. Correção: Execute customize no CI antes do typecheck.
• Href de string para rotas dinâmicas - href="/user/[id]" faz typecheck como inválido porque id está faltando. Correção: Use { pathname: "/user/[id]", params: { id } }.
• Nomes de parâmetros incorretos - O arquivo é [id].tsx mas os parâmetros usam { userId: "1" }. Correção: As chaves de parâmetros devem corresponder exatamente aos nomes dos segmentos entre colchetes.
• Commitar expo-env.d.ts - Ele é regenerado por máquina e polui os diffs. Correção: Deixe-o ignorado pelo git; regenere no CI com expo customize.
• Remover .expo/types do tsconfig - O autocomplete falha silenciosamente; rotas inválidas compilam. Correção: Mantenha ambos .expo/types/**/*.ts e expo-env.d.ts em include.
• Caminhos relativos ./ hrefs - Rotas tipadas não suportam caminhos relativos. Correção: Caminhos absolutos ou caminhos construídos com useSegments().
• Tipos desatualizados após um grande refator de rota - O IDE ainda sugere rotas excluídas. Correção: Reinicie o servidor de desenvolvimento; execute npx expo customize tsconfig.json se os caminhos de include mudaram.

Alternativas

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

Relacionados

• Básico de TypeScript em RN - useLocalSearchParams<Params>() manual antes dos tipos gerados
• Tipando Navegação e Parâmetros de Rota - validação de parâmetros e sobreposição do React Navigation
• Rotas Tipadas - guia da seção Expo Router sobre links e href
• Link & href - padrões de navegação declarativa
• Grupos de Rotas e Organizando o app - como (groups) afetam os caminhos gerados
• Tipando Respostas de API e Zod - valide parâmetros de deep link em tempo de execução

Versões do Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).