upgrading-expo

name	upgrading-expo
description	Guidelines for upgrading Expo SDK versions and fixing dependency issues
license	MIT
compatibility	Claude Code, Cursor, Gemini CLI, GitHub Copilot
metadata	{"author":"jhm1909","version":"2.0.0","domain":"mobile","estimated_tokens":2500}

Upgrading Expo

Knowledge Graph

• extends: [[mobile-developer]]
• requires: []
• suggests: []
• conflicts: []
• enhances: []
• moc: [[mobile-development-moc]]

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

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

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

• 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

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.