Código Nativo Personalizado no CNG

Loops locais de expo run:ios / expo run:android e a decisão de quando commitar ios/ e android/ em um fluxo de trabalho de Geração Nativa Contínua (Continuous Native Generation - CNG). Código nativo personalizado pertence a modules/, plugins de configuração e EAS Build - não a edições silenciosas no Xcode que desaparecem em um prebuild limpo.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

npx create-expo-app@latest CustomNative --template blank-typescript@sdk-57 --yes
cd CustomNative
npx expo install expo-dev-client expo-modules-core

# Estrutura um módulo Expo local (preferível a código de bridge bruto)
npx create-expo-module@latest expo-device-info-plus
# Mova para modules/ se a CLI criou uma pasta irmã

CustomNative/
├── app.config.ts
├── modules/
│   └── expo-device-info-plus/   # Commite isso - fonte da verdade
├── plugins/                     # Commite plugins de configuração personalizados
├── ios/                         # Gitignore sob CNG
└── android/                     # Gitignore sob CNG

// Scripts do package.json
{
  "scripts": {
    "ios": "expo run:ios",
    "android": "expo run:android",
    "prebuild": "expo prebuild"
  }
}

npx expo run:ios
# ou
npx expo run:android --device

Quando usar isso:

• Depurando um módulo Expo personalizado em um dispositivo físico
• Iterando em Swift/Kotlin antes de publicar um módulo
• Validando autolinking após adicionar modules/my-feature/
• Decidindo se as pastas nativas brownfield devem permanecer commitadas

Exemplo de Trabalho

Um aplicativo com um módulo Expo local, um cliente de desenvolvimento e gitignore CNG - o loop nativo personalizado padrão do SDK 57.

// app.config.ts
import type { ExpoConfig } from "expo/config";
 
const config: ExpoConfig = {
  name: "CustomNative",
  slug: "custom-native",
  ios: { bundleIdentifier: "com.example.customnative" },
  android: { package: "com.example.customnative" },
  plugins: ["expo-dev-client"],
};
 
export default config;

# .gitignore - Padrão CNG
ios/
android/
.expo/

// App.tsx
import * as DeviceInfoPlus from "expo-device-info-plus";
import { useEffect, useState } from "react";
import { Text, View } from "react-native";
 
export default function App() {
  const [model, setModel] = useState<string>("…");
 
  useEffect(() => {
    DeviceInfoPlus.getModelAsync().then(setModel);
  }, []);
 
  return (
    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
      <Text>Device model: {model}</Text>
    </View>
  );
}

# Primeira compilação nativa em um clone recém-criado
npm install
npx expo run:ios
 
# Após alterar Swift/Kotlin em modules/
npx expo run:ios --no-build-cache

O que isso demonstra:

• modules/ é commitado - o código nativo sobrevive a um prebuild limpo
• ios//android/ são gerados - recriados a partir da configuração + autolinking em cada prebuild
• expo run:ios orquestra prebuild → pod install → compilação Xcode
• Alterações de módulo exigem recompilação - Fast Refresh não recarrega código nativo

Mergulho Profundo

O Loop Nativo Local

Editar modules/*.swift ou *.kt  →  expo run:<platform>  →  prebuild (se necessário)  →  compilar  →  teste no dispositivo

O Que Commitar vs Gitignore

Caminhos de Integração (Prefira de Cima para Baixo)

1. Pacote Expo SDK - npx expo install expo-* com plugin integrado
2. Pacote da comunidade + plugin de configuração - verifique o suporte a RN 0.86 / Nova Arquitetura
3. Módulo Expo local - npx create-expo-module@latest em modules/
4. Patch de plugin de configuração - para pequenas alterações de manifesto nativo/Gradle
5. Diretórios nativos commitados - apenas brownfield, com plano de migração para CNG

Veja Regras de Módulo Nativo Nível 1 para a árvore de decisão.

Autolinking Após Prebuild

expo-modules-autolinking descobre:

• Dependências npm com expo-module.config.json
• Pastas locais modules/*
• Registros de plugins de configuração

npx expo prebuild --no-install
# Verifique se o Podfile contém o script de autolinking do expo
# Verifique se android/settings.gradle inclui useExpoModules()

Autolinking ausente se manifesta como módulo nativo indefinido em tempo de execução - não um erro do Metro.

Quando Commitar Diretórios Nativos

Commite ios/ e android/ apenas quando:

• Um aplicativo brownfield tem código nativo que ainda não pode ser expresso como plugins
• Um ADR nomeia o proprietário, o processo de atualização e o marco de migração CNG
• CI executa expo prebuild --check ou diff de impressão digital para detectar desvios

Não commite diretórios nativos quando:

• Iniciando um aplicativo greenfield SDK 57
• Todas as alterações nativas vivem em plugins e modules/
• EAS Build gera projetos nativos em CI (CNG em CI)

Padrão de Migração Híbrida

# 1. Inventarie as diferenças do Xcode/Gradle em relação a um prebuild recém-criado
rm -rf ios android
npx expo prebuild --no-install
git diff  # contra o antigo ios/ commitado
 
# 2. Porte cada bloco de diff para um plugin de configuração ou alteração em modules/
 
# 3. Portão final: prebuild limpo reproduz o comportamento
rm -rf ios android && npx expo prebuild

Runbook completo: Migrando Projetos Nativos Manuais para CNG.

Armadilhas

• Editar AppDelegate gerado sem um plugin - Perdido no prebuild limpo do SDK 57. Correção: Plugin expo-dev-client ou plugin de configuração personalizado.
• Esperar que o Expo Go carregue módulos personalizados - O binário do Expo Go é fixo. Correção: Cliente de desenvolvimento via expo run:ios ou build de desenvolvimento EAS.
• Esquecer de recompilar após alteração em Swift - O Metro Fast Refresh apenas atualiza o JS. Correção: Reexecute expo run:ios.
• Duas cópias de react-native em monorepo - Autolinking escolhe a instância errada. Correção: npx expo-doctor, react-native unificado.
• Committar ios/Pods/ - Bloat massivo do repositório e conflitos de merge. Correção: Gitignore Pods; pod install em CI/EAS.
• Misturar CNG e Gradle editado manualmente - Prebuild sobrescreve edições não codificadas. Correção: expo-build-properties ou plugin personalizado.

Alternativas

FAQs

Relacionados

• Noções Básicas de Prebuild - gerando projetos nativos
• Plugins de Configuração no CNG - codificando edições nativas
• ../native-modules/create-expo-module/create-expo-module.md - estruturando módulos locais
• ../native-modules/writing-a-turbomodule/writing-a-turbomodule.md - caminho TurboModule no RN 0.86
• ../expo-rules/native-module-rules/native-module-rules.md - checklist do caminho de integração
• Migrando Projetos Nativos Manuais para CNG - adoção brownfield

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