Un manual para evaluar, instalar y verificar librerías nativas de la comunidad en una app Expo SDK 57 CNG - con verificaciones explícitas de viabilidad de prebuild y compatibilidad con Nueva Arquitectura en React Native 0.86.
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
# 1. Evalúa ANTES de instalar (ve lista de verificación a continuación)# 2. Instala con el resolver de Expo - no npm simplenpx expo install react-native-maps# 3. Registra el plugin de configuración en app.config.ts (si la librería incluye uno)# 4. Regenera proyectos nativos y verificanpx expo prebuild --cleannpx expo-doctor# 5. Construye un cliente de desarrollo - el código nativo de terceros NO está en Expo Gonpx expo install expo-dev-clientnpx expo run:ios# o: eas build --profile development --platform all
// app.config.ts - registro típico de plugin de tercerosimport type { ExpoConfig } from "expo/config";export default ({ config }: { config: ExpoConfig }): ExpoConfig => ({ ...config, plugins: [ [ "react-native-maps", { iosGoogleMapsApiKey: process.env.GOOGLE_MAPS_IOS_KEY, androidGoogleMapsApiKey: process.env.GOOGLE_MAPS_ANDROID_KEY, }, ], ],});
Cuándo usar esto:
Adoptando react-native-maps, react-native-ble-plx, react-native-purchases, o cualquier paquete npm con carpetas ios/ / android/.
Auditando si una librería sobrevive npx expo prebuild --clean en un flujo de trabajo CNG.
Confirmando soporte de RN 0.86 Nueva Arquitectura antes de fusionar un PR de dependencia.
Reemplazando un contenedor nativo deprecado con un equivalente de Expo SDK.
# Regenera directorios nativos y ejecuta en simuladornpx expo prebuildnpx expo run:ios# Inicia Metro para el cliente de desarrollo (no Expo Go)npx expo start --dev-client
Lo que esto demuestra:
npx expo install resuelve una versión compatible con binarios nativos de SDK 57.
Plugin de configuración inyecta claves API en Info.plist y AndroidManifest.xml durante prebuild.
expo prebuild conecta autolinking - sin ediciones manuales de Podfile en apps CNG.
Compilación de desarrollo es obligatoria - react-native-maps no está incluido en Expo Go.
React Native 0.86 usa por defecto Nueva Arquitectura (Fabric - TurboModules). Las librerías de terceros caen en tres categorías:
Categoría
Síntoma
Mitigación
Totalmente compatible
Compila y ejecuta en dispositivo
Publica
Parcial (fallback del bridge)
Compila pero APIs JSI sincrónicas fallan
Prueba cada API que llamas; abre issue aguas arriba
Incompatible
Error de compilación o crash instantáneo
No adoptes; encuentra alternativa o haz un fork
# Confirma Nueva Arquitectura en proyecto generadogrep -r "newArchEnabled" android/ ios/ 2>/dev/null || true# Verifica por fuerza con compilación de release en dispositivo (no solo Metro de debug)npx expo run:ios --configuration Release
Las librerías que usan solo bridge antiguo de NativeModules aún pueden ejecutarse vía capa de interoperabilidad, pero rutas sensibles al rendimiento (mapas, vídeo, BLE) deben validarse en hardware físico - los simuladores ocultan bugs de threading.
Nunca documentes "agrega esta línea a AndroidManifest.xml" como paso permanente - codifícalo en un plugin de configuración para que la regeneración se mantenga limpia. Ve Prebuild Basics y Config Plugins in CNG.
# Lista módulos que compilarán en el binarionpx expo-modules-autolinking resolve --platform iosnpx expo-modules-autolinking resolve --platform android# Autolinking de comunidad React Native (paquetes no-Expo)npx react-native config
Si un paquete aparece en package.json pero no en salida de resolve, la compilación nativa nunca lo compiló - requireNativeModule lanzará error en tiempo de ejecución.
Probar en Expo Go después de npm install - falta código nativo de terceros del binario Go. Solución:npx expo start --dev-client con compilación personalizada.
Omitir prebuild después de cambio de configuración de plugin - entradas obsoletas en Info.plist. Solución:npx expo prebuild --clean localmente antes de fusionar.
Asumir que TypeScript verde en CI significa que nativo funciona - Jest no ejecuta código nativo. Solución: QA en dispositivo o flujo Maestro en compilación de desarrollo.
Fijar @latest en paquetes nativos - rompe alineación ABI de SDK 57. Solución:npx expo install o versión explícita con ADR.
Mezclar múltiples SDKs de mapa/BLE/pago en un PR - pesadilla de bisect cuando prebuild falla. Solución: Una dependencia nativa por PR por Native Module Rules.
¿Puedo usar cualquier paquete react-native-* con Expo?
Solo si soporta prebuild/autolinking, tiene un plugin de configuración (o escribes uno), y compila en RN 0.86 Nueva Arquitectura. npx expo-doctor captura fallos comunes tempranamente.
¿Confirmo ios/ y android/ después de agregar una librería?
La política de equipo varía. Equipos de CNG a menudo gitignore directorios nativos y regeneran en CI. Si los confirmas, aún expresa cambios vía plugins - no drift manual. Ve Mejores prácticas de CNG.
¿Cómo pruebo compatibilidad de Nueva Arquitectura rápidamente?
npx expo run:ios --configuration Release en dispositivo físico con flujo de usuario primario de la librería. Metro de debug puede ocultar issues de threading nativo.
La librería no tiene plugin de configuración - ¿ahora qué?
Escribe un plugin local en plugins/ o elige un fork mantenido. Ediciones manuales posteriores a prebuild son deuda técnica en apps CNG.
¿expo install vs npm install?
npx expo install lee tabla de compatibilidad de Expo para SDK 57. npm install puede resolver JS que no coincide con binarios nativos en tu compilación.