New Architecture

Learn about React Native's "New Architecture" and how and why to migrate to it.

We recommend using SDK 51 or later for the best experience with the New Architecture.

The New Architecture is a name that we use to describe a complete refactoring of the internals of React Native. It is also used to solve limitations of the original React Native architecture discovered over years of usage in production at Meta and other companies.

In this guide, we'll talk about how to use the New Architecture in Expo projects today.

To learn more about the ideas and motivations behind the New Architecture, we recommend the following resources:

Why invest in migrating to the New Architecture?

The New Architecture is the future of React Native — yet, for many apps, there may not be many immediate benefits to migrating today. You may want to think of migrating to the New Architecture as an investment in the future of your app, rather than as a way to immediately improve your app.

The changes that come with the New Architecture address the technical debt of the original implementation and unlock possibilities for solving long-standing issues in React Native, such as interoperability with synchronous native APIs (for example, UITableView), and pave the way for concurrent React support.

Expo tools and the New Architecture

As of SDK 51, nearly all expo-* packages in the Expo SDK support the New Architecture (including bridgeless). Learn more about known issues.

Additionally, all modules written using the Expo Modules API support the New Architecture by default! So if you have built your own native modules using this API, no additional work is needed to use them with the New Architecture.

Third-party libraries and the New Architecture

The compatibility status of many of the most popular libraries, such as react-native-bootsplash, react-native-fbsdk-next, and react-native-pdf, are tracked in the "New Architecture support in popular libraries" spreadsheet. This does not track every library, only those that appeared in the top 400 most installed libraries on EAS Build, so if a library is not there it does not mean it is necessarily unsupported.

In React Native 0.74, there are various Interop Layers enabled by default which allows many libraries to work without any changes — however, it's not perfect and some libraries will need to be updated. The libraries that are most likely to require updates are those that ship or depend on third party native code. Learn more about library support in the New Architecture.

Learn more about known issues.

Initialize a new project with the New Architecture

The easiest way to get started with the New Architecture is to use the with-new-arch template when creating a new project:

Enable the New Architecture in an existing project

You can enable the New Architecture in your app using the expo-build-properties config plugin:

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "newArchEnabled": true
          },
          "android": {
            "newArchEnabled": true
          }
        }
      ]
    ]
  }
}

If the build succeeds, you will now be running your app with the New Architecture! Depending on the native modules you use, your app may work properly immediately.

Now you can tap around your app and test it out. For most non-trivial apps, you're likely to encounter some issues, such as missing native views that haven't been implemented for the New Architecture yet. Many of the issues you encounter are actionable and can be resolved with some configuration or code changes. We recommend reading Troubleshooting sections below for more information.

If you use Expo Router or React Navigation, your app may be impacted by a known issue with useLayoutEffect in React Native with the New Architecture. This issue is expected to be resolved in a patch release for React Native 0.74.

Troubleshooting

Meta and Expo are working towards making the New Architecture the default for all new apps and ensuring it is as easy as possible to migrate existing apps. However, the New Architecture isn't just a name — many of the internals of React Native has been re-architected and rebuilt from the ground up. As a result, you may encounter issues when enabling the New Architecture in your app. The following is some advice for troubleshooting these issues.