upgrading-expo

Original：🇺🇸 English
Not Translated

Guidelines for upgrading Expo SDK versions and fixing dependency issues

2installs
Sourcegigs-slc/react-native-skills
Added on

NPX Install

npx skill4agent add gigs-slc/react-native-skills upgrading-expo

SKILL.md Content

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

  1. Upgrade Expo and dependencies
bash
npx expo install expo@latest
npx expo install --fix
  1. Run diagnostics: 
    npx expo-doctor
  2. Clear caches and reinstall
bash
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

If upgrading requires native changes:
bash
npx expo prebuild --clean
This 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.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

Old PackageReplacement
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-gradientexperimental_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

  • autoprefixer
    isn't needed in SDK +53.
  • Use 
    postcss.config.mjs
    in SDK +53.

Metro

Remove redundant metro config options:
  • 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

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.