Fluxo de Trabalho do expo prebuild

Q: O expo prebuild é executado automaticamente no EAS Build?

Sim, quando ios/ e android/ não são enviados ou são ignorados pelo git. EAS executa a mesma avaliação de configuração e pipeline de plugins que o prebuild local.

Q: Qual é o loop de iteração nativa local mais rápido?

1. Edite app.config.ts ou o plugin 2. npx expo prebuild --platform 3. npx expo run: 4. Repita - use --no-install no prebuild apenas ao pular a compilação

Checklist operacional para npx expo prebuild no Expo SDK 57 - padrões de regeneração limpa, quando usar --no-clean, e como iterar localmente sem corromper projetos nativos. Use isto antes de atualizações de SDK, PRs de plugins de configuração e configuração inicial do dev-client.

Como Usar Este Checklist

Execute a Camada 1 antes de cada atualização de SDK ou clone novo - ios//android/ desatualizados de um template mais antigo do SDK bloqueiam RN 0.86.
Aplique a Camada 2 ao criar ou revisar plugins de configuração - plugins não idempotentes destroem projetos nativos na segunda execução.
Use a Camada 3 para iteração local do dia a dia com expo run:ios / expo run:android.
Registre exceções de brownfield (diretórios nativos commitados) em docs/adr/ - CNG é o caminho padrão no SDK 57.
Emparelhe com Regras de Módulos Nativos ao adicionar pacotes com código nativo.

Camada 1: Regeneração Limpa e Padrões do SDK 57 (1–6)

Entenda o padrão limpo do SDK 57: npx expo prebuild remove os diretórios ios/ e android/ existentes antes de gerar novos projetos.
- Desativar: npx expo prebuild --no-clean aplica atualizações de template sobre pastas existentes.
- Após o bump do SDK: Sempre use a limpeza padrão - nunca --no-clean em branches de atualização.
Exclua pastas nativas desatualizadas antes do prebuild de atualização: ios/ commitado do SDK 56 tem como alvo RN 0.85 Hermes e versões de Pod.
- Padrão CNG: rm -rf ios android e depois npx expo prebuild.
- Verifique: package.json mostra expo ~57.0.4 e react-native 0.86.0.
Execute expo-doctor antes do prebuild: Campos inválidos em app.config.ts falham tardiamente - o doctor detecta desvios de esquema precocemente.
- Portão: npx expo-doctor sai com zero antes de expo prebuild em scripts de atualização.
- Corrija: npx expo install --fix quando o doctor relatar desvio de versão.
Ignore diretórios nativos em .gitignore sob CNG: Equipes padrão não commitam ios/ e android/.
- .gitignore: Adicione ios/ e android/ na raiz do app.
- Rejeite: Edições Xcode de "correção rápida" que não estão codificadas em plugins de configuração.
Use --no-install para verificações de diff em CI: Pula pod install e sincronização Gradle - validação mais rápida da saída do plugin.
- Build completo local: Omita --no-install quando precisar compilar imediatamente após o prebuild.
- EAS Build: Construtores na nuvem executam etapas de instalação automaticamente.
Prebuild com escopo de plataforma ao iterar: --platform ios ou --platform android economiza tempo em trabalhos de plugins de plataforma única.
- Lançamento completo: Execute ambas as plataformas antes de mesclar alterações de plugin que tocam a configuração compartilhada.
- Rejeite: Mesclar plugins testados apenas em iOS sem verificação de prebuild do Android.

Camada 2: Plugins de Configuração e Idempotência (7–12)

