expo-sdk-upgrade

Expo SDK upgrades without a lost weekend

Ground rules

• One SDK version at a time. Two majors in one jump doubles the breakage and halves your ability to bisect it.
• Upgrade on a branch and keep the app runnable on main. You will want to diff against a working tree.
• Read the SDK changelog before touching anything. The "Breaking changes" and "Deprecations" sections are short and they are the whole game.
• Budget real time for it. A clean upgrade is an afternoon; a project with many native libraries can take days.

The order of operations

# 1. Update the expo package itself to the target SDK
#    (57 was current when this was written; check expo.dev/changelog)
npm install expo@^57.0.0

# 2. Let Expo align every SDK-managed dependency to the versions it was tested with
npx expo install --fix

# 3. Ask for a health report
npx expo-doctor

expo install --fix is the step people skip and then pay for. React Native, React, Reanimated, gesture-handler, screens and the rest are version-coupled per SDK. Mixing "latest of everything" is the most common source of upgrade crashes.

Then:

# 4. Regenerate native projects if the repo uses CNG (no manual edits under ios/ or android/)
npx expo prebuild --clean

# 5. Run both platforms before declaring victory
npx expo run:ios
npx expo run:android

What expo-doctor tells you and what it cannot

expo-doctor validates dependency versions against React Native Directory metadata and flags unmaintained or incompatible packages. Take its "unmaintained" flags seriously: abandoned native libraries block more upgrades than anything else, and swapping one is often cheaper than patching it.

It cannot catch runtime behavior changes. A library can install cleanly and still break at runtime because of a renamed prop or a New Architecture difference, which is why step 5 is non-negotiable.

Version-coupled packages

• react-native-reanimated: tightly coupled to the React Native version. Never pin it ahead of or behind what expo install chooses.
• react-native-gesture-handler, react-native-screens, react-native-safe-area-context: same rule.
• Anything with a config plugin: plugin APIs shift between SDKs, so a library's plugin can throw during prebuild even when its runtime code is fine. The error names the plugin; check that library's release notes for the SDK you are targeting.