Fundamentos de Prebuild

Diez ejemplos para generar ios/ y android/ desde la configuración de Expo sin desvío manual - la base de Continuous Native Generation (CNG) en Expo SDK 57 y React Native 0.86.

Requisitos previos

Comienza desde una aplicación Expo en blanco con SDK 57 fijado. Prebuild lee app.config.ts, aplica plugins de configuración y escribe proyectos nativos:

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

Confirma el pin de la pila antes de ejecutar prebuild:

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

Herramientas: Estos ejemplos están dirigidos a Expo SDK 57 (expo ~57.0.4), React Native 0.86.0 y React 19.2.3. Lee Native Module Rules antes de agregar dependencias nativas.

Ejemplos básicos

1. Qué hace Prebuild

npx expo prebuild es el bridge entre tu configuración JavaScript y proyectos Xcode/Gradle. Lo que hace:

1. Evalúa app.config.ts (o app.json)
2. Ejecuta plugins de configuración registrados en orden
3. Copia la plantilla nativa de SDK 57 en ios/ y android/
4. Aplica mutaciones de plugins a Info.plist, AndroidManifest.xml, Gradle y Podfile

npx expo prebuild

Después de una ejecución exitosa:

PrebuildBasics/
├── app.config.ts
├── ios/                 # Generado - no editar manualmente bajo CNG
├── android/             # Generado - no editar manualmente bajo CNG
└── package.json

• Los equipos de CNG gitignore ios/ y android/ - EAS Build ejecuta el mismo paso de prebuild en CI
• Los archivos nativos editados manualmente se sobrescriben en expo prebuild --clean (el default de SDK 57)
• Expresa cambios duraderos como plugins de configuración, no clics de Xcode - ver Config Plugins in CNG

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

Prebuild necesita identificadores de paquete, nombre de visualización y rutas de iconos como 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 omite pod install y Gradle sync - útil para comprobaciones de diff de CI
• npx expo config --type public imprime el manifiesto resuelto sin escribir carpetas nativas
• El ID de paquete y el nombre del paquete fluyen en PRODUCT_BUNDLE_IDENTIFIER y applicationId generados

3. Gitignore de Carpetas Nativas Bajo CNG

Los proyectos CNG estándar no confirman directorios nativos generados:

# .gitignore (patrón CNG)
ios/
android/

# Verifica que prebuild reproduce el mismo árbol localmente
rm -rf ios android
npx expo prebuild --no-install

• ios/ comprometido de SDK 56 bloquea plantillas de RN 0.86 en upgrade - elimina y regenera
• EAS Build ejecuta prebuild automáticamente cuando faltan carpetas
• Los equipos de brownfield que comprometen directorios nativos heredan trabajo de fusión manual - ver Custom Native Code in CNG

Relacionado: ../expo-rules/expo-project-rules-checklist/expo-project-rules-checklist.md - gitignore de CNG es un no-negociable de Tier 3

4. Default de Regen Limpio de SDK 57

En SDK 57, expo prebuild elimina ios/ y android/ existentes antes de regenerar:

# Comportamiento por defecto (SDK 57): limpiar luego generar
npx expo prebuild
 
# Optar por no participar: capas de cambios en proyectos nativos existentes
npx expo prebuild --no-clean

• Usa default limpio después de upgrades de SDK o cuando la salida del plugin se ve corrupta
• Usa --no-clean cuando iteras en un parche nativo local que estás migrando en un plugin
• Lista de verificación de flujo completo: expo prebuild Workflow

5. Inspeccionar la Salida Generada

Antes de fusionar cambios de plugins, diffsea lo que prebuild produjo:

npx expo prebuild --no-install
git diff ios android   # solo si las carpetas están rastreadas (brownfield)

# Imprimir configuración resuelto sin escribir archivos
npx expo config --type introspect

• --type introspect muestra resultados de mods que aplicarían plugins - más rápido que prebuild completo durante el desarrollo de plugins
• expo-doctor detecta campos de configuración inválidos que fallan silenciosamente hasta prebuild
• El orden de los plugins en app.config.ts importa cuando múltiples plugins tocan el mismo archivo

6. Registrando un Plugin de Configuración

Los permisos nativos y derechos pertenecen en plugins, no en ediciones post-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 envía un plugin de configuración que agrega NSCameraUsageDescription a Info.plist
• Las librerías de terceros con código nativo a menudo exponen plugins - consulta su README para soporte de SDK 57
• Profundización: Config Plugins in CNG y ../native-modules/config-plugins/config-plugins.md

7. Prebuild - Cliente de Desarrollo

