Guide to Integrating the New React Native Architecture into an Android Project
Last Update On: Jun 30, 2025
The new architecture of React Native has been in place since version 0.76, and starting with version 0.80, the legacy architecture has been officially frozen. This indicates that the new architecture is now sufficiently mature. It's now the right time to transition to it.
This article will provide a detailed guide on how to integrate the new architecture of React Native into your existing Android project. It is particularly useful for those who initially developed a native Android project without using Expo or the React Native CLI, and later decided to incorporate React Native. While the React Native official documentation does cover some aspects of integration, you are likely to encounter more issues than expected in real life. This article aims to help you avoid wasting time on complex errors. So, let's get started.
gradle.properties
The first step is to update your gradle.properties to enable the new architecture:
The ndkVersion should set to 27.1.12297006 to match with the react native lib.
NOTE: The NDK version may be updated in the future. Please refer to the official blog for the latest info.
settings.gradle
Next, update your settings.gradle file to include some React Native configurations:
// apply the plugin:
plugins {
id "com.facebook.react.settings"
}
// enable auto link:
extensions.configure(com.facebook.react.ReactSettingsExtension) { ex ->
ex.autolinkLibrariesFromCommand()
}
// include the react native gradle plugin:
includeBuild('../node_modules/@react-native/gradle-plugin')
build.gradle
We need to set the AGP version to match React Native, to ensure compatibility and prevent potential issues. You can find it from node_modules/react-native/gradle/libs.versions.toml:
buildscript {
// some libs will use the ext properties, you can config it here:
ext {
ndkVersion = "27.1.12297006"
compileSdkVersion = 35
minSdkVersion = 29
targetSdkVersion = 35
}
dependencies {
classpath("com.facebook.react:react-native-gradle-plugin")
}
}
plugins {
// AGP version
id "com.android.application" version "8.8.2" apply false// other configs ......
}
// if you encounter build errors with some third-party library test tasks, you can ignore them here. However, it's generally not recommended to do so:
gradle.startParameter.excludedTaskNames.addAll(
gradle.startParameter.taskNames.findAll {
it.contains("testClasses")
}
)
The above covers the basic configuration. Now, I'll provide a detailed walkthrough on how to configure the Application and Activity.
Application
Your Application does not have to inherit from a specific class, it should implement the com.facebook.react.ReactApplication interface. Here is an example:
When in debug mode, you can set the debug_http_host to specify the host of the React Native bundle server, for example:
val sharedPref = PreferenceManager.getDefaultSharedPreferences(this)
val editor = sharedPref.edit()
editor.remove("debug_http_host")
editor.putString("debug_http_host", "192.168.1.101:8081")
editor.apply()
Activity
The Activity to show React Native elements should inherit from com.facebook.react.ReactActivity:
overridefuncreateReactActivityDelegate(): ReactActivityDelegate {
overridefungetMainComponentName(): String {
// return the registered component name in your react code
}
returnobject : DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled) {
overridefungetLaunchOptions(): Bundle? {
// return your init props for the react component
}
overridefuncreateRootView(): ReactRootView? {
val rootView = super.createRootView()
reactRootView = rootView
return rootView
}
}
}
With the configurations and code above, your project should compile and launch successfully. However, during development you might encounter some issues. Here are some common problems and their solutions.
FAQs
💡Problem: A problem occurred starting process 'command 'node'
This is because Node.js isn't included in your environment variable PATH. You have two options:
For Mac, if your node is installed in user space, such as via nvm, you can launch your Android Studio from shell open -a "Android Studio"
Also you can add node to your system' PATH
💡rebuilding 'build.ninja': subcommand failed
Try remove the dir android/app/.cxx.
💡implicit capture of 'this' with a capture default of '=' is deprecated (uiWorkletRuntime_)
Check your NDK version, should match with React Native.
After completing all the steps, you should be able to use React Native in your project smoothly. Your next major task is to stay up-to-date with the latest React Native versions by regularly checking the official blog.