Expresse alterações nativas como plugins: Permissões, entitlements, dependências Gradle e entradas de manifesto pertencem ao array plugins em app.config.ts.
- Inspecione: npx expo config --type introspect antes do prebuild completo.
- Mergulhe fundo: Plugins de Configuração em CNG.
Execute prebuild duas vezes para cada novo plugin: A segunda execução deve produzir zero diff na saída nativa.
- Teste: npx expo prebuild && npx expo prebuild - git diff ios android vazio na segunda passagem.
- Rejeite: Plugins de anexação de regex sem verificações de existência.
Documente a ordem dos plugins em comentários: Múltiplos plugins que tocam Info.plist ou build.gradle dependem da ordem de execução.
- Padrão: Entitlements base primeiro, plugins de recursos segundo, plugin de patch personalizado por último.
- Depure: Use bisect removendo plugins um por um quando o prebuild falhar.
Prefira plugins de biblioteca em vez de edições manuais: expo-camera, expo-notifications e a maioria dos módulos Expo fornecem plugins mantidos.
- Instale: npx expo install <package> - não npm install @latest.
- Referência: ../native-modules/config-plugins/config-plugins.md.
Migre edições manuais com --no-clean temporariamente: Ao portar alterações nativas de brownfield, use --no-clean enquanto desenvolve o plugin, depois verifique com limpeza completa.
- Concluído quando: O prebuild limpo reproduz o mesmo comportamento nativo da edição manual.
- Exclua: Patches nativos temporários assim que o plugin for implementado.
Nunca edite arquivos gerados que você não pode reproduzir: Se uma alteração não estiver na configuração ou em um plugin, ela será perdida em um prebuild limpo.
- ADR necessário: Qualquer arquivo nativo commitado fora do CNG deve documentar o proprietário e o caminho de atualização.
- Emparelhe: ../expo-rules/native-module-rules/native-module-rules.md Camada 2.

Camada 3: Loops de Iteração Local (13–18)

expo run:ios envolve prebuild + compilação: Gera ios/ se ausente, executa pod install, abre o build Xcode.
- Script: "ios:native": "expo run:ios" em package.json.
- Requer: Xcode e CocoaPods para builds iOS locais.
expo run:android envolve prebuild + Gradle: Mesmo fluxo para Android - gera android/ se ausente.
- Dispositivo: expo run:android --device para testes em hardware físico.
- Emulador: Certifique-se de que ANDROID_HOME e as plataformas SDK estejam instaladas.
Reconstrua o dev client após alterações nas dependências nativas: expo-dev-client incorpora código nativo - a recarga do Metro não é suficiente.
- Gatilho: Novo pacote npm nativo, bump de SDK ou plugin alterando entitlements.
- OTA não pode substituir: eas update envia apenas JS dentro do mesmo runtime.
Limpe o cache do Metro após alterações de configuração do prebuild: Caches desatualizados mascaram problemas de autolinking e resolução de configuração.
- Comando: npx expo start --clear após adicionar módulos nativos.
- Nuclear: rm -rf node_modules/.cache em erros persistentes do bundler.
Use npx expo config para depurar sem escrever arquivos: Mais rápido que o prebuild completo ao validar variantes de ambiente.
- Manifesto público: npx expo config --type public antes da submissão para a loja.
- Introspect: Veja os resultados dos mods que os plugins aplicarão.
Teste de fumaça em dispositivo físico após prebuild: Simuladores não capturam problemas de entitlement, push ou App Links.
- Matriz: Um dispositivo iOS + um dispositivo Android no mínimo após PRs de plugins.
- Complemento CI: EAS development profile constrói para colegas de equipe sem Xcode.

Camada 4: Portões de Atualização e Lançamento (19–24)

