React Native's New Architecture

Edit this page

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


We recommend using the latest Expo version 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.

New Architecture is here

A blog post from the React Native team at Meta that gives an overview of the features of the New Architecture and the motivations behind building it.

Why migrate 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.

That said, new React and React Native features are coming to the New Architecture only. For example, the New Architecture includes full support for Suspense and new styling capabilities are not implemented in the legacy architecture. Libraries such as @shopify/flash-list and react-native-reanimated will be shipping new major versions that take full advantage of new features to deliver better performance than was possible before, and will drop support for the legacy architecture.

The legacy architecture will not be around forever — it's possible that the legacy architecture will be removed from React Native in a late 2025 release. When it is removed, you will not be able to upgrade React Native or the Expo SDK without migrating to the New Architecture.

Expo tools and the New Architecture

As of SDK 53, 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.

As of April 2025, approximately 75% of SDK 52+ projects built with EAS Build use the New Architecture.

Third-party libraries and the New Architecture

The compatibility status of many of the most popular libraries is tracked on React Native Directory (learn more about known issues in third-party libraries). We've built tooling into Expo Doctor to integrate with React Native Directory to help you validate your dependencies, so you can quickly learn which libraries are unmaintained and which incompatible or untested with the New Architecture.

Validate your dependencies with React Native Directory

Run npx expo-doctor to check your dependencies against the data in React Native Directory.

Terminal
npx expo-doctor@latest

You can configure the React Native Directory check in your package.json file. For example, if you would like to exclude a package from validation:

package.json
{
  "expo": {
    "doctor": {
      "reactNativeDirectoryCheck": {
        "exclude": ["react-redux"]
      }
    }
  }
}
See all available options
  • enabled: If true, the check will warn if any packages are missing from React Native Directory. Set this to false to disable this behavior. On SDK 52 and above, this is set to true by default, otherwise it is false by default. You can also override this setting with the EXPO_DOCTOR_ENABLE_DIRECTORY_CHECK environment variable (0 is false, 1 is true).
  • exclude: List any packages you want to exclude from the check. Supports exact package names and regex patterns. For example, ["exact-package", "/or-a-regex-.*/"].
  • listUnknownPackages: By default, the check will warn if any packages are missing from React Native Directory. Set this to false to disable this behavior.

Initialize a new project with the New Architecture

As of SDK 52, all new projects will be initialized with the New Architecture enabled by default.

Terminal
npx create-expo-app@latest

Enable the New Architecture in an existing project

The New Architecture is enabled by default in SDK 53 and above. If you have explicitly disabled it, remove that configuration to enable it.

We recommend upgrading to SDK 53 in order to ensure that your app can take advantage of all of the latest New Architecture related fixes and improvements with libraries and React Native itself. If you want to try it on SDK 52 first, follow the instructions below.

1

To enable it on both Android and iOS, use the newArchEnabled at the root of the expo object in your app config. You can selectively enable it for a single platform by setting, for example, "android": { "newArchEnabled": true }.

app.json
{
  "expo": {
    "newArchEnabled": true
  }
}

2

Create a new build:

Terminal
# Run a clean prebuild and start a local build, if you like
npx expo prebuild --clean && npx expo run:android
# Run a build with EAS if you prefer
eas build -p android
Terminal
# Run a clean prebuild and start a local build, if you like
npx expo prebuild --clean && npx expo run:ios
# Run a build with EAS if you prefer
eas build -p ios

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.

We recommend upgrading to at least SDK 52, preferably SDK 53. It's possible to enable the New Architecture in SDK 51, but you are likely to encounter a variety of issues that have been resolved in more recent releases. To enable it, you need to install the expo-build-properties plugin and set newArchEnabled on target platforms.

Are you enabling the New Architecture in a bare React Native app?

If you are using Expo SDK 53 or higher, it will be enabled by default. The following instructions apply to older projects.

  • Android: Set newArchEnabled=true in the gradle.properties file.
  • iOS: If your project has a Podfile.properties.json file (which is created by npx create-expo-app or npx expo prebuild), you can enable the New Architecture by setting the newArchEnabled property to "true" in the Podfile.properties.json file. Otherwise, refer to the "Enable the New Architecture for Apps" section of the React Native New Architecture working group.

Disable the New Architecture in an existing project

: Expo Go only supports the New Architecture.

If you want to opt out of using the New Architecture, set the newArchEnabled property to false in app config and create a development build.

app.json
{
  "expo": {
    "newArchEnabled": false
  }
}
Are you disabling the New Architecture in a bare React Native app?
  • Android: Set newArchEnabled=false in the gradle.properties file.
  • iOS: If your project has a Podfile.properties.json file (which is created by npx create-expo-app or npx expo prebuild), you can enable the New Architecture by setting the newArchEnabled property to "false" in the Podfile.properties.json file. Otherwise, refer to the "Enable the New Architecture for Apps" section of the React Native New Architecture working group.

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.

Can I still try the New Architecture even if some of the libraries I use aren't supported?

You may be able to try the New Architecture in your app even if some of the libraries you use aren't supported, but it will require temporarily removing those libraries. Create a new branch in your repository and remove any of the libraries that aren't compatible until your app is running. This will give you a good idea of what libraries still need work before you can fully migrate to the New Architecture. We recommend creating issues or pull requests on those libraries' repositories to help them become compatible with the New Architecture. Alternatively, you could switch to other libraries that are compatible with the New Architecture. Refer to React Native Directory to find compatible libraries.

Known issues in React Native
Known issues in Expo libraries

There are no known issues specific to the New Architecture in Expo libraries.

Known issues in third-party libraries

Since React Native 0.74, there are various Interop Layers enabled by default. This allows many libraries built for the old architecture to work on the New Architecture without any changes. However, the interop is 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.

Refer to React Native Directory a more complete list of libraries and their compatibility with the New Architecture. The following libraries were found to be popular among Expo apps and are known to be incompatible:

The following are known issues with libraries that are popular among Expo apps.

  • react-native-maps: Initial support for the New Architecture is available in version 1.21.0, which is still stabilizing. We encourage your to test it in your app, report issues that you find, and follow along with the discussion on GitHub. We are also investigating another approach that may provider a smoother migration path, by leaning on the interop layer rather than rewriting the module. It’s worth mentioning that if your app can force a minimum version of iOS 18, or does not need to support maps on iOS, then you can consider using expo-maps instead.
  • @stripe/react-native does not yet support the New Architecture. Follow along with progress.
  • @react-native-community/masked-view: Use @react-native-masked-view/masked-view instead.
  • @react-native-community/clipboard: Use @react-native-clipboard/clipboard instead.
  • rn-fetch-blob: Use react-native-blob-util instead.
  • react-native-fs: Use expo-file-system or a fork of react-native-fs instead.
  • react-native-geolocation-service: Use expo-location instead.
  • react-native-datepicker: Use react-native-date-picker or @react-native-community/datetimepicker instead.
My build failed after enabling the New Architecture

This isn't entirely surprising! Not all libraries are compatible yet, and in some cases compatibility was only recently added and so you will want to ensure you update your libraries to their latest versions. Read the logs to determine which library is incompatible. Also, run npx expo-doctor@latest to check your dependencies against the data in React Native Directory.

When you are using the latest version of a library and it is not compatible, report any issues you encounter to the respective GitHub repository. Create a minimal reproducible example and report the issue to the library author. If you believe the issue originates in React Native itself, rather than a library, report it to the React Native team (again, with a minimal reproducible example).