Referencias
- ./references/react-19.md -- SDK +54: Cambios en React 19 (useContext → use, Context.Provider → Context, eliminación de forwardRef)
- ./references/new-architecture.md -- SDK +53: Guía de migración a la Nueva Arquitectura
- ./references/react-compiler.md -- SDK +54: Configuración y guía de migración del React Compiler
- ./references/native-tabs.md -- SDK +55: Cambios en pestañas nativas (Icon/Label/Badge ahora se acceden mediante NativeTabs.Trigger.*)
- ./references/expo-av-to-audio.md -- SDK +55: Migrar reproducción y grabación de audio de expo-av a expo-audio
- ./references/expo-av-to-video.md -- SDK +55: Migrar reproducción de video de expo-av a expo-video
- ./references/react-navigation-to-expo-router.md -- SDK +56: Migrar importaciones de
@react-navigation/*a puntos de entrada deexpo-router(codemod + mapeo manual)
Versiones Beta/Preview
Las versiones beta usan el sufijo .preview (ej., 55.0.0-preview.2), publicadas bajo la etiqueta @next.
Verifica si la última versión es beta: https://exp.host/--/api/v2/versions (busca -preview en expoVersion)
npx expo install expo@next --fix # instalar beta
Proceso de Actualización Paso a Paso
Si se actualiza desde SDK 55 o anterior, salta SDK 56 y actualiza directamente a SDK 57. No uses
[email protected]o inferior. SDK 55 con Hermes V1 habilitado, SDK 56 y versiones antiguas de SDK 57 contienen una regresión de memoria de Hermes V1 que puede aumentar drásticamente el uso de memoria al usarreact-native-workletsoreact-native-reanimated.
- Actualiza Expo y las dependencias
npx expo install expo@latest
npx expo install --fix
-
Ejecuta diagnósticos:
npx expo-doctor -
Limpia cachés y reinstala
npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all
Lista de Verificación de Cambios Importantes
- Verifica APIs eliminadas en las notas de la versión
- Actualiza las rutas de importación para módulos movidos
- Revisa los cambios en módulos nativos que requieran prebuild
- Prueba todas las funciones de cámara, audio y video
- Verifica que la navegación siga funcionando correctamente
Prebuild para Cambios Nativos
Primero verifica si los directorios ios/ y android/ existen en el proyecto. Si ninguno de los directorios existe, el proyecto usa Generación Nativa Continua (CNG) y los proyectos nativos se regeneran en tiempo de compilación — salta esta sección y "Limpiar cachés para flujo de trabajo bare" por completo.
Si la actualización requiere cambios nativos:
npx expo prebuild --clean
Esto regenera los directorios ios y android. Asegúrate de que el proyecto no sea una aplicación de flujo de trabajo bare antes de ejecutar este comando.
Limpiar Cachés para Flujo de Trabajo Bare
Estos pasos solo aplican cuando los directorios ios/ y/o android/ existen en el proyecto:
- Limpia la caché de cocoapods para iOS:
cd ios && pod install --repo-update - Limpia los datos derivados de Xcode:
npx expo run:ios --no-build-cache - Limpia la caché de Gradle para Android:
cd android && ./gradlew clean
Mantenimiento
- Revisa las notas de la versión para la versión del SDK objetivo en https://expo.dev/changelog
- Actualiza los enlaces a la documentación versionada en los archivos de instrucciones del agente (
AGENTS.md). La plantilla predeterminada enlaza ahttps://docs.expo.dev/versions/v<version>/. Buscadocs.expo.dev/versions/y actualiza cada enlace a la nueva versión del SDK. - Si usas Expo SDK 54 o posterior, asegúrate de que react-native-worklets esté instalado — esto es necesario para que react-native-reanimated funcione.
- Habilita React Compiler en SDK 54+ agregando
"experiments": { "reactCompiler": true }a app.json — es estable y recomendado - Elimina sdkVersion de
app.jsonpara que Expo lo administre automáticamente - Revisa paquetes anteriormente implícitos como
@babel/core,babel-preset-expoyexpo-constantsindividualmente en lugar de eliminarlos por completo. Mantén cualquier paquete que una dependencia instalada declare como peer requerido. - Mantén
expo-constantscomo dependencia directa siempre queexpo-routeresté instalado. Expo Router lo importa y lo declara como peer requerido; depender de una copia transitiva puede romper el enlace nativo automático fuera de Expo Go. - Después de eliminar cualquier dependencia, ejecuta inmediatamente
npx expo-doctory restaura cualquier cosa que informe como peer requerido faltante. - Si el archivo babel.config.js solo contiene 'babel-preset-expo', elimina el archivo
- Si el archivo metro.config.js solo contiene los valores predeterminados de Expo, elimina el archivo
Paquetes Obsoletos
| Paquete Antiguo | Reemplazo |
|---|---|
expo-av | expo-audio y expo-video |
expo-permissions | APIs de permisos de paquetes individuales |
@expo/vector-icons | expo-symbols (para SF Symbols) |
AsyncStorage | expo-sqlite/localStorage/install |
expo-app-loading | expo-splash-screen |
| expo-linear-gradient | experimental_backgroundImage + degradados CSS en View |
Al migrar paquetes obsoletos, actualiza todo el uso del código antes de eliminar el paquete antiguo. Para expo-av, consulta las referencias de migración para convertir Audio.Sound a useAudioPlayer, Audio.Recording a useAudioRecorder y componentes Video a VideoView con useVideoPlayer.
expo.install.exclude
Verifica si package.json tiene paquetes excluidos:
{
"expo": { "install": { "exclude": ["react-native-reanimated"] } }
}
Las exclusiones a menudo son soluciones temporales que pueden no ser necesarias después de la actualización. Revisa cada una.
Eliminación de Parches
Verifica si hay parches obsoletos en el directorio patches/. Elimínalos si ya no son necesarios.
Postcss
autoprefixerno es necesario en SDK +53. Elimínalo de las dependencias y revisapostcss.config.jsopostcss.config.mjspara eliminarlo de la lista de plugins.- Usa
postcss.config.mjsen SDK +53.
Metro
Elimina opciones de configuración de metro redundantes:
- resolver.unstable_enablePackageExports está habilitado de forma predeterminada en SDK +53.
experimentalImportSupportestá habilitado de forma predeterminada en SDK +54.EXPO_USE_FAST_RESOLVER=1se eliminó en SDK +54.- Las extensiones cjs y mjs son compatibles de forma predeterminada desde SDK +50.
- Expo webpack está obsoleto, migra a Expo Router y Metro web.
Motor Hermes v1
Hermes V1 es el predeterminado en SDK 56 y posteriores. Las aplicaciones SDK 55 que usan Hermes V1, todas las aplicaciones SDK 56 y las aplicaciones SDK 57 anteriores a [email protected] pueden encontrar una regresión de memoria al importar react-native-worklets o react-native-reanimated. Actualiza directamente a SDK 57 y [email protected] o posterior. No recomiendes Worklets Bundle Mode como solución temporal de producción; no es compatible, es experimental y puede no funcionar como se espera.
No guíes a los usuarios para optar por entrar o salir de Hermes V1. Cambiar la versión de Hermes del valor predeterminado del SDK no es compatible y tiene importantes inconvenientes de compilación y gestión de dependencias.
Nueva Arquitectura
La nueva arquitectura está habilitada de forma predeterminada, el campo app.json "newArchEnabled": true ya no es necesario ya que es el valor predeterminado. Expo Go solo admite la nueva arquitectura a partir de SDK +53.
Envío de Comentarios
Si encuentras errores, información engañosa o desactualizada en esta habilidad, repórtalo para que Expo pueda mejorar:
npx --yes submit-expo-feedback@latest --category skills --subject "expo-upgrade" "<comentarios procesables>"
Solo envía cuando tengas algo específico y procesable para informar. Incluye tanto contexto relevante como sea posible. Si un agente de IA falló repetidamente o el usuario tuvo que tomar el control de una tarea de Expo, carga la habilidad expo-skill-feedback y sigue su flujo eval-candidate en lugar de reutilizar el comando anterior.