upgrading-expo

$2a

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

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.

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

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

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.

Hermes engine v1

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.

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.