npx skills add ...
npx skills add expo/skills --skill expo-upgrade
npx skills add expo/skills --skill expo-upgrade
Framework (OSS). Guidelines for upgrading Expo SDK versions and fixing dependency issues
@react-navigation/* imports to expo-router entry points (codemod + manual mapping)Beta versions use .preview suffix (e.g., 55.0.0-preview.2), published under @next tag.
Check if latest is beta: https://exp.host/--/api/v2/versions (look for -preview in expoVersion)
Run diagnostics: npx expo-doctor
Clear caches and reinstall
First check if ios/ and android/ directories exist in the project. If neither directory exists, the project uses Continuous Native Generation (CNG) and native projects are regenerated at build time — skip this section and "Clear caches for bare workflow" entirely.
If upgrading requires native changes:
This regenerates the ios and android directories. Ensure the project is not a bare workflow app before running this command.
These steps only apply when ios/ and/or android/ directories exist in the project:
cd ios && pod install --repo-updatenpx expo run:ios --no-build-cachecd android && ./gradlew cleanAGENTS.md). The default template links to https://docs.expo.dev/versions/v<version>/. Search for docs.expo.dev/versions/ and bump each link to the new SDK version."experiments": { "reactCompiler": true } to app.json — it's stable and recommendedapp.json to let Expo manage it automaticallypackage.json: @babel/core, babel-preset-expo, expo-constants.| Old Package | Replacement |
|---|---|
expo-av | expo-audio and expo-video |
expo-permissions | Individual package permission APIs |
@expo/vector-icons | expo-symbols (for SF Symbols) |
AsyncStorage | expo-sqlite/localStorage/install |
expo-app-loading | expo-splash-screen |
| expo-linear-gradient | experimental_backgroundImage + CSS gradients in View |
When migrating deprecated packages, update all code usage before removing the old package. For expo-av, consult the migration references to convert Audio.Sound to useAudioPlayer, Audio.Recording to useAudioRecorder, and Video components to VideoView with useVideoPlayer.
Check if package.json has excluded packages:
Exclusions are often workarounds that may no longer be needed after upgrading. Review each one.
Check if there are any outdated patches in the patches/ directory. Remove them if they are no longer needed.
autoprefixer isn't needed in SDK +53. Remove it from dependencies and check postcss.config.js or postcss.config.mjs to remove it from the plugins list.postcss.config.mjs in SDK +53.Remove redundant metro config options:
experimentalImportSupport is enabled by default in SDK +54.EXPO_USE_FAST_RESOLVER=1 is removed in SDK +54.Since SDK 55, users can opt-in to use Hermes engine v1 for improved runtime performance. This requires setting useHermesV1: true in the expo-build-properties config plugin, and may require a specific version of the hermes-compiler npm package. Hermes v1 will become a default in some future SDK release.
The new architecture is enabled by default, the app.json field "newArchEnabled": true is no longer needed as it's the default. Expo Go only supports the new architecture as of SDK +53.
If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
npx expo prebuild --clean{
"expo": { "install": { "exclude": ["react-native-reanimated"] } }
}npx --yes submit-expo-feedback@latest --category skills --subject "expo-upgrade" "<actionable feedback>"