Boas Práticas Fundamentais do Expo Router
Um resumo condensado das 25 práticas recomendadas mais importantes, extraídas de todas as páginas desta seção.
//
Busque em todas as páginas da documentação
Um resumo condensado das 25 práticas recomendadas mais importantes, extraídas de todas as páginas desta seção.
Estruture com Expo Router desde o início: default@sdk-57 define main: "expo-router/entry" - adaptar o roteamento baseado em arquivos posteriormente custa mais do que começar com app/.
Instale o router através do Expo: npx expo install expo-router fixa versões compatíveis com os peers do React Navigation do SDK 57 - intervalos manuais do npm causam assimetria nativa/JS.
Trate nomes de arquivos como URLs: app/settings.tsx → /settings - projete caminhos para deep links e análises antes que as pastas se proliferem.
Mantenha os arquivos de rota enxutos: Abaixo de ~20 linhas; reexporte telas de features/<nome>/ - revisores buscam em app/ para entender a navegação, não as regras de negócios.
Um único _layout.tsx raiz para providers: Tema, cliente de consulta, sessão de autenticação e limites de erro são montados uma vez - nunca duplique QueryClientProvider em layouts de abas.
Layouts aninhados gerenciam apenas o chrome: Cabeçalhos de stack, ícones de abas, rótulos de gaveta - não busca de dados. useFocusEffect refetch pertence às telas.
Use grupos de rotas para estrutura: (auth), (app), (tabs), (modals) - parênteses organizam sem poluir URLs.
Pastas privadas usam prefixo underscore: _components/ co-localizado com layouts não é roteável - nunca crie telas /components acidentais.
Rotas de índice para hubs de lista: orders/index.tsx lista; orders/[id].tsx detalha - caminhos previsíveis semelhantes a REST auxiliam na vinculação.
Hub de redirecionamento único em app/index.tsx: Roteamento de autenticação e de função vivem em um só lugar - evite arquivos de índice / duplicados entre grupos.
Aguarde a hidratação da sessão antes de redirecionar: Mostre splash ou spinner enquanto o SecureStore lê - <Redirect> prematuro causa flicker de login/home.
router.replace após login e logout: Preserva a higiene da pilha de retorno - push deixa telas de credenciais para trás no swipe-back.
Proteja grupos autenticados no layout: (app)/_layout.tsx redireciona convidados - deep links para /settings não devem contornar a autenticação.
Prefira Link para navegação declarativa: Listas, links inline e prefetch - reserve router.push para efeitos colaterais pós-assíncronos.
Centralize construtores de href: orderDetailHref(id) em navigation/hrefs.ts - uma correção de erro de digitação atualiza todas as chamadas de feature.
Habilite rotas tipadas cedo: experiments: { typedRoutes: true } em app.config.ts - caminhos inválidos falham tsc, não produção.
Valide parâmetros com Zod em tempo de execução: A entrada de useLocalSearchParams() não é confiável de deep links e payloads de push - tipos sozinhos são insuficientes.
Aninhe stacks dentro de abas para drill-down: Uma aba exibe telas de detalhes enquanto a barra de abas permanece - limite o aninhamento em drawer → tabs → stack.
Oculte rotas não-tab com href: null: Telas auxiliares permanecem navegáveis via router.push sem poluir a barra de abas.
Rotas de modal são explícitas: Grupo (modals) ou presentation: "modal" - sobreposições parciais quebram o back do Android e a acessibilidade.
Declare scheme antes de enviar deep links: O esquema app.config.ts e os domínios associados combinam com os caminhos de arquivo - teste fluxos do Maestro por URL crítica.
Execute tsc --noEmit quando app/ mudar: .expo/types regenerados capturam hrefs desatualizados - adicione ao CI junto com expo-doctor.
Alinhe app/ com fatias de features: features/orders/ mapeia para app/(tabs)/orders/ - regra de importação: rotas importam features, não o contrário.
Documente padrões não-padrão em ADRs: Modais como sobreposições, barras de abas personalizadas ou "escape hatches" do React Navigation - antes que a terceira equipe os copie.
Revise o mapa de rotas com ~30 telas: Achate árvores profundas, divida modais e audite caminhos duplicados - agende antes que ciclos de importação e rotas / duplicadas forcem uma reescrita.
Em features/<nome>/ - hooks, API e UI da tela. Arquivos app/ apenas reexportam. Providers globais vivem no _layout.tsx raiz ou app-providers.tsx.
app/*.tsx, exceto para guards de redirecionamento de autenticação.npx expo start --non-interactive &
npm run typecheckCertifique-se de que .expo/types gere antes de tsc em CI quando app/ mudar.
app/ - (auth) e pastas privadasHref geradosVersões de Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (
expo~57.0.4).
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026