Developing mobile applications using framework React Native opens up enormous opportunities for engineers to create cross-platform solutions. However, the very first and often the most painful stage for a beginner is the successful launch of the assembled application on a device running Android. Errors at this stage can be caused by dozens of reasons: from missing environment variables to incorrect Gradle configuration.
In this article we will analyze in detail all the necessary steps to turn your code into a working application. We'll look at two main scenarios: using a virtual emulator for quick debugging and connecting a real physical device for performance testing. Understanding the architecture of interaction between Metro Bundler, Gradle and Android Debug Bridge (ADB) is critical for a successful start.
Before moving on to the commands, make sure that you have the latest version Node.js installed and the JDK configured. Often the problem lies not in React Native itself, but in a mismatch between the build tool versions. If you use the new CLI, the initialization process has been significantly simplified, but the requirements for the system environment remain strict.
Preparing the environment and checking dependencies
The first step before starting any project is to validate the installed development environment. Tool react-native-doctor automatically scans the system for the presence of all necessary components. It checks the path to the Android SDK, the presence of emulators, the Java version and environment variable settings ANDROID_HOME. Running this utility saves hours of manual debugging.
Make sure you have Android Studio installed with the latest platform updates. In the SDK manager, you need to check not only System Images, but also platform tools Platform-Tools and Build-Tools. Lack of a specific version of build-tools specified in the project configuration file will result in a compilation error even before the launch stage.
⚠️ Attention: Android SDK Build-Tools versions must match the version specified in the file
android/build.gradle. Version mismatches often cause the "SDK location not found" error or failures to build the APK.
It is also critical to check the variable JAVA_HOME. React Native is JDK version sensitive: older projects may require Java 11, while newer versions of the framework are fully compatible with Java 17. The wrong version of Java can cause the Gradle daemon to behave strangely.
Use the npx react-native doctor --verbose command to get a detailed report of each check, not just the overall status.
Running a project on an Android Emulator
The emulator is an ideal tool for the initial debugging of the interface and application logic without the need to connect a cable. To work with emulators in the React Native ecosystem, Android Virtual Device (AVD), supplied with the studio, or third-party solutions like Genymotion are most often used. Creating an ADV requires selecting a system image that is compatible with your processor architecture.
After creating the virtual device, you need to launch it and wait until the Android system is completely loaded. Only after the home screen appears can you initiate the launch of the application from the terminal. The command npx react-native run-android will automatically find the active emulator, build the debug version of the application and install it.
The build process may take several minutes the first time you run it because Gradle downloads a lot of dependencies. At this time, in the terminal you will see progress bars for downloading libraries. If the build freezes at stage Installing APK, check whether there is enough RAM allocated for the emulator in its settings.
To speed up the emulator, it is recommended to enable hardware acceleration in the BIOS (Intel VT-x or AMD-V). Without this option, the virtual machine will run extremely slowly, making the development process painful. It is also worth allocating at least 4 GB of RAM for the virtual device in the AVD Manager configuration.
Connecting a real Android device
Testing on real hardware is mandatory before release, since emulators cannot accurately simulate the operation of the sensor, camera, GPS and processor performance under load. To connect your phone, you will need to enable developer mode. This is usually done by clicking on the build number seven times in the "About phone" settings.
In the "For Developers" menu that appears, you need to activate the item USB debugging. After connecting the cable to the computer, a request for permission to debug from this computer will appear on the smartphone screen. Be sure to click "Allow", otherwise ADB will not see the device, and the launch command will fail.
You can check the visibility of the device with the command adb devices. If the list displays a serial number with status device, then the connection has been successfully established. If the status is unauthorized, reconnect the cable and confirm the request on the phone screen again.
⚠️ Attention: Some manufacturers (Xiaomi, Huawei) require additional account authorization or enable the "USB debugging (security settings)" item to install applications via ADB.
When you run the command npx react-native run-android with a connected phone, the assembly will occur on the computer, and installation and launch will occur on the device. Make sure you have enough free space on your phone, as debug versions of apps can take up a significant amount of memory due to debugging symbols being enabled.
☑️ Check before launching on the device
Working with Metro Bundler and launch scripts
Metro - it is a JavaScript module wrapper that is the heart of the React Native framework. It is responsible for transforming your code into a format that the device's JavaScript engine can understand and provides the Hot Reload feature. When you start the project, the Metro server automatically starts, which listens on port 8081 by default.
Sometimes the server does not start automatically or occupies a port used by another process. In this case, you can launch it manually with the command npx react-native start in a separate terminal window. This allows you to see the packer logs in real time and track code transformation errors that may not be included in the device log file.
If the application does not download code updates after changes, try clearing the Metro cache. This is done by adding a flag --reset-cache to the start command. This is especially true after updating dependencies in package.json or changing the configuration babel.
npx react-native start --reset-cacheIt is important to understand the difference between Hot Reload and Fast Refresh. Fast Refresh preserves the state of local components when updating, while Hot Reload simply reloads the entire code bundle. For complex forms with entered data, Fast Refresh is the preferred operating mode.
What to do if port 8081 is busy?
If port 8081 is occupied by another application (for example, Oracle DB or another server), Metro will not start. You can either close the conflicting application or run Metro on a different port by adding the --port 8088 flag, and then manually configure the application to connect to the new port through the debug menu.
Resolving common build errors
The process of building an Android application is complex and multi-step, so errors occur regularly. One of the most common problems is the Gradle daemon running out of memory. If the build fails with an error OutOfMemoryError, you need to increase the memory limit in the file gradle.propertiesby adding the line org.gradle.jvmargs=-Xmx2048m -XX:MaxPermSize=512m.
Another common problem is dependency versions being out of sync. If you updated React Native but did not update the corresponding versions of the libraries in android/build.gradle, the compiler will throw type mismatch errors. Always check the version compatibility matrix on the official website of the framework.
| Error type | Possible cause | Solution method |
|---|---|---|
| Command failed: gradlew | No execution rights or broken cache | Clear cache: cd android && ./gradlew clean |
| Unable to load script | Metro Bundler is not running or the port is closed | Run npx react-native start and check the firewall |
| SDK location not found | Local.properties is not configured | Create a local.properties file with the path to the SDK |
| Execution failed for task ':app:mergeDexRelease' | Duplicating classes or Multidex | Enable multidex true in build.gradle |
If you encounter an error related to mergeDexReleasethis often indicates the fact that the number of methods in the application exceeded the limit of 65k. To solve this problem, you need to enable Multidex support in the build configuration by adding the appropriate dependency and setting to defaultConfig.
90% of build errors are resolved by clearing the Gradle and Metro cache, as well as checking compliance between the JDK and Android SDK versions.
Debugging and real-time log analysis
After the successful launch of the application, the developer’s work moves into the debugging phase. The main tool for viewing Android system logs is logcat. It can be filtered by tag ReactNativeJSto see only messages from the JavaScript stream, ignoring the noise of system processes.
For convenient work with logs, it is recommended to use third-party utilities, such as Flipper (although in new versions of RN it is gradually being abandoned in favor of built-in tools) or a plugin react-native-log-android. They allow you to search through logs, highlight errors and analyze the network.
Do not forget about the debugging menu, which is called up by shaking the device (or command Cmd+M / Ctrl+M on the emulator). In this menu, there is an item Enable Remote JS Debuggingthat allows you to debug JavaScript code in the Chrome developer tools on your computer using a full-fledged debugger.
⚠️ Attention: When Remote Debugging is enabled, the application runs in a mode different from production, since JS is executed in the context of Chrome, and not in the device engine. This may hide errors associated with native modules.
The item Show Performance Monitoris also useful in the debug menu. It displays the FPS and running time of the JS stream in real time. If you see an FPS drop below 55 or red zones on the JS graph, then your code has heavy calculations that are blocking the main thread.
Why does the application crash immediately after launching on a real device?
Most often this happens because Metro Bundler is not available for the device. Make sure your phone and computer are on the same Wi-Fi network. If this does not help, try connecting your phone via USB and running the command adb reverse tcp:8081 tcp:8081to redirect the port.
How to change the port on which Metro Bundler runs?
The default port is 8081. If it is busy, start the server with the port flag: npx react-native start --port 8088. Then on the device, call the debug menu, select "Debug server host & port for device" and specify localhost:8088.
What should I do if Gradle downloads dependencies endlessly?
This may be due to a slow Internet or blocked repositories. Try clearing the Gradle cache with the command ./gradlew clean in the android folder. Also check the file android/build.gradle and make sure that the repositories google() and mavenCentral() are available.
Is it possible to run React Native without Android Studio?
Technically yes, if you already have the SDK installed and the variables configured environment manually. However, Android Studio provides the necessary emulators, a visual layout editor and a profiler, so its installation is highly recommended for comfortable development.