Expo SDK Upgrade Guide: Upgrade Now, Test First, or Wait?
An Expo SDK upgrade is not just a package update. It can change the React Native version, native build tools, configuration plugins, Expo Go support, and the behavior of the iOS and Android projects generated by prebuild.
The safest decision is not always "upgrade immediately." It is the option that keeps your app buildable, testable, and recoverable. This guide gives you a repeatable way to choose between upgrading now, testing in a separate branch, or waiting for a specific blocker to be resolved.
The short answer
Use this decision rule:
| Decision | Choose it when |
|---|---|
| Upgrade now | The target SDK is stable, your critical native dependencies support it, both release builds work, and you have time for a controlled rollout. |
| Test first | The upgrade contains native or tooling changes, you use custom native code, or a new SDK is still in beta. |
| Wait | A critical dependency is incompatible, your release pipeline is already unstable, or you cannot verify and roll back the change safely. |
Waiting should still produce an action: record the blocker, assign an owner, and choose a date to check it again. "Wait" without a reason or review date is just unmanaged dependency drift.
Start with a reproducible baseline
Before changing a dependency, prove that the current app works. Record:
- the current Expo SDK and React Native versions;
- the Node.js and package-manager versions used locally and in CI;
- a clean dependency install from the lockfile;
- successful Android and iOS release builds;
- the result of your unit, integration, and end-to-end tests;
- the EAS Build profiles and update channels used for production;
- the commit or tag you will return to if the migration fails.
Run Expo's diagnostic tools against the current branch:
npx expo install --check
npx expo-doctor
Fix baseline failures before the upgrade. Otherwise, you will not know whether a failure was introduced by the new SDK or already existed.
Inventory the parts that can break
The expo package is only one part of the migration. Build an inventory of:
- Expo packages and config plugins;
- React Native libraries with native iOS or Android code;
- custom changes in
ios/andandroid/; - local Expo modules;
- authentication, notifications, maps, camera, media, payments, and deep links;
- build-time environment variables and secrets;
- EAS Build, Submit, and Update configuration;
- minimum iOS and Android versions required by your users.
For every critical native library, check its release notes and issue tracker for the target Expo SDK and React Native version. A JavaScript package that installs successfully can still fail during CocoaPods, Gradle, code generation, or at runtime on a physical device.
Remove unused native libraries before upgrading. A smaller dependency surface means fewer compatibility checks and fewer places for native builds to fail.
Know how your native projects are managed
Your upgrade path depends on whether the project uses Continuous Native Generation.
If ios/ and android/ are generated
Treat app.json, app.config.*, config plugins, and package versions as the
source of truth. Expo's upgrade guide recommends regenerating native projects
that were created for an older SDK instead of carrying generated output forward.
Do not delete native directories until you have verified that they contain no handwritten changes. Move any required behavior into a config plugin or another tracked source first.
If native projects are maintained manually
Keep the native directories and apply the required changes deliberately. Use Expo's native project upgrade helper and the release notes for the target SDK. Then run CocoaPods and Gradle from a clean state and inspect the native diff.
Do not combine a switch to prebuild with a framework upgrade unless that is the explicit goal. Two migrations in one change make failures harder to diagnose.
Upgrade one SDK at a time
Expo recommends incremental SDK upgrades. Moving one SDK at a time makes it easier to identify the release that introduced a breaking change and to follow the correct migration notes.
For a stable release, the core workflow is:
# Replace the version with the stable SDK you are targeting.
pnpm add expo@^57.0.0
npx expo install --fix
npx expo-doctor
Then follow the version-specific release notes. The command aligns compatible Expo packages, but it cannot verify your business-critical flows, custom native code, or backend contracts.
Use a dedicated branch and keep the upgrade diff narrow. Avoid redesigns, navigation rewrites, analytics migrations, or unrelated features in the same change.
Current release watch: Expo SDK 58 beta
This section reflects the release state on September 29, 2026. The title and URL of this guide remain stable; this section is updated as releases change.
Expo opened the SDK 58 beta on September 15, 2026 and described a three-to-four week beta period. The beta includes the React Native 0.88 release candidate, targets iOS 27, moves generated iOS projects to the scene-based lifecycle, and includes Expo Modules 2.0 in beta on both platforms.
That makes SDK 58 useful for compatibility testing, but not a routine production upgrade for every app yet. Test it now when you need to prepare for iOS 27, own custom native integrations, or maintain a library that should be ready when the stable SDK ships. Wait for the stable release when your app has no urgent SDK 58 requirement and the beta would add release risk without a clear benefit.
If you test the beta, use Expo's beta instructions and keep it isolated from the production branch:
npx expo install expo@next --fix
npx expo-doctor
Review the SDK 58 changelog again before shipping. Beta behavior, build images, and migration guidance can change before the stable release.
Run a release-focused test matrix
A successful development launch is not enough. Test the surfaces users and your release pipeline depend on.
Build and startup
- clean Android release build;
- clean iOS archive or release build;
- EAS Build for each production profile;
- cold start on at least one physical iOS and Android device;
- app launch from notifications and deep links.
Product flows
- sign-up, sign-in, token refresh, and sign-out;
- onboarding and navigation restoration;
- API requests, offline states, and retry behavior;
- camera, media library, maps, location, and file access;
- push-notification permission and delivery;
- purchases, subscriptions, or checkout;
- analytics, crash reporting, and consent flows.
Upgrade behavior
- install the new build over the current production build;
- verify persisted auth and local storage;
- test database and state migrations;
- confirm that an OTA update targets only a compatible runtime;
- verify that the previous production binary still behaves correctly.
Test on the oldest OS version you support as well as the newest. Framework upgrades often expose assumptions at the edges of the support matrix.
Treat OTA updates and native builds as different releases
Expo Updates can deliver compatible JavaScript and assets, but it cannot replace native code in an installed binary. If the SDK upgrade changes native modules, configuration plugins, permissions, or the runtime version, users need a new store build.
Before rollout, verify:
- the runtime-version policy;
- update branches and channels;
- which binary receives each update;
- how you stop or replace a bad update;
- whether the previous binary can continue safely.
For a detailed setup, see our guide to over-the-air updates with Expo Updates.
Define rollback before rollout
A rollback plan should answer four questions:
- Which Git commit and lockfile represent the last known-good build?
- Can you rebuild and resubmit that binary?
- Can backend and data changes remain compatible with both versions?
- Can an incompatible OTA update be stopped without affecting other runtimes?
Roll out to internal testers first, then a limited production audience if your distribution setup supports it. Watch crashes, startup failures, authentication, API errors, and the product flows most closely tied to native modules.
A practical go/no-go review
Upgrade when every answer below is yes:
- Is the target SDK appropriate for production, or is this explicitly a beta test?
- Do critical native dependencies support the target React Native version?
- Are custom native changes understood and reproducible?
- Do Android and iOS release builds pass?
- Have critical product flows been tested on physical devices?
- Are OTA runtime compatibility and channels correct?
- Is the rollback path documented and tested?
- Is there time to observe a staged rollout?
If an answer is no, turn it into a bounded preparation task. That is safer than starting a broad upgrade and discovering the blocker halfway through.
How this guide stays current
The decision model, baseline, test matrix, and rollback workflow are evergreen. Release-specific information belongs in the current release watch above.
| Updated | Release context | What changed in this guide |
|---|---|---|
| September 2026 | Expo SDK 58 beta | Added iOS 27, React Native 0.88 RC, and Expo Modules 2.0 beta considerations. |
For React Native projects that are not managed with Expo, use the broader React Native upgrade guide.