Los módulos nativos personalizados requieren un desarrollo build, no Expo Go. Prebuild genera el shell nativo:

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

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

• expo run:ios ejecuta prebuild si ios/ falta, instala pods, luego compila
• Reconstruye el cliente de desarrollo después de cada bump de SDK o cambio de dependencia nativa - OTA no puede reemplazar código nativo
• ../native-modules/native-modules-basics/native-modules-basics.md - cuando solo JS no es suficiente

8. Configuración Específica de Plataforma

Prebuild lee claves de plataforma y genera configuración nativa correspondiente:

// app.config.ts fragmento
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 y App Links requieren derechos nativos - los campos de configuración se mapean a associatedDomains e intent filters
• Prefiere plugins de configuración de librerías (por ejemplo, expo-router, expo-notifications) sobre infoPlist sin procesar cuando estén disponibles
• Reconstruye binarios de tienda después de cambiar dominios o esquemas - OTA no puede agregar derechos

9. Defaults de Nueva Arquitectura

SDK 57 se dirige a RN 0.86 con la Nueva Arquitectura habilitada en plantillas de prebuild:

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

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

• newArchEnabled: false es una escotilla de emergencia temporal - documenta un ADR si la desactivas
• Las librerías nativas de terceros deben soportar TurboModules/Fabric en RN 0.86 - consulta problemas de GitHub antes de instalar
• Reconstrucción limpia después de cambiar newArchEnabled: rm -rf ios android && npx expo prebuild

10. Prebuild en la Ruta de Upgrade

Los bumps de SDK eliminan carpetas nativas obsoletas bajo 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 bumps react-native independientemente - expo install --fix fija RN 0.86.0 para SDK 57
• EAS Build regenera proyectos nativos cuando ios//android/ están ausentes de la carga
• Receta de upgrade completa: ../expo-platform/upgrading-expo-sdk-versions/upgrading-expo-sdk-versions.md

Ejemplos Intermedios

11. Prebuild de Monorepo desde la Raíz de la Aplicación

En un workspace de pnpm/Turborepo, ejecuta prebuild desde el directorio de paquete de la aplicación:

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

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

• Metro y prebuild ambos se resuelven desde la raíz de la aplicación - no la raíz del monorepo
• Los paquetes compartidos no necesitan su propio ios/ - solo aplicaciones implementables ejecutan prebuild
• ../project-setup/shared-packages-and-metro-resolution/shared-packages-and-metro-resolution.md

12. Variantes de Entorno Sin Proyectos Nativos Bifurcados

Impulsa bundle IDs de staging y producción desde variables env - un archivo de configuración, múltiples binarios:

// 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

• Los perfiles de EAS establecen env.APP_VARIANT por build - prebuild se ejecuta con el bundle ID correcto en CI
• Cada bundle ID necesita sus propias credenciales y EAS projectId si los binarios se envían por separado
• Nunca confirmes secretos en app.config.ts - usa EAS Secrets para claves de firma

13. Validando Prebuild Antes de Fusionarse

Agrega una puerta de CI que prueba que la configuración produce salida nativa reproducible:

#!/usr/bin/env bash
# scripts/verify-prebuild.sh
set -euo pipefail
 
npx expo-doctor
rm -rf ios android
npx expo prebuild --no-install
 
# Opcional: fallar si se detecta diff nativo inesperado cuando las carpetas se rastrean
if git diff --quiet ios android 2>/dev/null; then
  echo "Prebuild output matches committed native projects."
else
  echo "Native diff detected - migrate changes to config plugins."
  exit 1
fi

• Los equipos de CNG omiten el paso de git diff - las carpetas son gitignored
• Ejecuta dos veces localmente cuando escribas plugins - la segunda ejecución debe producir cero diff
• CNG in CI - cuando EAS genera vs cuando verificas directorios nativos

Preguntas frecuentes

Relacionado

• expo prebuild Workflow - regen limpio, --no-clean, lista de verificación de iteración local
• Config Plugins in CNG - cambios nativos componibles
• Custom Native Code in CNG - expo run:ios/android y comprometer directorios nativos
• ../native-modules/autolinking-and-expo-modules-core/autolinking-and-expo-modules-core.md - cómo los módulos se vinculan después de prebuild
• ../expo-rules/native-module-rules/native-module-rules.md - cuándo usar plugins vs código nativo personalizado
• ../expo-platform/expo-platform-basics/expo-platform-basics.md - flujo de trabajo administrado y capa de plataforma

Versiones de pila: Esta página fue escrita para React 19.2.3, React Native 0.86.0 y Expo SDK 57 (expo ~57.0.4).