upgrading-expo

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
• ./references/native-tabs.md -- SDK +55: Native tabs changes (Icon/Label/Badge now accessed via NativeTabs.Trigger.*)
• ./references/expo-av-to-audio.md -- Migrate audio playback and recording from expo-av to expo-audio
• ./references/expo-av-to-video.md -- Migrate video playback from expo-av to expo-video

Beta/Preview Releases

.preview

55.0.0-preview.2

@next

-preview

expoVersion

npx expo install expo@next --fix  # install beta

Step-by-Step Upgrade Process

1. Upgrade Expo and dependencies

npx expo install expo@latest
npx expo install --fix

1. Run diagnostics:

   npx expo-doctor

2. Clear caches and reinstall

npx expo export -p ios --clear
rm -rf node_modules .expo
watchman watch-del-all

Breaking 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

npx expo prebuild --clean

ios

android

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.json

  to 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

expo-av

expo-audio

expo-video

expo-permissions

@expo/vector-icons

expo-symbols

AsyncStorage

expo-sqlite/localStorage/install

expo-app-loading

expo-splash-screen

expo.install.exclude

{
  "expo": { "install": { "exclude": ["react-native-reanimated"] } }
}

Removing patches

patches/

Postcss

• 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.
• Use

  postcss.config.mjs

  in SDK +53.

Metro

• resolver.unstable_enablePackageExports is enabled by default in SDK +53.

• experimentalImportSupport

  is enabled by default in SDK +54.

• EXPO_USE_FAST_RESOLVER=1

  is 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

"newArchEnabled": true