How to upgrade an Expo app one SDK version at a time

Upgrade an Expo app one SDK version at a time: on a branch, with one native build, then merge. Expo's own guidance is to move one version at a time, and the steps below follow its upgrade walkthrough.

Fitness Kit ships on Expo SDK 58 (expo ~58.0.21, React Native 0.88.1), so the steps below use SDK 58 as the target. Check your own package.json before you start.

The steps

  1. Create a branch. Keep main shippable while you work.
  2. Install the target SDK: npm install expo@^58.0.0.
  3. Align the rest of the dependencies with it: npx expo install --fix.
  4. Check the project: npx expo-doctor.
  5. Refresh the native projects:
    • With Continuous Native Generation, delete android/ and ios/, then regenerate them with npx expo prebuild or npx expo run:ios.
    • Without it, run npx pod-install and follow the native project upgrade helper.
  6. Read the target SDK changelog, especially "Upgrading your app" at the bottom.
  7. Run the native build once on a device or emulator, then merge.

What changed in SDK 58

Expo's changelog says SDK 58 shipped on 15 October 2026 and moved React Native from 0.86 to 0.88. SDK 57 was 30 June 2026, and SDK 56 was 21 May 2026.

Expo Go supports only the latest SDK, and Expo recommends development builds for production apps. If your app runs in Expo Go, expect to build a development build once you upgrade.

Our advice

  • Do the next version only, on a branch.
  • Build the native app once after the upgrade, not after every package change.
  • Merge when the build runs on a device.

Expo's walkthrough doesn't say these three things; they are our advice.

Before you start

Pick one target version and write it down. For a Fitness Kit app that is SDK 58, and for any other app it is the next SDK after the one you run today. Do not jump two versions at once, even when the changelog for the later one looks shorter. Each step has its own native changes, and a skipped step means you debug two sets of breaking changes at the same time.

Before you touch any code, record what runs today. Note the current expo version, the React Native version, whether the app runs in Expo Go or a development build, and which native modules you use directly, such as camera, notifications, secure storage or in-app purchases. Commit or stash your work so the diff you review later contains only the upgrade. Our advice: take a screenshot of the main screens on a device, so you have something to compare against after the upgrade.

Read the changelog before you change code

The SDK changelog is the source of truth for what changed, and the "Upgrading your app" section at the bottom is the part to read first. Sort what you find into three buckets. The first is packages you import yourself, which you must check line by line. The second is native modules your app depends on indirectly, such as a navigation or gesture library that a component pulls in. The third is configuration changes, in app.json or the config plugins you use.

Packages you never import can wait. Native modules in the second bucket are the ones that break builds quietly, because the JavaScript still loads and only the native side fails.

Work through the errors in order

After npm install expo@^58.0.0 and npx expo install --fix, run npx expo-doctor and treat its output as a to-do list. Fix the dependency mismatches first, because they often cause the other failures. Then fix configuration. Leave native problems for last. Re-run expo-doctor after each batch of fixes, so you know which change cleared which problem. If a warning survives two rounds, look it up in the changelog before you work around it.

Peer dependency warnings from the package manager are not noise. A peer that does not match the SDK is the most common cause of a crash that only shows up in a release build.

Refresh the native projects

If the app uses Continuous Native Generation, android/ and ios/ are generated output. Delete them and regenerate with npx expo prebuild or npx expo run:ios. Anything you changed by hand in those folders is lost on regeneration, so move that code into a config plugin before you delete the folders. Our advice: diff the regenerated folders against the old ones once, so you see every change before you commit.

Without CNG, run npx pod-install and follow the native project upgrade helper. Review each native file it changes. Do not accept a change you cannot explain.

Build once, then test on a device

Run the native build one time on a device or emulator. Do not rebuild after each package change; each build is slow, and the errors you fix in between often hide the real problem. Once the build runs, test the flows the upgrade could touch, not only the home screen:

  • A cold start from a killed app, not a warm reload.
  • Sign-in and sign-out, and anything that stores a session.
  • Every native module from the second bucket, such as the camera, notifications, deep links or file access.
  • A release build, not only a development build, because release builds catch minification and dependency issues that development builds hide.

These checks are our advice. They are not part of Expo's walkthrough.

When to stop

If the build still fails after two rounds of fixes, stop. Go back to main, open a fresh branch, and start the upgrade again with a clearer list of what broke. Do not merge a partly upgraded app. A half-upgraded branch on main is harder to undo than a closed pull request.

Expo Go and development builds

Expo Go runs only the latest SDK. Once you move to SDK 58, a project that runs in Expo Go on an older SDK stops opening there, so plan the switch to a development build before you merge. Expo recommends development builds for production apps, and that recommendation is the reason to make the switch now rather than later.

Checklist

Keep this list open while you work:

  1. One target version, written down.
  2. Current versions and native modules recorded.
  3. Changelog read, with the bottom section first.
  4. expo install --fix and expo-doctor run until the warnings are explained.
  5. Native projects regenerated or pod-installed, with changes reviewed.
  6. One native build on a device.
  7. Cold start, sign-in and the native modules tested in a release build.
  8. Merged only after the device test passes.

Fitness Kit ships on SDK 58 with a working setup you can compare against. If you want a starting point rather than an upgrade, the kit is at /templates/fitness-kit?utm_link=kit, and the live demo is one click away from there.

Sources

  • Expo, "Upgrading Expo SDK" walkthrough, docs.expo.dev/workflow/upgrading-expo-sdk-walkthrough (page modified 2 November 2026). Accessed 11 November 2026.
  • Expo, "Expo SDK 58" changelog, expo.dev/changelog/sdk-58. Accessed 11 November 2026.