How to upgrade to Expo SDK 54

‘Tis the season for a new Expo SDK! Expo SDK 54 is here, bringing with it React Native 0.81, Reanimated v4, and more! Android API level 36 is supported, as are iOS 26 features. Just check out the changelog...there’s a lot going on!

Each SDK undergoes extensive testing and a beta test period, where the Expo team and the community collaborate to find issues that might stand in the way of a fast and smooth upgrade for others. A lot of Expo engineers maintain our own apps and try to upgrade those as soon as the beta is out.

Nonetheless, there’s practically infinite possibilities out there. Every app is unique, and has it’s own complexities that will need to be accounted for when upgrading. Therefore, we wanted to highlight some specific key changes that may affect your upgrade to SDK 54, as well as some evergreen advice when it comes to upgrading to the latest Expo SDK.

If you prefer to consume your info via video check out this demo of an upgrade from SDK 53 to SDK 54:

React Native 0.81 now ships as an XCFramework, rather than source code that needs to be compiled into your app on every build. This could make the Fastlane step of your builds significantly faster. A small number of libraries may be referencing React Native core native components in a way that doesn’t work with this yet. If you do run into issues with this, we definitely appreciate issue submissions, and in the meantime you can switch back to compiling by source via expo-build-properties ’s ios.buildReactNativeFromSource property. We wrote a blog post about precompiled React Native that you can reference for more info.

Be sure to check out the migration guide for react-native-reanimated v4 . You can skip the babel.config.js steps, as babel-preset-expo handles them for you. If you use Nativewind, you will want to stay on Reanimated v3 for now.

Check out our advice for upgrading to New Architecture below.

Android edge-to-edge support has been around since SDK 52, but it is now enabled by default in all Android apps. Functionality that previously required react-native-edge-to-edge is now shipped inside React Native. If you continue using the react-native-edge-to-edge config plugin, you’ll need to install the package directly in your project. Or, you can use built-in properties on androidNavigationBar in your app config to achieve the same effect. If you haven’t yet tested edge-to-edge support, now is the time to make sure everything looks good on Android.

Android predictive back support can also be enabled via the android.predictiveBackGestureEnabled app config property. It is not yet enabled by default due to compatibility issues with react-native-screens.

The rewrite of expo-file-system is now the default when you import the package. If you still would like to use the old version, though, you can import expo-file-system/legacy.

Don’t adjust your terminal! You might see new runtime errors if you have unhandled exceptions thrown from async code. These were always there; they just weren’t surfaced before. This behavior change aligns better with how web browsers work.

We have written up detailed advice for troubleshooting issues found during an upgrade. This includes considerations for both before and during your upgrade, with a list of suggestions, starting with the quickest/easiest to try. We recommend reading the entire guide, but we wanted to highlight a few key items in brief here:

Most SDK releases will have a list of known breaking changes, or notable changes where you may need to tweak configuration for a scenario specific to your app. The best time to read the changelog and breaking changes is before you upgrade, so you can make those tweaks before you test, but the next best time to read it is after you upgrade, particularly if you see a compilation error or crash.

Upgrades are best taken when you don’t feel rushed to complete them. As Expo Go automatically upgraded to the latest version after the SDK release on your phone, you may have noticed that your app no longer worked in Expo Go, and felt that you needed to upgrade right away in order to keep working on features.

Development builds help reduce the temperature, giving you time and space to take on an upgrade while not interrupting ongoing feature work. A development build works a lot like Expo Go, allowing you to scan a QR code to work on your code locally without rebuilding. But it’s your own app, so it will not get upgraded when a new version of Expo Go is released.

If you still feel that you need to use Expo Go, know that you don’t necessarily have to use the latest version on the Play and App Stores. You can go to https://expo.dev/go and download previous versions for use on Android devices and iOS simulators. Unfortunately, due to App Store restrictions, this does not work on iOS devices.

Still, another reason to migrate to a development build is because Expo Go is quite limited in how it can replicate your production app, leading to issues where it works in Expo Go but not when you build your production app. Expo Go can run your JavaScript, but it cannot apply most of your app.json / app.config.js configuration, because that would require modifying native code. In short, Expo Go can’t contain nearly everything that’s unique and special about your app. Development builds can. There's plenty of headroom in the Free plan to make some development builds, or you build locally npx expo run:android or npx expo run:ios.

If you’re still on the Old Architecture, upgrade to the latest SDK, and then upgrade to New Architecture.

Expo SDK 54 will be the last SDK to support the Old Architecture, as the next version of React Native will only support the New Architecture. Therefore, if you haven’t upgraded to the New Architecture yet, now is the time! A number of the latest versions of major packages, such as react-native-reanimated v4 and @shopify/flash-list v4, only support New Architecture. 75% of SDK 53 projects built on EAS are using New Architecture, so it’s working well for most apps, and major progress has been made on the few remaining blockers for apps that have not yet migrated.

However, there’s no need to rush. Avoid upgrading both your Expo SDK and adopting New Architecture at the same time. This makes it more difficult to isolate any issues. Compared to upgrading your Expo SDK, adopting New Architecture is the bigger change, so any issues are likely related to that- but it will be hard to tell if you upgrade to both at the same time.

With a development build, you can upgrade to SDK 54 / React Native 0.81 separately. Make a development build that just upgrades to SDK 54 first (e.g., by running npx expo install expo@latest --fix and follow the release notes to address any breaking changes). Test against that and make sure everything is working with the SDK 54 upgrade. Then, turn on New Architecture and make another development build and test against that. Also note that you will want to not upgrade Reanimated from v3 to v4 until after turning on New Architecture.

You could do that immediately, or even release your app on SDK 54 / old architecture and then release later on the New Architecture. There’s no hurry to do both at once, and, if you do each of them separately, you’ll be able to pinpoint more closely if the issue is SDK 54 / React Native 0.81 or New Architecture-related. If it’s New Architecture-related, you can use our New Architecture troubleshooting guide to help.

We have a landing page of our most popular troubleshooting guides that you can browse depending on your issue. If your issue is an error when building, you’ll want to take different steps compared to a crash or performance issue. Even if you don’t fully get to the root cause, using a tool like ADB Logcat or macOS console to find a native error that the operating system reports from a crash can be very helpful as you engage in further troubleshooting or ask others for help.

We appreciate your bug reports and feedback! The best way to surface an issue is and will always be a Github issue with a minimal reproduction, where you send us a link to a Github repo based on the default project template created with npx create-expo-app , plus just enough code to reproduce the issue.

A minimal reproduction ensures that our team can see exactly what you’re seeing and gives us a way to test that our fix will work for you. Even if that seems like a lot to do, often spending 15 or 30 minutes trying to make a minimal reproduction is more effective than hours spent debugging on your actual app, where there are a lot of moving pieces and it’s more difficult to isolate issues.

We also understand the value in discussing an issue in the moment, even before you’re ready to try to reproduce it. Other developers may be experiencing the same thing and already have an answer. Discussions about issues on Discord, Reddit, Bluesky and elsewhere can result in a sort of collaborative virtual rubberducking where we find the answer together while talking through it.

We encourage you to post screenshots or videos of the issues you’re facing, or at least descriptions of what exactly you’re seeing, what platforms are affected, etc. so we can see what is broken and help the community think through how to isolate that issue and find a solution. If you have detailed feedback about the upgrade process that doesn’t fit neatly into a minimal reproduction of a single issue, we’d love to hear about it, as well. Besides social forums, we always have someone checking on the messages received from our support page.

Happy upgrading and we hope you love SDK 54!

We'll be livestreaming about SDK 54 next week. Join us!