Melhores Práticas de Módulos Nativos
Um resumo condensado das 25 práticas mais importantes de módulos nativos 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 mais importantes de módulos nativos extraídas de todas as páginas desta seção.
Pesquise primeiro os pacotes do Expo SDK: expo-camera, expo-location, expo-secure-store e mais de 100 módulos vêm com binários nativos do SDK 57 - prefira-os em vez de wrappers nativos aleatórios do npm, de acordo com Regras de Módulos Nativos.
Execute a lista de verificação de terceiros antes de npm install: Verifique o suporte ao RN 0.86, Nova Arquitetura, disponibilidade de plugin de configuração e manutenção - veja Usando Bibliotecas Nativas de Terceiros.
Sempre use npx expo install para dependências nativas: Resolve versões compatíveis com os binários nativos do SDK 57 - o sucesso da compilação não garante estabilidade em tempo de execução.
Trate o Expo Go como apenas SDK: Módulos nativos de terceiros e personalizados exigem expo-dev-client e uma build de desenvolvimento - nunca aprove o QA apenas a partir do Expo Go.
Recompile o nativo após cada alteração nativa no package.json: O hot reload do Metro não compila Swift/Kotlin - execute npx expo run:ios / eas build antes de declarar como concluído.
OTA não pode enviar código nativo: O EAS Update entrega apenas JavaScript e assets - alterações nativas precisam de um novo binário da loja ou cliente de desenvolvimento.
Declare permissões em plugins de configuração: As entradas NS*UsageDescription do iOS e do manifesto do Android pertencem a plugins em app.config - veja Plugins de Configuração.
Escreva plugins idempotentes: Executar npx expo prebuild duas vezes não deve duplicar entradas em Info.plist ou AndroidManifest - git diff após a segunda execução deve estar vazio.
Documente a ordem dos plugins em app.config.ts: Plugins posteriores prevalecem ao modificar a mesma chave - comente por que expo-router precede plugins personalizados.
Prefira expo-build-properties para pins do Gradle/Pod: compileSdkVersion, target de implantação e regras do ProGuard sobrevivem à regeneração - veja Patching Native Projects.
Nunca edite manualmente ios/ e android/ em aplicativos CNG: O próximo prebuild --clean apaga as edições - codifique as alterações em plugins de acordo com Noções Básicas de Prebuild.
Use create-expo-module para pontes locais do aplicativo: A API Expo Modules integra autolinking, TypeScript e plugins de configuração - veja create-expo-module.
Exija um ADR para módulos nativos personalizados: Documente por que os pacotes do SDK falharam, nomeie um mantenedor e planeje testes da Nova Arquitetura - Regras de Módulos Nativos Nível 3.
Verifique o autolinking antes de mergulhar em Xcode/Gradle: npx expo-modules-autolinking resolve --platform ios mostra o que realmente é compilado no binário.
Alinhe a resolução do Metro e nativa em monorepos: Habilite autolinkingModuleResolution e evite cópias duplicadas de react-native - Autolinking & expo-modules-core.
Declare pacotes nativos do workspace como dependências diretas do aplicativo: O autolinking transitivo de módulos packages/* não é confiável - o package.json do aplicativo deve listá-los explicitamente.
Mock na fronteira do serviço em Jest: jest-expo substitui módulos Expo; substitua apenas o que os testes afirmam - veja Mocking Native Modules.
Uma suíte Jest que passa não prova que o nativo funciona: Complemente testes unitários com QA em dispositivo ou Maestro em uma build de desenvolvimento.
Escolha TurboModules apenas com justificativa: O Codegen + a cerimônia C++ são adequados para bibliotecas do ecossistema RN - equipes de aplicativos usam Expo Modules como padrão, a menos que compartilhem o núcleo C++ nativo - Writing a TurboModule.
Teste a Nova Arquitetura em builds de lançamento: RN 0.86 usa Fabric/TurboModules por padrão - depurar o Metro pode mascarar bugs de fallback da ponte; execute --configuration Release em hardware.
Uma dependência nativa por PR, quando possível: Misturar SDK de pagamento, mapas e módulo personalizado em uma única mesclagem torna o bisect impossível quando o prebuild falha.
Execute npx expo-doctor após cada alteração nativa: Detecta versões incompatíveis, plugins ausentes e workspaces mal configurados antes do CI.
Use patch-package apenas com um ticket de remoção: Prefira plugins de configuração e correções upstream - patches em node_modules quebram em expo install --fix.
Script de sobrevivência nativo pós-atualização do SDK: expo install --fix → expo-doctor → prebuild --clean → verificação de idempotência → compilação de lançamento em ambas as plataformas.
Lista de verificação nativa pré-lançamento: Build de desenvolvimento em dispositivo, fluxos de usuário nativos primários, caminhos de negação de permissão, expo-modules-autolinking resolve limpo, idempotência de plugin e reconstrução de credenciais da loja se as dependências nativas foram alteradas.
Analise este resumo primeiro para orientação, depois aprofunde-se nas páginas individuais ao implementar. Retorne aqui antes da revisão de código ou atualizações do SDK.
Expo Go durante a prototipagem com módulos apenas do SDK. Mude para expo-dev-client antes de mesclar qualquer dependência nativa de terceiros ou personalizada.
Registre o plugin de configuração da biblioteca em app.config.ts, execute npx expo prebuild --clean e verifique se as strings de descrição de uso existem no Info.plist gerado.
O CNG regenera projetos nativos a partir da configuração. Módulos nativos são instalados via autolinking; plugins de configuração aplicam suas permissões e requisitos de build durante o prebuild - CNG prebuild.
Quando o Expo SDK, pacotes de terceiros mantidos e módulos Expo finos não conseguem atender a um requisito documentado - com ADR, proprietário e plano de QA do cliente de desenvolvimento por Regras de Módulos Nativos.
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: 16 de jul. de 2026