Expo SDK Upgrade Guide

Guidelines for upgrading Expo SDK versions and fixing dependency issues. Based on official Expo skills.

Step-by-Step Upgrade Process

1. Upgrade Expo and Dependencies

# Upgrade to latest SDK
npx expo install expo@latest

# Fix peer dependencies
npx expo install --fix

2. Run Diagnostics

npx expo-doctor

3. Clear Caches and Reinstall

# Clear Expo cache
npx expo export -p ios --clear

# Clean install
rm -rf node_modules .expo
watchman watch-del-all
npm install  # or bun install

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
Test push notifications
Verify deep linking

Prebuild for Native Changes

If upgrading requires native changes:

npx expo prebuild --clean

This regenerates the ios and android directories. Only run on managed workflow projects.

Clear Caches for Bare Workflow

iOS

# Clear CocoaPods cache
cd ios && pod install --repo-update

# Clear derived data
npx expo run:ios --no-build-cache

# Full clean
rm -rf ios/Pods ios/Podfile.lock
cd ios && pod install

Android

# Clear Gradle cache
cd android && ./gradlew clean

# Full clean
rm -rf android/.gradle android/build android/app/build

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

Migration Examples

expo-av to expo-audio/expo-video

// Before
import { Audio, Video } from 'expo-av';

// After
import { Audio } from 'expo-audio';
import { VideoView } from 'expo-video';

AsyncStorage to expo-sqlite

// Before
import AsyncStorage from '@react-native-async-storage/async-storage';

// After
import { localStorage } from 'expo-sqlite/localStorage';
await localStorage.setItem('key', 'value');
const value = await localStorage.getItem('key');

Housekeeping

Remove from package.json

These are now implicit dependencies:

@babel/core
babel-preset-expo
expo-constants

Delete Redundant Config Files

If babel.config.js only contains 'babel-preset-expo', delete it.

If metro.config.js only contains expo defaults, delete it.

app.json Cleanup

Delete sdkVersion - let Expo manage it automatically
Remove "newArchEnabled": true in SDK 53+ (it's the default)

SDK-Specific Changes

SDK 54+ (React 19)

React 19 Changes

// Before - useContext
const value = React.useContext(MyContext);

// After - use
const value = React.use(MyContext);

// Before - Context.Provider
<MyContext.Provider value={value}>

// After - Context directly
<MyContext value={value}>

// Before - forwardRef
const Component = React.forwardRef((props, ref) => { ... });

// After - ref in props
const Component = ({ ref, ...props }) => { ... };

React Compiler (Recommended)

Enable in app.json:

{
  "expo": {
    "experiments": {
      "reactCompiler": true
    }
  }
}

Required Dependencies

# Required for react-native-reanimated in SDK 54+
npx expo install react-native-worklets

SDK 53+ (New Architecture)

The new architecture is enabled by default. Expo Go only supports new architecture.

Metro Config

Remove redundant options (now defaults):

resolver.unstable_enablePackageExports
experimentalImportSupport (SDK 54+)
EXPO_USE_FAST_RESOLVER=1 (removed in SDK 54)

PostCSS

autoprefixer isn't needed in SDK 53+
Use postcss.config.mjs (not .js)

SDK 50+

cjs and mjs extensions supported by default
Expo Webpack deprecated - migrate to Expo Router + Metro web

Troubleshooting

Common Issues

"Cannot find module" errors

# Clear Metro cache
npx expo start --clear

TypeScript errors after upgrade

# Reinstall types
npx expo install --fix
npm install @types/react@latest @types/react-native@latest

Native module not found

# Rebuild native projects
npx expo prebuild --clean
npx expo run:ios  # or run:android

CocoaPods issues

# Full pod reinstall
cd ios
rm -rf Pods Podfile.lock
pod install --repo-update

Verifying the Upgrade

# Check for issues
npx expo-doctor

# Verify TypeScript
npx tsc --noEmit

# Run tests
npm test

# Start development
npx expo start

Removing Patches

Check patches/ directory for outdated patches that may no longer be needed after upgrade. Remove and test.

Resources

Release notes: https://expo.dev/changelog
Upgrade helper: https://docs.expo.dev/workflow/upgrading-expo-sdk/
Breaking changes: https://docs.expo.dev/versions/latest/

expo-upgrading