Código Nativo Personalizado en CNG

Loops locales de expo run:ios / expo run:android y la decisión de cuándo hacer commit de ios/ y android/ en un flujo de trabajo de Generación Nativa Continua. El código nativo personalizado pertenece a modules/, plugins de configuración y EAS Build - no a ediciones silenciosas de Xcode que desaparecen en prebuild limpio.

Receta

Tarjeta de receta de referencia rápida - lista para copiar-pegar.

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

# Andamio de un módulo Expo local (preferido sobre código de bridge crudo)
npx create-expo-module@latest expo-device-info-plus
# Mueve a modules/ si el CLI creó una carpeta hermana

CustomNative/
├── app.config.ts
├── modules/
│   └── expo-device-info-plus/   # Hacer commit esto - fuente de verdad
├── plugins/                     # Hacer commit plugins de configuración personalizados
├── ios/                         # Gitignore bajo CNG
└── android/                     # Gitignore bajo CNG

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

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

Cuándo usar esto:

• Depuración de un módulo Expo personalizado en un dispositivo físico
• Iterando en Swift/Kotlin antes de publicar un módulo
• Validando autovínculo después de agregar modules/my-feature/
• Decidiendo si los directorios nativos de brownfield deben permanecer comprometidos

Ejemplo de Trabajo

Una app con un módulo Expo local, un cliente dev y gitignore de CNG - el loop nativo personalizado estándar de 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 - CNG predeterminado
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>Modelo de dispositivo: {model}</Text>
    </View>
  );
}

# Primera compilación nativa en un clon fresco
npm install
npx expo run:ios
 
# Después de cambiar Swift/Kotlin en modules/
npx expo run:ios --no-build-cache

Lo que esto demuestra:

• modules/ se hace commit - el código fuente nativo sobrevive prebuild limpio
• ios//android/ se generan - recreados desde config + autovínculo en cada prebuild
• expo run:ios orquesta prebuild - pod install - compilación de Xcode
• Los cambios de módulos requieren recompilación - Fast Refresh de Metro no recarga código nativo

Análisis Profundo

El Loop Nativo Local

Editar modules/*.swift o *.kt  -  expo run:<platform>  -  prebuild (si es necesario)  -  compilar  -  prueba en dispositivo

Qué Hacer Commit vs Gitignore

Rutas de Integración (Preferir de Arriba hacia Abajo)

1. Paquete Expo SDK - npx expo install expo-* con plugin integrado
2. Paquete comunitario + plugin de configuración - verificar soporte de RN 0.86 / New Architecture
3. Módulo Expo local - npx create-expo-module@latest en modules/
4. Parche de plugin de configuración - para cambios finos de manifiesto nativo/Gradle
5. Directorios nativos comprometidos - solo brownfield, con plan de migración a CNG

Ver Native Module Rules Tier 1 para el árbol de decisión.

Autovínculo Después de Prebuild

expo-modules-autolinking descubre:

• Dependencias de npm con expo-module.config.json
• Carpetas locales modules/*
• Registros de plugins de configuración

npx expo prebuild --no-install
# Verificar que Podfile contiene script de autovínculo de Expo
# Verificar que android/settings.gradle incluye useExpoModules()

El autovínculo faltante se manifiesta como módulo nativo indefinido en tiempo de ejecución - no un error de Metro.

Cuándo Hacer Commit de Directorios Nativos

Hacer commit de ios/ y android/ solo cuando:

• Una app brownfield tiene código nativo que aún no puede expresarse como plugins
• Un ADR nombra al propietario, proceso de actualización e hito de migración de CNG
• CI ejecuta expo prebuild --check o diff de huella digital para detectar cambios

No hagas commit de directorios nativos cuando:

• Iniciando una app greenfield SDK 57
• Todos los cambios nativos viven en plugins y modules/
• EAS Build genera proyectos nativos en CI (CNG in CI)

Patrón de Migración Híbrida

# 1. Inventariar diffs de Xcode/Gradle vs prebuild fresco
rm -rf ios android
npx expo prebuild --no-install
git diff  # contra ios/ comprometido anteriormente
 
# 2. Transportar cada trozo de diff a un plugin de configuración o cambio de modules/
 
# 3. Compuerta final: prebuild limpio coincide con comportamiento
rm -rf ios android && npx expo prebuild

Runbook completo: Migrating Manual Native Projects to CNG.

Errores Comunes

• Editar AppDelegate generado sin un plugin - Perdido en SDK 57 prebuild limpio. Solución: plugin expo-dev-client o plugin de configuración personalizado.
• Esperando que Expo Go cargue módulos personalizados - El binario de Expo Go es fijo. Solución: Cliente dev mediante expo run:ios o compilación de desarrollo EAS.
• Olvidar reconstruir después del cambio de Swift - Metro Fast Refresh solo actualiza JS. Solución: Volver a ejecutar expo run:ios.
• Dos copias de react-native en monorepo - El autovínculo elige la instancia incorrecta. Solución: npx expo-doctor, único react-native hoisted.
• Hacer commit de ios/Pods/ - Inflado masivo de repo y conflictos de fusión. Solución: Gitignore Pods; pod install en CI/EAS.
• Mezclar CNG y Gradle editado manualmente - Prebuild sobrescribe ediciones sin codificar. Solución: expo-build-properties o plugin personalizado.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Prebuild - generando proyectos nativos
• Plugins de Configuración en CNG - codificando ediciones nativas
• ../native-modules/create-expo-module/create-expo-module.md - andamio de módulos locales
• ../native-modules/writing-a-turbomodule/writing-a-turbomodule.md - ruta de TurboModule en RN 0.86
• ../expo-rules/native-module-rules/native-module-rules.md - lista de verificación de ruta de integración
• Migrando Proyectos Nativos Manuales a CNG - adopción de brownfield

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