Integrating Expo tools into existing native apps

An overview of how you can integrate Expo tools into existing native apps ("brownfield" apps).

An existing native app that was built using another technology, whose main entry point is not a React Native view, is commonly referred to as a "brownfield" app. For example, if your app was built using UIKit and Swift, and you want to use React Native for a single screen then that is considered an "existing native app" and "brownfield".

In contrast, "greenfield" apps are created using Expo or React Native from the start or where React Native is the entry point and where all other UI branches off from.

By these definitions, if you have an "existing native app" for Android or iOS and you want to learn how to use Expo and React Native in your project (perhaps on a single screen or even a single feature), then this guide is for you.

Compatibility with existing native apps

Support for integrating Expo modules into existing native projects is in alpha. If you encounter issues, create an issue on GitHub. Not all features of the tools and services below will be available when used in the context of an existing native app.

Expo is primarily built with greenfield apps in mind, but we are increasingly investing in brownfield scenarios. Not all Expo tools and services are compatible with existing native projects yet. Additionally, comprehensive documentation for brownfield integrations may not yet available, and you may need to adapt other related documentation to your context.

Integrated vs Isolated approaches

When you integrate React Native into an existing native app, you can choose between two main approaches: integrated and isolated. The best approach for you will depend on your project's structure, your team's workflow, and your long-term goals.

Integrated approach

In the integrated approach, your React Native code lives inside your existing native project. This allows for a tight coupling between your React Native and native code.

For example, you might add your existing Android or iOS native projects to a subdirectory of the React Native project. This is a common setup for projects that started with React Native and added native code later, but it can also be used for existing native apps. If you can't use the standard android and ios subdirectories for your native projects, you can configure a custom root folder for your React Native code, with a simple monorepo setup.

Choose this approach if:

• You need to frequently iterate on both native and React Native code together.
• You have a single team that manages both native and React Native development.
• Your project structure allows for adding a React Native project directly.

Isolated approach

In the isolated approach, your React Native code is developed and maintained separately from your native project, and it can be maintained in a separate repository or in a monorepo.

With this approach, you package your React Native app as a native library (using AAR for Android and XCFramework for iOS). Then, you integrate this library into your native app just like any other native dependency.

This separation simplifies the workflow for native developers, as they don't need to set up a Node.js environment, or deal with React Native's build dependencies. They can just consume the React Native part of the app as a pre-built artifact.

Choose this approach if:

• You have separate teams for native and React Native development.
• You want to minimize the impact of adding React Native on your existing native build process.
• You prefer to treat the React Native part of your app as a self-contained module.

Next steps