Atualizações sequenciais de SDK: Um SDK por vez - os templates de prebuild mudam por SDK.
- Sequência: expo install expo@^<sdk> → --fix → expo-doctor → excluir diretórios nativos → prebuild.
- Referência: ../expo-platform/upgrading-expo-sdk-versions/upgrading-expo-sdk-versions.md.
Commit de lockfiles com alterações de dependência relacionadas ao prebuild: expo install --fix atualiza package-lock.json - CI deve resolver a mesma árvore.
- Rejeite: PRs de atualização que alteram package.json sem lockfile.
- Verifique: npx expo install --check em scripts de higiene semanais.
EAS Build executa prebuild quando os diretórios nativos estão ausentes: Envie sem ios//android/ - o construtor na nuvem os gera.
- Opcional local: Equipes sem Xcode dependem inteiramente do EAS para compilação nativa.
- Mergulhe fundo: CNG em CI.
Impressão digital de alterações nativas para OTA/versão do runtime: Quando a impressão digital nativa muda, as atualizações OTA devem ter como alvo um novo runtime.
- Ferramenta: @expo/fingerprint - veja Detecção de Mudanças Nativas e Impressão Digital.
- Rejeite: Enviar OTA para binários compilados antes de um merge de plugin nativo.
Alinhamento da Nova Arquitetura: Os templates de prebuild do SDK 57 habilitam a Nova Arquitetura por padrão no RN 0.86.
- Verifique: Bibliotecas nativas de terceiros suportam TurboModules/Fabric antes de mesclar.
- Escape hatch: newArchEnabled: false requer ADR e reconstrução.
Lançamento na loja após merges que afetam o nativo: eas build de produção deve ser executado no mesmo commit que passou no prebuild local/EAS.
- Rejeite: Mesclar PRs de plugin sem um build de desenvolvimento verde na CI.
- Rollback: PRs nativos de propósito único mapeiam claramente para o rollback da versão da loja.

Camada 5: Brownfield e Migração (25–28)

Inventarie diffs nativos mantidos manualmente antes da adoção do CNG: Liste cada alteração Xcode e Gradle que não está na configuração.
- Saída: Planilha mapeando arquivo → plugin de configuração ou exceção ADR.
- Runbook: Migrando Projetos Nativos Manuais para CNG.
Use --no-clean apenas durante a migração, não em CI: A CI deve provar que o prebuild limpo é reproduzível.
- Portão final: rm -rf ios android && npx expo prebuild passa no branch de migração.
- Concluído quando: Diretórios nativos ignorados em git e o prebuild limpo é o único caminho.
Verificação de autolinking após migração: expo-modules-autolinking deve aparecer no Podfile gerado e settings.gradle.
- Corrija: npx expo prebuild --clean se as entradas de autolinking estiverem ausentes.
- Referência: ../native-modules/autolinking-and-expo-modules-core/autolinking-and-expo-modules-core.md.
Documente quem é o proprietário de regressões nativas pós-CNG: Engenheiro de plataforma ou líder mobile revisa PRs de plugins.
- CODEOWNERS: app.config.ts, plugins/ e qualquer código nativo em modules/.
- Onboarding: README declara o fluxo de trabalho CNG - sem edições silenciosas no Xcode.

FAQs

Quando devo usar --no-clean?

Iterando em um plugin de configuração ao portar uma edição nativa de brownfield.
Depurando atualizações incrementais de template sem exclusão/regeneração completa.
Nunca em branches de atualização de SDK ou validação de CI - use a limpeza padrão.

O expo prebuild é executado automaticamente no EAS Build?

Sim, quando ios/ e android/ não são enviados ou são ignorados pelo git.
EAS executa a mesma avaliação de configuração e pipeline de plugins que o prebuild local.

Qual é o loop de iteração nativa local mais rápido?

Edite app.config.ts ou o plugin
npx expo prebuild --platform <ios|android>
npx expo run:<platform>
Repita - use --no-install no prebuild apenas ao pular a compilação

Posso pular o prebuild se usar o Expo Go?

O Expo Go usa um binário nativo fixo - ele ignora seus plugins de configuração para entitlements nativos.
Código nativo personalizado requer prebuild + dev client - Expo Go não é um alvo de teste de produção.

Relacionados

