upgrading-expo

When to Use

Use this skill when you need guidelines for upgrading Expo SDK versions and fixing dependency issues.

References

• ./references/react-19.md -- SDK +54: React 19 changes (useContext → use, Context.Provider → Context, forwardRef removal)
• ./references/new-architecture.md -- SDK +53: New Architecture migration guide
• ./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 -- SDK +55: Migrate audio playback and recording from expo-av to expo-audio
• ./references/expo-av-to-video.md -- SDK +55: Migrate video playback from expo-av to expo-video
• ./references/react-navigation-to-expo-router.md -- SDK +56: Migrate @react-navigation/* imports to expo-router entry points (codemod + manual mapping)

Beta/Preview Releases

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)

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

2. Run diagnostics: npx expo-doctor

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

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:

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

These steps only apply when ios/ and/or android/ directories exist in the project:

• 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

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.

expo.install.exclude

Check if package.json has excluded packages:

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

Exclusions are often workarounds that may no longer be needed after upgrading. Review each one.

Removing patches

…