Noções Básicas de Prebuild

Dez exemplos para gerar ios/ e android/ a partir da configuração do Expo sem desvios manuais - a base da Geração Nativa Contínua (CNG) no Expo SDK 57 e React Native 0.86.

Pré-requisitos

Comece com um aplicativo Expo em branco com o SDK 57 fixado. O Prebuild lê app.config.ts, aplica plugins de configuração e grava projetos nativos:

npx create-expo-app@latest PrebuildBasics --template blank-typescript@sdk-57 --yes
cd PrebuildBasics

Confirme o pin da stack antes de executar o prebuild:

{
  "dependencies": {
    "expo": "~57.0.4",
    "react": "19.2.3",
    "react-native": "0.86.0"
  }
}

Ferramentas: Estes exemplos visam Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 e React 19.2.3. Leia Native Module Rules antes de adicionar dependências nativas.

Exemplos Básicos

1. O que o Prebuild Faz

npx expo prebuild é a ponte entre sua configuração JavaScript e os projetos Xcode/Gradle. Ele:

1. Avalia app.config.ts (ou app.json)
2. Executa plugins de configuração registrados em ordem
3. Copia o template nativo do SDK 57 para ios/ e android/
4. Aplica mutações de plugin a Info.plist, AndroidManifest.xml, Gradle e Podfile

npx expo prebuild

Após uma execução bem-sucedida:

PrebuildBasics/
├── app.config.ts
├── ios/                 # Gerado - não edite manualmente sob CNG
├── android/             # Gerado - não edite manualmente sob CNG
└── package.json

• Equipes CNG ignoram ios/ e android/ - o EAS Build executa o mesmo passo de prebuild no CI
• Arquivos nativos editados manualmente são sobrescritos em expo prebuild --clean (o padrão do SDK 57)
• Expresse alterações duráveis como plugins de configuração, não cliques no Xcode - veja Config Plugins in CNG

2. app.config.ts Mínimo para Prebuild

O Prebuild precisa de identificadores de bundle, nome de exibição e caminhos de ícone no mínimo:

// app.config.ts
import type { ExpoConfig } from "expo/config";
 
const config: ExpoConfig = {
  name: "PrebuildBasics",
  slug: "prebuild-basics",
  version: "1.0.0",
  orientation: "portrait",
  icon: "./assets/icon.png",
  scheme: "prebuildbasics",
  userInterfaceStyle: "automatic",
  ios: {
    bundleIdentifier: "com.example.prebuildbasics",
    supportsTablet: true,
  },
  android: {
    package: "com.example.prebuildbasics",
    adaptiveIcon: {
      foregroundImage: "./assets/adaptive-icon.png",
      backgroundColor: "#ffffff",
    },
  },
};
 
export default config;

npx expo prebuild --no-install

• --no-install pula pod install e sincronização do Gradle - útil para verificações de diff no CI
• npx expo config --type public imprime o manifesto resolvido sem gravar pastas nativas
• O ID do bundle e o nome do pacote fluem para PRODUCT_BUNDLE_IDENTIFIER e applicationId gerados

3. Ignorar Pastas Nativas sob CNG

Projetos CNG padrão não confirmam diretórios nativos gerados:

# .gitignore (padrão CNG)
ios/
android/

# Verifique se o prebuild reproduz a mesma árvore localmente
rm -rf ios android
npx expo prebuild --no-install

• ios/ confirmado do SDK 56 bloqueia templates do RN 0.86 na atualização - exclua e regenere
• EAS Build executa o prebuild automaticamente quando as pastas estão ausentes
• Equipes Brownfield que confirmam diretórios nativos herdam trabalho manual de mesclagem - veja Custom Native Code in CNG

Relacionado: ../expo-rules/expo-project-rules-checklist/expo-project-rules-checklist.md - O gitignore do CNG é um não negociável de Nível 3

4. Padrão de Regeneração Limpa do SDK 57

No SDK 57, expo prebuild exclui ios/ e android/ existentes antes de regenerar:

# Comportamento padrão (SDK 57): limpar e depois gerar
npx expo prebuild
 
