Melhores Práticas para Brownfield
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.
Defina brownfield explicitamente: Se o AppDelegate / Application nativo for o proprietário da UI raiz, o RN é um convidado - planeje os limites de incorporação antes de escolher as rotas do Expo Router.
Pontue embed vs rewrite vs WebView por recurso: Use a matriz de três vias em Noções Básicas de Brownfield - shells WebView permanentes sem um ADR de pôr do sol são um modo comum de falha.
Padrão para artefatos expo-brownfield isolados: AAR + Swift Package permite que a CI nativa pule o Node quando as equipes estão divididas - integrado apenas quando um esquadrão edita ambos os lados diariamente.
Um bundler Metro por módulo embarcado: Dois runtimes RN em um único processo exigem multipleFrameworks: true no iOS e uma estratégia de símbolos deliberada - evite projetos Metro duplos acidentais.
Inicialize ReactNativeHostManager uma vez no lançamento do aplicativo: A inicialização tardia causa telas RN em branco e ciclo de vida de módulo Expo instável - espelhe a documentação do Expo no AppDelegate / Application host.
Corresponda moduleName ao registro JS: O ReactNativeViewController(moduleName:) host deve estar alinhado com registerRootComponent / entrada app.json - a incompatibilidade mostra uma tela branca sem erro de JS.
Fixe o Expo SDK entre expo e expo-brownfield: Use npx expo install no SDK 57 - Hermes e binários nativos divergem se as versões se separarem.
Execute npx expo-doctor em cada build de artefato: Detecta o descompasso do módulo nativo antes que os consumidores Maven/XCFramework publiquem artefatos ruins.
Versionar artefatos Android na configuração do plugin: android.version deve corresponder às coordenadas Maven - marque Git e Maven com o mesmo semver.
Envie pacotes Swift de depuração e lançamento do iOS separadamente: Alvos binários SPM são específicos de sabor - QA e pinos da App Store não devem cruzar fios.
Documente uma versão de contrato de ponte: BRIDGE_CONTRACT_VERSION em tipos compartilhados - a quebra de SharedStateKeys ou valores de type de mensagem requer lançamentos nativos + RN coordenados.
O keychain nativo possui tokens de atualização: O RN obtém tokens de acesso de curta duração via useSharedState - a atualização permanece nativa, a menos que o estrangulador de autenticação tenha sido explicitamente migrado.
Monte um listener raiz SessionBridge: Mensagens SESSION_UPDATED / LOGOUT em _layout.tsx - listeners por tela perdem eventos em navegação rápida.
Nunca passe tokens de atualização em initialProps: As props de bootstrap são registradas e inspecionadas - use o estado compartilhado definido pelo nativo após a leitura segura.
Use Brownfield.popToNative() na conclusão do fluxo: Checkout e assistentes devem retornar o controle ao chrome nativo - não deixe pilhas RN órfãs sob abas nativas.
Habilite setNativeBackEnabled quando o nativo possuir o back: O botão de voltar do hardware deve sair do módulo RN quando a pilha estiver vazia - evita usuários presos no Android.
Escolha fatias de estrangulador pós-autenticação e fora do cold start: A primeira fatia não deve bloquear o lançamento do aplicativo - a inicialização do RN na aba inicial é uma armadilha de propriedade de desempenho e navegação.
Registre a ordem das fatias em ADRs: Decisões classificadas ADR de Adoção Incremental evitam migrações de "página de configurações aleatórias" sem coesão de jornada.
Separe os trens de lançamento: Pipeline de artefatos RN, pipeline de loja host, OTA opcional - versioná-los independentemente por CI/CD Brownfield.
OTA apenas dentro de runtimeVersion: eas update no projeto RN não deve ultrapassar o runtime Hermes incorporado no artefato fixado do host.
Teste offline os artefatos de lançamento: Modo avião no build de Lançamento do host antes de atualizar Maven/SPM - caminhos Metro de depuração ocultam pacotes embarcados ausentes.
Use @expo/ui RNHostView para chrome nativo dentro de telas RN: Distinto da apresentação brownfield completa - barras de ferramentas nativas em torno de corpos RN sem gerenciadores de visualização personalizados.
Mantenha as rotas RN finas; recursos grandes: O mesmo que greenfield - app/ reexporta telas de recursos por Noções Básicas de Arquitetura Mobile.
Prefira plugins de configuração em vez de plists host editados manualmente: O plugin expo-brownfield regenera alvos em prebuild --clean - edições manuais do Gradle são perdidas.
Trate brownfield como capaz de alpha, não descuidado com alpha: O Expo documenta o suporte brownfield como alpha - orce depuração de build nativo, leia as notas de lançamento do SDK e abra issues upstream com artefatos de reprodução.
Não - use artefatos brownfield de depuração com Metro ou builds host internos. O Expo Go não pode carregar seu shell host.
Conteúdo legal, de marketing e raramente atualizado somente leitura - não fluxos de produto principais com requisitos de navegação offline ou nativa.
Um, a menos que limites legais ou de equipe forcem dois - cada um adiciona CI de artefato, contratos de ponte e complexidade do linker iOS.
O Expo Router é o proprietário da navegação dentro do módulo embarcado apenas até que o ADR declare a raiz nativa aposentada - veja o ADR de navegação em architecture-design.
O esquadrão RN publica um novo artefato; o esquadrão nativo integra o PR que atualiza a dependência - OTA sozinho é insuficiente para novos módulos nativos.
expo-brownfieldVersõ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