Mejores prácticas de módulos nativos
Un resumen condensado de las 25 prácticas más importantes de módulos nativos extraídas de cada página en esta sección.
//
Busca en todas las páginas de la documentación
Un resumen condensado de las 25 prácticas más importantes de módulos nativos extraídas de cada página en esta sección.
Busca paquetes de Expo SDK primero: expo-camera, expo-location, expo-secure-store y más de 100 módulos se envían con binarios nativos del SDK 57 - prefierelos a envolturas nativas aleatorias de npm según Reglas de módulos nativos.
Ejecuta la lista de verificación de terceros antes de npm install: Verifica RN 0.86, soporte de New Architecture, disponibilidad de plugin de configuración y mantenimiento - ve Uso de bibliotecas nativas de terceros.
Siempre npx expo install para deps nativos: Resuelve versiones compatibles con binarios nativos del SDK 57 - el éxito de compilación no garantiza estabilidad en tiempo de ejecución.
Trata Expo Go como solo SDK: Los módulos nativos de terceros y personalizados requieren expo-dev-client y un build de desarrollo - nunca apruebes QA desde Expo Go solamente.
Reconstruye nativo después de cada cambio de package.json nativo: Metro hot reload no compila Swift/Kotlin - ejecuta npx expo run:ios / eas build antes de declarar que está hecho.
OTA no puede enviar código nativo: EAS Update entrega solo JavaScript y assets - cambios nativos necesitan un nuevo binario de tienda o cliente de desarrollo.
Expresa permisos en plugins de configuración: Las descripciones de uso de iOS NS*UsageDescription y entradas de manifiesto de Android pertenecen a plugins de app.config - ve Plugins de configuración.
Escribe plugins idempotentes: Ejecutar npx expo prebuild dos veces no debe duplicar entradas en Info.plist o AndroidManifest - git diff después de la segunda ejecución debe estar vacío.
Documenta el orden de plugins en app.config.ts: Los plugins posteriores ganan al modificar la misma clave - comenta por qué expo-router precede a plugins personalizados.
Prefiere expo-build-properties para pines de Gradle/Pod: compileSdkVersion, destino de despliegue y reglas de ProGuard sobreviven a la regeneración - ve Parches de proyectos nativos.
Nunca edites ios/ y android/ a mano en aplicaciones CNG: El siguiente prebuild --clean borra ediciones - codifica cambios en plugins según Conceptos básicos de prebuild.
Usa create-expo-module para puentes locales de aplicación: Expo Modules API integra autolinking, TypeScript y plugins de configuración - ve create-expo-module.
Requiere un ADR para módulos nativos personalizados: Documenta por qué fallaron los paquetes SDK, nombra un mantenedor y planifica pruebas de New Architecture - Reglas de módulos nativos Nivel 3.
Verifica autolinking antes de problemas de Xcode/Gradle: npx expo-modules-autolinking resolve --platform ios muestra qué se compila realmente en el binario.
Alinea Metro y resolución nativa en monorepos: Habilita autolinkingModuleResolution y evita copias de react-native duplicadas - Autolinking y expo-modules-core.
Declara paquetes nativos de workspace como dependencias directas de la aplicación: El autolinking transitivo de módulos packages/* no es confiable - package.json de la aplicación debe enumerarlos explícitamente.
Simula en el límite del servicio en Jest: jest-expo burlarse de módulos de Expo; solo reemplaza lo que las pruebas afirman - ve Burla de módulos nativos.
Un conjunto de Jest que pasa no prueba que lo nativo funcione: Complementa pruebas unitarias con QA en dispositivo o Maestro en un build de desarrollo.
Elige TurboModules solo con justificación: La ceremonia de Codegen + C++ se adapta a las bibliotecas del ecosistema RN - equipos de aplicaciones usan por defecto Expo Modules a menos que compartan core nativo de C++ - Escritura de un TurboModule.
Prueba New Architecture en builds de lanzamiento: RN 0.86 por defecto utiliza Fabric/TurboModules - Metro de depuración puede enmascarar bugs de fallback de bridge; ejecuta --configuration Release en hardware.
Una dependencia nativa por PR cuando sea posible: Mezclar SDK de pago, mapas y módulos personalizados en una fusión hace imposible bisect cuando falla prebuild.
Ejecuta npx expo-doctor después de cada cambio nativo: Detecta versiones incompatibles, plugins faltantes y espacios de trabajo mal configurados antes de CI.
Usa patch-package solo con ticket de remoción: Prefiere plugins de configuración y correcciones ascendentes - parches en node_modules rompen en expo install --fix.
Script de supervivencia posterior a la actualización del SDK nativo: expo install --fix - expo-doctor - prebuild --clean - verificación de idempotencia - compilación de lanzamiento en ambas plataformas.
Lista de verificación previa al lanzamiento nativo: Build de desarrollo en dispositivo, flujos de usuario nativos primarios, rutas de denegación de permisos, expo-modules-autolinking resolve limpio, idempotencia de plugins y reconstrucción de credenciales de tienda si cambiaron dependencias nativas.
Lee primero este resumen para orientarte, luego profundiza en páginas individuales al implementar. Vuelve aquí antes de revisión de código o actualizaciones de SDK.
Usa Expo Go mientras prototipas con módulos solo del SDK. Cambia a expo-dev-client antes de fusionar cualquier dependencia nativa de terceros o personalizada.
Registra el plugin de configuración de la biblioteca en app.config.ts, ejecuta npx expo prebuild --clean y verifica que existan cadenas de descripción de uso en Info.plist generado.
CNG regenera proyectos nativos desde la configuración. Los módulos nativos se instalan a través de autolinking; los plugins de configuración aplican sus permisos y requisitos de compilación durante prebuild - Conceptos básicos de CNG prebuild.
Cuando el SDK de Expo, paquetes de terceros mantenidos y módulos delgados de Expo no pueden cumplir un requisito documentado - con ADR, propietario y plan de QA de dev-client según Reglas de módulos nativos.
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).
Revisado por Chris St. John·Última actualización: 16 jul 2026