Regras do Expo: Melhores Práticas
Um resumo condensado das 25 melhores práticas 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 melhores práticas mais importantes extraídas de todas as páginas desta seção.
Fixe o SDK no momento do scaffold: Use npx create-expo-app@latest --template default@sdk-57 para que expo comece em ~57.0.4 - atualizar três SDKs em um único PR acumula alterações que quebram compatibilidade.
app.config.ts é a fonte da verdade: A configuração dinâmica suporta ambientes, plugins e helpers tipados - execute npx expo config --type public antes de cada submissão para a loja.
Nunca comite segredos em extra ou EXPO_PUBLIC_*: Pacotes do cliente expõem esses valores - segredos do servidor pertencem apenas ao EAS Secrets e ao código do backend.
Comite lockfiles e use npx expo install: CI e EAS devem resolver a mesma árvore de dependências - npm install manual em pacotes do Expo distorce os binários nativos.
Mantenha app/ enxuto; features possuem a lógica: Arquivos de rota reexportam telas de features/<nome>/ - sem chamadas de fetch, hooks ou regras de negócio ao lado de _layout.tsx.
Gitignore ios/ e android/ sob CNG: Pastas nativas comitadas bloqueiam os templates de prebuild do RN 0.86 - regenere no EAS Build ou expo prebuild --clean.
Execute expo-doctor na CI em cada PR: Detecta descompasso de versões, configuração inválida e erros de dependência antes que cheguem ao TestFlight.
Prefira objetos href e rotas tipadas: Habilite experiments.typedRoutes - router.push({ pathname: '/orders/[id]', params: { id } }) é melhor que caminhos de string que falham silenciosamente por erro de digitação.
Valide parâmetros de rota na fronteira da feature: Analise useLocalSearchParams() com Zod antes da renderização - deep links malformados mostram UI recuperável, não redboxes.
Gates de autenticação vivem nos layouts; resete a pilha no logout: Um redirecionamento em (app)/_layout.tsx - router.replace após o logout para que o gesto de voltar nunca retorne a PII com um token limpo.
Declare scheme e domínios associados em app.config: Universal links e esquemas customizados são território de config-plugins - não arquivos nativos gerados editados manualmente.
Pesquise pacotes do Expo SDK antes de escrever código nativo: Use npx expo install expo-* primeiro - Swift/Kotlin customizados exigem reconstruções do dev-client, ADRs e propriedade contínua.
Expresse mudanças nativas como config plugins idempotentes: Editar manualmente Info.plist ou AndroidManifest.xml é perdido no prebuild --clean - plugins devem ser seguros em execuções repetidas.
Reconstrua clientes de desenvolvimento após cada mudança de dependência nativa: Atualizações OTA são apenas JavaScript - novos módulos nativos precisam de eas build --profile development antes da aprovação de QA.
Expo Go não é um alvo de QA nativo: Módulos customizados e IDs de bundle reais exigem builds de dev-client ou preview EAS - Expo Go esconde o comportamento de linking e permissões de produção.
Armazene tokens em expo-secure-store: Tokens de refresh e acesso nunca vão para AsyncStorage ou MMKV não criptografado - limpe o armazenamento seguro no logout.
Audite a configuração pública antes do lançamento: Execute npx expo config --type public com o ambiente de produção - use grep na CI para sk_live, chaves privadas e hostnames internos.
Padrão para TLS do sistema; fixe apenas com um ADR: O pinning de certificado exige runbooks de rotação e módulos nativos - a maioria dos aplicativos não deve fixar desde o primeiro dia.
Defina política explícita de runtimeVersion: appVersion, sdkVersion ou fingerprint devem corresponder entre eas build e eas update - discrepâncias deixam usuários presos em pacotes desatualizados.
Canais mapeiam para ambientes, não pessoas: development → preview → production com um período de teste preview - use eas update --environment production em runners SDK 55+.
Mudanças nativas exigem builds para loja: Novos módulos, plugins, permissões e esquemas nunca são apenas OTA - controle o acesso a novas APIs nativas via JS apenas após o limiar de adoção do binário.
Defina gatilhos de rollback antes do lançamento: Taxa de crash, falhas de autenticação e quedas de pagamento cada um tem um responsável, métrica limite e o último ID de bundle conhecido como bom.
Publique orçamentos de performance com responsáveis nomeados: MB do bundle, TTI de cold-start e FPS de scroll são portões de merge - orçamentos anônimos são ignorados na semana de pico.
Meça em dispositivos de referência Android de gama média: iPhone Pro esconde jank e pressão de memória - se passar em hardware classe Pixel, o iOS geralmente segue.
ADR para cada escolha arquitetural não padrão: Módulos nativos customizados, pinning, ios/ comitado, isenções de orçamento e padrões de modal recebem registros em docs/adr/ com datas de revisitação obrigatórias.
Anexe a página de checklist relevante ao template de PR - projeto, roteamento, nativo, segurança, lançamento ou performance. Bloqueie o merge em violações de Nível 1, a menos que um ADR esteja vinculado.
Segredos, lockfiles, posicionamento ilegal de hooks em listas, falta de secure store para tokens e OTA de produção no canal errado são bloqueadores. Isenções de performance e omissões de pinning precisam de exceções de ADR com data de expiração.
Sim - adicione uma instância react-native, projectId EAS por app e regras de fronteira para imports entre features. Customização do Metro espera até que a configuração automática do SDK 57 falhe.
Leia o Expo Project Rules Checklist Nível 1, depois Navigation & Routing Rules antes de adicionar telas.
Checklists definem os padrões que a equipe aplica. ADRs documentam exceções aprovadas com rollback e revisitação - vincule ADRs de PRs que se desviam.
Versões da 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: 9 de jul. de 2026