Noções Básicas de Prebuild - dez exemplos para gerar projetos nativos a partir da configuração
Plugins de Configuração em CNG - mutações nativas compostas
Código Nativo Personalizado em CNG - quando commitar ios/ e android/
CNG em CI - EAS gera vs projetos nativos commitados
../expo-rules/expo-project-rules-checklist/expo-project-rules-checklist.md - não negociáveis da equipe
Melhores Práticas de Prebuild - resumo de 25 itens

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).

Como Usar Este Checklist

Execute a Camada 1 antes de cada atualização de SDK ou clone novo - ios//android/ desatualizados de um template mais antigo do SDK bloqueiam RN 0.86.
Aplique a Camada 2 ao criar ou revisar plugins de configuração - plugins não idempotentes destroem projetos nativos na segunda execução.
Use a Camada 3 para iteração local do dia a dia com expo run:ios / expo run:android.
Registre exceções de brownfield (diretórios nativos commitados) em docs/adr/ - CNG é o caminho padrão no SDK 57.
Emparelhe com Regras de Módulos Nativos ao adicionar pacotes com código nativo.

Camada 1: Regeneração Limpa e Padrões do SDK 57 (1–6)

Entenda o padrão limpo do SDK 57: npx expo prebuild remove os diretórios ios/ e android/ existentes antes de gerar novos projetos.
- Desativar: npx expo prebuild --no-clean aplica atualizações de template sobre pastas existentes.
- Após o bump do SDK: Sempre use a limpeza padrão - nunca --no-clean em branches de atualização.
Exclua pastas nativas desatualizadas antes do prebuild de atualização: ios/ commitado do SDK 56 tem como alvo RN 0.85 Hermes e versões de Pod.
- Padrão CNG: rm -rf ios android e depois npx expo prebuild.
- Verifique: package.json mostra expo ~57.0.4 e react-native 0.86.0.
Execute expo-doctor antes do prebuild: Campos inválidos em app.config.ts falham tardiamente - o doctor detecta desvios de esquema precocemente.
- Portão: npx expo-doctor sai com zero antes de expo prebuild em scripts de atualização.
- Corrija: npx expo install --fix quando o doctor relatar desvio de versão.
Ignore diretórios nativos em .gitignore sob CNG: Equipes padrão não commitam ios/ e android/.
- .gitignore: Adicione ios/ e android/ na raiz do app.
- Rejeite: Edições Xcode de "correção rápida" que não estão codificadas em plugins de configuração.
Use --no-install para verificações de diff em CI: Pula pod install e sincronização Gradle - validação mais rápida da saída do plugin.
- Build completo local: Omita --no-install quando precisar compilar imediatamente após o prebuild.
- EAS Build: Construtores na nuvem executam etapas de instalação automaticamente.
Prebuild com escopo de plataforma ao iterar: --platform ios ou --platform android economiza tempo em trabalhos de plugins de plataforma única.
- Lançamento completo: Execute ambas as plataformas antes de mesclar alterações de plugin que tocam a configuração compartilhada.
- Rejeite: Mesclar plugins testados apenas em iOS sem verificação de prebuild do Android.

Camada 2: Plugins de Configuração e Idempotência (7–12)