# Desativar: sobrepor alterações em projetos nativos existentes
npx expo prebuild --no-clean

• Use limpeza padrão após atualizações de SDK ou quando a saída do plugin parecer corrompida
• Use --no-clean ao iterar em um patch nativo local que você está migrando para um plugin
• Checklist de fluxo de trabalho completo: expo prebuild Workflow

5. Inspecionando a Saída Gerada

Antes de mesclar alterações de plugin, compare o que o prebuild produziu:

npx expo prebuild --no-install
git diff ios android   # apenas se as pastas forem rastreadas (brownfield)

# Imprimir configuração resolvida sem gravar arquivos
npx expo config --type introspect

• --type introspect mostra os resultados de modificação que os plugins aplicariam - mais rápido que o prebuild completo durante o desenvolvimento de plugins
• expo-doctor captura campos de configuração inválidos que falham silenciosamente até o prebuild
• A ordem dos plugins em app.config.ts importa quando vários plugins tocam o mesmo arquivo

6. Registrando um Plugin de Configuração

Permissões e direitos nativos pertencem a plugins, não a edições pós-prebuild:

// app.config.ts
const config: ExpoConfig = {
  // ...name, slug, ios, android
  plugins: [
    [
      "expo-camera",
      {
        cameraPermission: "Allow $(PRODUCT_NAME) to scan barcodes.",
      },
    ],
  ],
};

npx expo install expo-camera
npx expo prebuild --platform ios --no-install

• expo-camera envia um plugin de configuração que adiciona NSCameraUsageDescription ao Info.plist
• Bibliotecas de terceiros com código nativo frequentemente expõem plugins - verifique seu README para suporte ao SDK 57
• Mergulho profundo: Config Plugins in CNG e ../native-modules/config-plugins/config-plugins.md

7. Prebuild + Cliente de Desenvolvimento

Módulos nativos personalizados exigem um build de desenvolvimento, não o Expo Go. O Prebuild gera o shell nativo:

npx expo install expo-dev-client
npx expo prebuild
npx expo run:ios

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

• expo run:ios executa o prebuild se ios/ estiver ausente, instala pods e depois compila
• Reconstrua o cliente de desenvolvimento após cada atualização de SDK ou alteração de dependência nativa - OTA não pode substituir código nativo
• ../native-modules/native-modules-basics/native-modules-basics.md - quando apenas JS não é suficiente

8. Configuração Específica da Plataforma

O Prebuild lê chaves de plataforma e gera configurações nativas correspondentes:

// trecho do app.config.ts
ios: {
  bundleIdentifier: "com.example.prebuildbasics",
  infoPlist: {
    UIBackgroundModes: ["fetch"],
  },
  associatedDomains: ["applinks:shop.example.com"],
},
android: {
  package: "com.example.prebuildbasics",
  intentFilters: [
    {
      action: "VIEW",
      autoVerify: true,
      data: [{ scheme: "https", host: "shop.example.com", pathPrefix: "/orders" }],
      category: ["BROWSABLE", "DEFAULT"],
    },
  ],
},

npx expo prebuild --no-install

• Universal Links e App Links exigem direitos nativos - os campos de configuração mapeiam para associatedDomains e filtros de intenção
• Prefira plugins de configuração de biblioteca (por exemplo, expo-router, expo-notifications) em vez de infoPlist bruto quando disponíveis
• Reconstrua binários da loja após alterar domínios ou esquemas - OTA não pode adicionar direitos

9. Padrões da Nova Arquitetura

O SDK 57 visa o RN 0.86 com a Nova Arquitetura habilitada nos templates de prebuild:

// app.config.ts
const config: ExpoConfig = {
  // ...
  newArchEnabled: true,
};

npx expo-doctor
npx expo prebuild --no-install

• newArchEnabled: false é um escape hatch temporário - documente um ADR se você o desativar
• Bibliotecas nativas de terceiros devem suportar TurboModules/Fabric no RN 0.86 - verifique os problemas do GitHub antes de instalar
• Reconstrução limpa após alterar newArchEnabled: rm -rf ios android && npx expo prebuild

