How to upgrade the Expo SDK without breaking your app

Upgrading the Expo SDK is one of those tasks that gets postponed until the store forces your hand. Then you find several versions of backlog, libraries that no longer match and a build that fails with an error that tells you nothing. After doing it many times across several apps, this is the process that causes me the fewest problems.

The main idea is simple: upgrade little and often, one SDK at a time, and never mix the upgrade with new features.

Before you touch anything

Spend ten minutes on preparation, because they will save you hours later:

• Commit everything and work on a separate branch.
• Check that the current app builds and runs. If it was already broken, you will not know whether the upgrade broke it.
• Read the release notes of the SDK you are moving to. Expo lists the breaking changes and the minimum versions of React Native, Node and the native tools.
• Make a list of the native libraries you use that are not part of Expo, such as billing, ads or notifications. They are the ones that usually cause trouble.

Upgrade one SDK at a time

It is tempting to jump from an old version straight to the latest one. Don’t. If something fails, you won’t know which change caused it. Going one version at a time takes longer on paper, but each step is small and easy to fix.

First, install the new version of Expo:

npx expo install expo@latest

Then let Expo align the rest of the dependencies with that SDK:

npx expo install --fix

This command adjusts the versions of the packages Expo knows about so they are compatible with each other. It will not touch third-party libraries it doesn’t manage, and those you have to review by hand.

Check the project health

Expo includes a tool that detects the most common problems, such as duplicated dependencies, versions that do not match or invalid configuration:

npx expo-doctor

Fix what it reports before going on. Most of the time it points straight at the cause of a later error.

Review the third-party libraries

This is the part that takes the longest. For each native library outside Expo:

• Check that its latest version supports the SDK and the React Native version you now have.
• Read its changelog looking for breaking changes.
• If it is no longer maintained, look for an alternative before you upgrade, not after.

Billing and ad libraries deserve special attention. They change their APIs often, and a mistake there affects your revenue directly, so test purchases and ads on a real device before publishing.

Regenerate the native projects

If you use prebuild and do not commit the android and ios folders, regenerate them from scratch so no old configuration is left over:

npx expo prebuild --clean

If you do commit those folders and made manual changes to them, compare them carefully with the new template before overwriting anything.

Clean the caches

Many strange errors disappear after cleaning the caches. Start the bundler without cache and, if you still have doubts, reinstall the dependencies:

npx expo start --clear
rm -rf node_modules
npm install

Test before you publish

A successful build does not mean the app works. These are the things I always check:

• Startup and navigation between the main screens.
• Login and anything that uses the backend.
• Purchases, subscriptions and restoring purchases.
• Ads, if you use them.
• Push notifications.
• Permissions, such as camera, location or storage.

Test it on a real Android device and an iPhone, not just on the emulator. Some native problems only show up there.

Common errors and where to look

• Version conflicts when installing: run npx expo install --fix again and check for packages that pin an old version of a dependency.
• Build fails on Android: check the Gradle and Java version required by the new SDK and clean the Gradle cache.
• Build fails on iOS: reinstall the pods and check that the Xcode version is the minimum required.
• A library crashes on startup: it is probably not compatible with the new React Native version. Look at its open issues.

Final advice

Do not leave it for later. Every SDK you skip makes the next jump bigger and more painful. If you keep several apps, set aside a fixed time to upgrade them in sequence and you will avoid emergency migrations when the store deadline arrives.