Expresse alterações nativas como plugins: Permissões, entitlements, dependências Gradle e entradas de manifesto pertencem ao array plugins em app.config.ts.
- Inspecione: npx expo config --type introspect antes do prebuild completo.
- Mergulhe fundo: Plugins de Configuração em CNG.
Execute prebuild duas vezes para cada novo plugin: A segunda execução deve produzir zero diff na saída nativa.
- Teste: npx expo prebuild && npx expo prebuild - git diff ios android vazio na segunda passagem.
- Rejeite: Plugins de anexação de regex sem verificações de existência.
Documente a ordem dos plugins em comentários: Múltiplos plugins que tocam Info.plist ou build.gradle dependem da ordem de execução.
- Padrão: Entitlements base primeiro, plugins de recursos segundo, plugin de patch personalizado por último.
- Depure: Use bisect removendo plugins um por um quando o prebuild falhar.
Prefira plugins de biblioteca em vez de edições manuais: expo-camera, expo-notifications e a maioria dos módulos Expo fornecem plugins mantidos.
- Instale: npx expo install <package> - não npm install @latest.
- Referência: ../native-modules/config-plugins/config-plugins.md.
Migre edições manuais com --no-clean temporariamente: Ao portar alterações nativas de brownfield, use --no-clean enquanto desenvolve o plugin, depois verifique com limpeza completa.
- Concluído quando: O prebuild limpo reproduz o mesmo comportamento nativo da edição manual.
- Exclua: Patches nativos temporários assim que o plugin for implementado.
Nunca edite arquivos gerados que você não pode reproduzir: Se uma alteração não estiver na configuração ou em um plugin, ela será perdida em um prebuild limpo.
- ADR necessário: Qualquer arquivo nativo commitado fora do CNG deve documentar o proprietário e o caminho de atualização.
- Emparelhe: ../expo-rules/native-module-rules/native-module-rules.md Camada 2.

Camada 3: Loops de Iteração Local (13–18)

expo run:ios envolve prebuild + compilação: Gera ios/ se ausente, executa pod install, abre o build Xcode.
- Script: "ios:native": "expo run:ios" em package.json.
- Requer: Xcode e CocoaPods para builds iOS locais.
expo run:android envolve prebuild + Gradle: Mesmo fluxo para Android - gera android/ se ausente.
- Dispositivo: expo run:android --device para testes em hardware físico.
- Emulador: Certifique-se de que ANDROID_HOME e as plataformas SDK estejam instaladas.
Reconstrua o dev client após alterações nas dependências nativas: expo-dev-client incorpora código nativo - a recarga do Metro não é suficiente.
- Gatilho: Novo pacote npm nativo, bump de SDK ou plugin alterando entitlements.
- OTA não pode substituir: eas update envia apenas JS dentro do mesmo runtime.
Limpe o cache do Metro após alterações de configuração do prebuild: Caches desatualizados mascaram problemas de autolinking e resolução de configuração.
- Comando: npx expo start --clear após adicionar módulos nativos.
- Nuclear: rm -rf node_modules/.cache em erros persistentes do bundler.
Use npx expo config para depurar sem escrever arquivos: Mais rápido que o prebuild completo ao validar variantes de ambiente.
- Manifesto público: npx expo config --type public antes da submissão para a loja.
- Introspect: Veja os resultados dos mods que os plugins aplicarão.
Teste de fumaça em dispositivo físico após prebuild: Simuladores não capturam problemas de entitlement, push ou App Links.
- Matriz: Um dispositivo iOS + um dispositivo Android no mínimo após PRs de plugins.
- Complemento CI: EAS development profile constrói para colegas de equipe sem Xcode.

Camada 4: Portões de Atualização e Lançamento (19–24)

Atualizações sequenciais de SDK: Um SDK por vez - os templates de prebuild mudam por SDK.
- Sequência: expo install expo@^<sdk> → --fix → expo-doctor → excluir diretórios nativos → prebuild.
- Referência: ../expo-platform/upgrading-expo-sdk-versions/upgrading-expo-sdk-versions.md.
Commit de lockfiles com alterações de dependência relacionadas ao prebuild: expo install --fix atualiza package-lock.json - CI deve resolver a mesma árvore.
- Rejeite: PRs de atualização que alteram package.json sem lockfile.
- Verifique: npx expo install --check em scripts de higiene semanais.
EAS Build executa prebuild quando os diretórios nativos estão ausentes: Envie sem ios//android/ - o construtor na nuvem os gera.
- Opcional local: Equipes sem Xcode dependem inteiramente do EAS para compilação nativa.
- Mergulhe fundo: CNG em CI.
Impressão digital de alterações nativas para OTA/versão do runtime: Quando a impressão digital nativa muda, as atualizações OTA devem ter como alvo um novo runtime.
- Ferramenta: @expo/fingerprint - veja Detecção de Mudanças Nativas e Impressão Digital.
- Rejeite: Enviar OTA para binários compilados antes de um merge de plugin nativo.
Alinhamento da Nova Arquitetura: Os templates de prebuild do SDK 57 habilitam a Nova Arquitetura por padrão no RN 0.86.
- Verifique: Bibliotecas nativas de terceiros suportam TurboModules/Fabric antes de mesclar.
- Escape hatch: newArchEnabled: false requer ADR e reconstrução.
Lançamento na loja após merges que afetam o nativo: eas build de produção deve ser executado no mesmo commit que passou no prebuild local/EAS.
- Rejeite: Mesclar PRs de plugin sem um build de desenvolvimento verde na CI.
- Rollback: PRs nativos de propósito único mapeiam claramente para o rollback da versão da loja.