10. Prebuild no Caminho de Atualização

Atualizações de SDK excluem pastas nativas desatualizadas sob CNG:

npx expo install expo@^57.0.0
npx expo install --fix
npx expo-doctor
rm -rf ios android
npx expo prebuild --no-install

• Nunca atualize react-native independentemente - expo install --fix fixa o RN 0.86.0 para o SDK 57
• EAS Build regenera projetos nativos quando ios//android/ estão ausentes do upload
• Receita completa de atualização: ../expo-platform/upgrading-expo-sdk-versions/upgrading-expo-sdk-versions.md

Exemplos Intermediários

11. Monorepo Prebuild a partir da Raiz do App

Em um workspace pnpm/Turborepo, execute o prebuild a partir do diretório do pacote do aplicativo:

cd apps/mobile
npx expo prebuild --no-install

// apps/mobile/app.config.ts
const config: ExpoConfig = {
  name: "Mobile",
  slug: "mobile",
  // ...
};

• Metro e prebuild resolvem a partir da raiz do app - não da raiz do monorepo
• Pacotes compartilhados não precisam de seu próprio ios/ - apenas aplicativos implantáveis executam o prebuild
• ../project-setup/shared-packages-and-metro-resolution/shared-packages-and-metro-resolution.md

12. Variantes de Ambiente Sem Projetos Nativos Forquilhados

Controle os IDs de bundle de staging e produção a partir de variáveis de ambiente - um arquivo de configuração, múltiplos binários:

// app.config.ts
const IS_DEV = process.env.APP_VARIANT === "development";
 
const config: ExpoConfig = {
  name: IS_DEV ? "PrebuildBasics (Dev)" : "PrebuildBasics",
  slug: "prebuild-basics",
  ios: {
    bundleIdentifier: IS_DEV
      ? "com.example.prebuildbasics.dev"
      : "com.example.prebuildbasics",
  },
  android: {
    package: IS_DEV
      ? "com.example.prebuildbasics.dev"
      : "com.example.prebuildbasics",
  },
};
 
export default config;

APP_VARIANT=development npx expo prebuild --no-install
APP_VARIANT=production npx expo prebuild --no-install

• Perfis EAS definem env.APP_VARIANT por build - o prebuild é executado com o ID de bundle correto no CI
• Cada ID de bundle precisa de suas próprias credenciais e projectId do EAS se os binários forem enviados separadamente
• Nunca confirme segredos em app.config.ts - use EAS Secrets para chaves de assinatura

13. Validando Prebuild Antes da Mesclagem

Adicione um portão de CI que prove que a configuração produz saída nativa reproduzível:

#!/usr/bin/env bash
# scripts/verify-prebuild.sh
set -euo pipefail
 
npx expo-doctor
rm -rf ios android
npx expo prebuild --no-install
 
# Opcional: falhar se houver um diff nativo inesperado quando as pastas forem rastreadas
if git diff --quiet ios android 2>/dev/null; then
  echo "A saída do Prebuild corresponde aos projetos nativos confirmados."
else
  echo "Diff nativo detectado - migre as alterações para plugins de configuração."
  exit 1
fi

• Equipes CNG pulam a etapa de diff do git - as pastas são ignoradas pelo git
• Execute duas vezes localmente ao criar plugins - a segunda execução deve produzir zero diff
• CNG in CI - quando o EAS gera versus quando você confirma diretórios nativos

FAQs

Relacionados

• expo prebuild Workflow - regen limpa, --no-clean, checklist de iteração local
• Config Plugins in CNG - alterações nativas compostas
• Custom Native Code in CNG - expo run:ios/android e confirmação de diretórios nativos
• ../native-modules/autolinking-and-expo-modules-core/autolinking-and-expo-modules-core.md - como os módulos se vinculam após o prebuild
• ../expo-rules/native-module-rules/native-module-rules.md - quando usar plugins versus código nativo personalizado
• ../expo-platform/expo-platform-basics/expo-platform-basics.md - fluxo de trabalho gerenciado e camada de plataforma

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