References
- ./references/new-architecture.md -- SDK +53: New Architecture migration guide
- ./references/react-19.md -- SDK +54: React 19 changes (useContext → use, Context.Provider → Context, forwardRef removal)
- ./references/react-compiler.md -- SDK +54: React Compiler setup and migration guide
Step-by-Step Upgrade Process
- Upgrade Expo and dependencies
npx expo install expo@latest
npx expo install --fix- Run diagnostics:
npx expo-doctor - Clear caches and reinstall
npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-allBreaking Changes Checklist
- Check for removed APIs in release notes
- Update import paths for moved modules
- Review native module changes requiring prebuild
- Test all camera, audio, and video features
- Verify navigation still works correctly
Prebuild for Native Changes
If upgrading requires native changes:
npx expo prebuild --cleanThis regenerates the ios and android directories. Ensure the project is not a bare workflow app before running this command.
Clear caches for bare workflow
- Clear the cocoapods cache for iOS:
cd ios && pod install --repo-update - Clear derived data for Xcode:
npx expo run:ios --no-build-cache - Clear the Gradle cache for Android:
cd android &&./gradlew clean
Housekeeping
- Review release notes for the target SDK version at https://expo.dev/changelog
- If using Expo SDK 54 or later, ensure react-native-worklets is installed — this is required for react-native-reanimated to work.
- Enable React Compiler in SDK 54+ by adding
"experiments": {"reactCompiler": true}to app.json — it's stable and recommended - Delete sdkVersion from
app.jsonto let Expo manage it automatically - Remove implicit packages from
package.json:@babel/core,babel-preset-expo,expo-constants. - If the babel.config.js only contains 'babel-preset-expo', delete the file
- If the metro.config.js only contains expo defaults, delete the file
Deprecated Packages
| 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 |
Removing patches
Check if there are any outdated patches in the patches/ directory. Remove them if they are no longer needed.
Postcss
autoprefixerisn't needed in SDK +53.- Use
postcss.config.mjsin SDK +53.
Metro
Remove redundant metro config options:
- resolver.unstable_enablePackageExports is enabled by default in SDK +53.
experimentalImportSupportis enabled by default in SDK +54.EXPO_USE_FAST_RESOLVER=1is removed in SDK +54.- cjs and mjs extensions are supported by default in SDK +50.
- Expo webpack is deprecated, migrate to Expo Router and Metro web.
New Architecture
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.