Camada 5: Brownfield e Migração (25–28)

Inventarie diffs nativos mantidos manualmente antes da adoção do CNG: Liste cada alteração Xcode e Gradle que não está na configuração.
- Saída: Planilha mapeando arquivo → plugin de configuração ou exceção ADR.
- Runbook: Migrando Projetos Nativos Manuais para CNG.
Use --no-clean apenas durante a migração, não em CI: A CI deve provar que o prebuild limpo é reproduzível.
- Portão final: rm -rf ios android && npx expo prebuild passa no branch de migração.
- Concluído quando: Diretórios nativos ignorados em git e o prebuild limpo é o único caminho.
Verificação de autolinking após migração: expo-modules-autolinking deve aparecer no Podfile gerado e settings.gradle.
- Corrija: npx expo prebuild --clean se as entradas de autolinking estiverem ausentes.
- Referência: ../native-modules/autolinking-and-expo-modules-core/autolinking-and-expo-modules-core.md.
Documente quem é o proprietário de regressões nativas pós-CNG: Engenheiro de plataforma ou líder mobile revisa PRs de plugins.
- CODEOWNERS: app.config.ts, plugins/ e qualquer código nativo em modules/.
- Onboarding: README declara o fluxo de trabalho CNG - sem edições silenciosas no Xcode.

FAQs

Quando devo usar --no-clean?

Iterando em um plugin de configuração ao portar uma edição nativa de brownfield.
Depurando atualizações incrementais de template sem exclusão/regeneração completa.
Nunca em branches de atualização de SDK ou validação de CI - use a limpeza padrão.

O expo prebuild é executado automaticamente no EAS Build?

Sim, quando ios/ e android/ não são enviados ou são ignorados pelo git.
EAS executa a mesma avaliação de configuração e pipeline de plugins que o prebuild local.

Qual é o loop de iteração nativa local mais rápido?

Edite app.config.ts ou o plugin
npx expo prebuild --platform <ios|android>
npx expo run:<platform>
Repita - use --no-install no prebuild apenas ao pular a compilação

Posso pular o prebuild se usar o Expo Go?

O Expo Go usa um binário nativo fixo - ele ignora seus plugins de configuração para entitlements nativos.
Código nativo personalizado requer prebuild + dev client - Expo Go não é um alvo de teste de produção.

Relacionados

Noções Básicas de Prebuild - dez exemplos para gerar projetos nativos a partir da configuração
Plugins de Configuração em CNG - mutações nativas compostas
Código Nativo Personalizado em CNG - quando commitar ios/ e android/
CNG em CI - EAS gera vs projetos nativos commitados
../expo-rules/expo-project-rules-checklist/expo-project-rules-checklist.md - não negociáveis da equipe
Melhores Práticas de Prebuild - resumo de 25 itens

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).

Fluxo de Trabalho do expo prebuild

Buscar na documentação

Fluxo de Trabalho do expo prebuild