New Architecture

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

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 49, nearly all expo-* packages in the Expo SDK support the New Architecture.

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.

Known incompatibilities

• expo-updates does not yet support the New Architecture. This is expected to be ready for SDK 51.
• Font.loadAsync() from expo-font is not yet compatible. This is expected to be ready by SDK 51. Use the expo-font config plugin to statically embed fonts in your app instead.
• Bridgeless mode is not yet supported. This will be worked on for SDK 51, but may not be ready.

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 the Using the interop layer and Troubleshooting sections below for more information.

Using the interop layer

Not all libraries have been migrated to support the New Architecture yet. To use these libraries in your app, you can use the interop layer as described in the "New Renderer Interop Layer" working group post.

To use the interop layer, you will need to add the following to your react-native.config.js:

module.exports = {
  project: {
    android: {
      unstable_reactLegacyComponentNames: ["NativeComponentName"]
    },
    ios: {
      unstable_reactLegacyComponentNames: ["NativeComponentName"]
    }
  },
};

Replace "NativeComponentName" with the name of the native component that you want to use. For example, the view component in @react-native-segmented-control/segmented-control is RNCSegmentedControl, so you would add "RNCSegmentedControl" to the list of unstable_reactLegacyComponentNames.

You may need to look at the library source code to determine the name, it may be helpful to look for requireNativeComponent in the library to find the name (example).

The interop layer is not perfect and may not work for all libraries. If you encounter issues, please file an issue with the library.

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 have 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.