Tratar las carpetas nativas como salida de compilación con Expo Prebuild y CNG

Durante años, los equipos de React Native en Expo se enfrentaron al mismo dilema: en el momento en que un proyecto necesitaba un módulo nativo personalizado, audio de fondo o un SDK de un proveedor, la solución era expo eject, y el ordenado proyecto en JavaScript de repente pasaba a tener los directorios completos de ios y android. A partir de entonces, el equipo también tenía que mantener CocoaPods, editar build.gradle y solucionar errores en Xcode. La Generación Nativa Continua (CNG) y Expo Prebuild eliminan ese compromiso. Esta guía explica cómo funciona este modelo, cómo los plugins de configuración reemplazan las ediciones nativas manuales, cómo recuperarse de compilaciones locales de Android dañadas y cómo introducir credenciales en las compilaciones en la nube sin guardarlas.

Código nativo como artefacto de compilación

CNG se basa en un principio: los proyectos nativos son algo que se genera, no algo que se mantiene manualmente.

Ejecutar npx expo prebuild genera las carpetas ios y android a partir de una única fuente de información, que es su app.json o app.config.js. Prebuild lee esa configuración, aplica los cambios nativos que describe y genera proyectos nativos completos listos para compilarse.

Dado que esas carpetas pueden recrearse en cualquier momento, muchos equipos añaden /ios y /android a .gitignore. Cuando una dependencia nativa queda en estado defectuoso, o al actualizar React Native, se descartan esas carpetas y se vuelven a generar. La pregunta cotidiana pasa de “¿qué cambió alguien en el proyecto de Xcode?” a “¿qué declara la configuración?”.

Eso también establece la única regla del modelo: una vez generadas las carpetas nativas, no se deben editar manualmente. Cualquier cambio hecho a mano desaparece en la siguiente fase de preconstrucción. Si se necesita un cambio, debe expresarse a través de la configuración.

Los complementos de configuración reemplazan las ediciones manuales en código nativo

Eso plantea una pregunta obvia: ¿cómo se agrega un permiso a AndroidManifest.xml o se ajusta AppDelegate.mm si los archivos generados están prohibidos para modificaciones?

Los complementos de configuración son la solución. Un complemento de configuración es una función de JavaScript que se ejecuta durante la fase de preconstrucción y modifica el proyecto nativo de manera controlada y reproducible. Las aplicaciones con requisitos nativos exigentes, como el procesamiento de voz en tiempo real o la renderización de modelos 3D, dependen de bibliotecas que necesitan integraciones profundas en el código nativo, y esas bibliotecas suelen incluir sus propios complementos.

En lugar de editar el código nativo, se enumera el plugin y sus opciones en app.json. El ejemplo a continuación utiliza expo-build-properties para establecer la versión compileSdkVersion de Android en 34, un valor que de lo contrario estaría en un archivo Gradle:

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "compileSdkVersion": 34
          }
        }
      ]
    ]
  }
}

En la siguiente fase de preconstrucción, el plugin escribe ese valor en el proyecto Android generado. Dado que el cambio se declara en lugar de aplicarse manualmente, sobrevive a cada regeneración y queda visible durante la revisión del código.

Mantener las compilaciones locales de Android en buen estado

Expo Go es excelente para la creación temprana de prototipos, pero solo incluye los módulos nativos que vienen incluidos con él. Una vez que dependas de código nativo personalizado, debes probarlo con versiones de desarrollo utilizando npx expo run:android o npx expo run:ios. Esto es especialmente importante para aplicaciones que realizan muchos cálculos en el dispositivo, como las funciones de IA, donde es necesario ver el rendimiento real en un dispositivo o emulador.

La cadena de herramientas para Android tiene la reputación de tener cachés frágiles. Un escenario típico: agregas una dependencia y la siguiente compilación local falla con un error poco claro de Java o Gradle. La causa suele ser la salida de compilación obsoleta y no tu propio código.

Lo primero que debes intentar es realizar una compilación limpia. Ve al directorio android generado, ejecuta la tarea de limpieza de Gradle para eliminar las salidas almacenadas en caché y luego vuelve a la raíz del proyecto para compilar nuevamente:

cd android
./gradlew clean
cd ..
npx expo run:android

Si simplemente ejecutar “clean” no es suficiente, CNG ofrece una opción más efectiva: npx expo prebuild --clean elimina y regenera por completo las carpetas nativas, lo cual es seguro precisamente porque nada en ellas se mantiene manualmente. Incorporar estas dos prácticas a tu rutina evita largas sesiones de depuración.

Suministro de credenciales confidenciales para compilaciones en la nube de EAS

CNG resulta especialmente útil cuando se combina con EAS (Expo Application Services) para las compilaciones en la nube.

Tomemos como ejemplo la supervisión de errores. Las aplicaciones en producción la necesitan, y al integrar Sentry es necesario subir mapas de fuente, lo cual requiere un SENTRY_AUTH_TOKEN. Tradicionalmente, ese token tenía que llegar a cada entorno de compilación sin estar en el repositorio, lo cual resultaba complicado de gestionar.

Con CNG y EAS, se agrega el plugin de configuración de Sentry a app.json y nunca se guarda el token. En su lugar, se registra como una variable de entorno en EAS mediante la CLI, otorgándole visibilidad de secret y alcance de proyecto para que esté disponible durante las compilaciones pero no se muestre posteriormente. Ejecute la orden una vez, sustituyendo el valor de marcador por su token real:

eas env:create --name SENTRY_AUTH_TOKEN --value your_token_here --visibility secret --scope projecteas env:create --name SENTRY_AUTH_TOKEN --value your_token_here --visibility secret --scope project

Durante una compilación en la nube, EAS ejecuta el proceso prebuild para generar los proyectos nativos; el plugin de Sentry lee la información secreta del entorno, configura el SDK nativo y sube los mapas de fuente. Ni los archivos nativos ni el token llegan nunca al control de versiones. Las opciones exactas de eas env:create pueden cambiar entre las versiones de la CLI, por lo que consulte la documentación actual de EAS si la orden es rechazada.

Cuando CNG requiere un cuidado adicional

El modelo es potente, pero hay algunas situaciones que requieren planificación:

• Bibliotecas sin complementos. Si un SDK nativo no cuenta con un complemento de configuración, es posible que deba escribir usted mismo un pequeño complemento local en lugar de editar los archivos generados.
• Proyectos existentes en estado “brownfield”. Las aplicaciones con años de código nativo editado a mano no pueden simplemente eliminar sus carpetas; migrar implica primero trasladar cada personalización a la configuración.
• Disciplina del equipo. CNG solo funciona si todos tratan a ios y android como elementos reutilizables. Una simple edición rápida en Xcode se perderá silenciosamente durante la siguiente regeneración.

Conclusión

Expo Prebuild y CNG hacen que las aplicaciones React Native complejas de nivel profesional sean mucho más manejables al convertir las capas nativas en elementos reutilizables:

• Declare los requisitos nativos en app.json o app.config.js y deje que prebuild genere el resto.

Utilice plugins de configuración para cada cambio nativo para que sobreviva a la regeneración.

Limpie los cachés de Gradle o regénerelos con prebuild --clean cuando las compilaciones locales fallen misteriosamente.

Mantenga tokens como SENTRY_AUTH_TOKEN en las variables de entorno de EAS, nunca en el repositorio.

Al reducir los proyectos nativos a resultados de compilación, la atención del equipo vuelve al código de React Native, las interfaces fluidas y las funcionalidades del producto.

Lecturas relacionadas

• Conexión de un módulo Turbo dentro de la aplicación de extremo a extremo con React Native Codegen — Defina una especificación tipada, ejecute codegen e implemente un módulo Turbo en iOS y Android con métodos síncronos, Promise, callback y emisor de eventos.
• Cambio de Tema Permanente en React Native con Contexto y Ganchoes — Crea un cambiador de temas para React Native utilizando Context, useState y useEffect: navegación por pestañas, selector de temas, persistencia con AsyncStorage y protección de carga al iniciar la aplicación.