Melhores Práticas de Prebuild
Um resumo condensado das 25 melhores práticas mais importantes extraídas de todas as páginas em CNG e Prebuild - nunca edite manualmente arquivos gerados que você não consegue reproduzir.
//
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 em CNG e Prebuild - nunca edite manualmente arquivos gerados que você não consegue reproduzir.
Trate o CNG como o padrão no SDK 57: Mantenha app.config.ts, plugins de configuração e modules/ - não pastas ios/ e android/ editadas manualmente.
Ignore diretórios nativos no Gitignore: Adicione ios/ e android/ a .gitignore, a menos que um ADR de brownfield exija explicitamente projetos nativos commitados.
Entenda o padrão de regeneração limpa: npx expo prebuild exclui pastas nativas existentes antes de gerar - passe --no-clean apenas durante o trabalho controlado de migração.
Nunca edite arquivos gerados que você não consegue reproduzir: Se uma alteração não estiver na configuração ou em um plugin, ela será perdida na próxima prebuild limpa.
Expresse permissões em plugins: NSCameraUsageDescription, permissões do Android e entitlements pertencem ao array plugins - não a edições pós-prebuild no Xcode.
Escreva plugins de configuração idempotentes: Executar o prebuild duas vezes não deve duplicar entradas de manifesto ou linhas apply do Gradle - verifique a existência antes de cada adição.
Documente a ordem dos plugins em app.config.ts: Múltiplos plugins que tocam o mesmo arquivo nativo dependem da ordem de execução - comente o raciocínio.
Prefira plugins de configuração de biblioteca: expo-camera, expo-notifications e módulos Expo fornecem plugins mantidos para o SDK 57 - não os reinvente.
Use npx expo install para dependências nativas: npm install manual pode puxar versões JS incompatíveis com os binários nativos do SDK 57.
Execute expo-doctor antes do prebuild: Capture configurações inválidas e descompasso de versão antes de desperdiçar um ciclo de compilação no EAS ou localmente.
Use npx expo config --type introspect ao desenvolver plugins: Inspecione os resultados do mod sem geração nativa completa a cada salvamento.
Porte as diferenças nativas de brownfield para plugins antes do cutover: Inventarie cada alteração no Xcode/Gradle em comparação com uma prebuild nova - planilha com proprietários por linha.
Commite modules/ para código nativo personalizado: Módulos Expo locais são a fonte da verdade; ios/MyApp/ gerado é efêmero sob CNG.
Use expo run:ios / expo run:android para iteração nativa local: Envolve prebuild + compilação - reconstrua após alterações em Swift/Kotlin; Fast Refresh não atualiza o código nativo.
Reconstrua clientes de desenvolvimento após atualizações de SDK: expo-dev-client incorpora o runtime nativo - OTA não pode atualizá-lo após uma alteração no SDK ou dependência nativa.
Exclua pastas nativas obsoletas ao atualizar: Após npx expo install --fix em um novo SDK, rm -rf ios android antes do prebuild - os templates antigos visam a versão anterior do RN.
Atualize SDKs sequencialmente: Um SDK por PR - templates de prebuild e APIs de plugin mudam a cada lançamento; pular versões agrava a dor.
Commite lockfiles com cada alteração que afeta o nativo: CI, EAS e hashes de impressão digital devem resolver a mesma árvore de dependências que o desenvolvimento local.
Adote gates de impressão digital na CI: @expo/fingerprint detecta quando uma nova build nativa é necessária - não envie OTA para binários incompatíveis.
Use runtimeVersion.policy: "fingerprint" para OTA do CNG: Vincula a elegibilidade da atualização à impressão digital dos inputs nativos, não apenas ao semver quando os plugins mudam entre os lançamentos da loja.
Deixe o EAS Build executar o prebuild na CI: Envie a configuração + JS - não as pastas nativas geradas - a menos que a migração de brownfield esteja incompleta.
Mapeie perfis do eas.json para ambientes: development, preview e production devem alinhar credenciais e variáveis de ambiente com a impressão digital e os jobs de build.
Teste de fumaça em dispositivo físico após mesclagens de plugins: Simuladores perdem entitlements de push, App Links e problemas de assinatura que o prebuild sozinho não consegue capturar.
Emparelhe o trabalho nativo com as Regras de Módulos Nativos: Pesquise pacotes do SDK Expo e plugins de configuração antes de escrever Swift/Kotlin - módulos personalizados precisam de ADRs e proprietários.
Agende a migração CNG de brownfield antes do próximo SDK principal: O custo de mesclagem nativa manual cresce a cada lançamento - faça o cutover quando a planilha de auditoria estiver completa e o prebuild limpo passar.
eas update.eas build para produção e clientes de desenvolvimento.app.config.tsnpx expo config --type introspectnpx expo prebuild --no-install duas vezes - diferença zero na segunda execuçãoexpo run:ios ou build de desenvolvimento EAS para prova no dispositivoVersõ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: 16 de jul. de 2026