How do you create APK file in React Native CLI?

What is an .apk file?

An Android Package Kit [APK] is the package file format used by the Android OS for distribution and installation of mobile apps. It is similar to the .exe file you have on Windows OS, a .apk file is for android.

Debug APK

What can I use it for?

A debug .apk file will allow you to install and test your app before publishing to app stores. Mind you, this is not yet ready for publishing, and there are quite a few things you’ll need to do to before you can publish. Nevertheless, it’ll be useful for initial distribution and testing.

You’ll need to enable debugging options on your phone to run this apk.

Prerequisite:

• react-native version > 0.58

How to generate one in 3 steps?

Step 1: Go to the root of the project in the terminal and run the below command:

react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/src/main/res

Step 2: Go to android directory:

cd android

Step 3: Now in this android folder, run this command

./gradlew assembleDebug

There! you’ll find the apk file in the following path:
yourProject/android/app/build/outputs/apk/debug/app-debug.apk

Release APK

Step 1. Generate a keystore

You will need a Java generated signing key which is a keystore file used to generate a React Native executable binary for Android. You can create one using the keytool in the terminal with the following command

keytool -genkey -v -keystore your_key_name.keystore -alias your_key_alias -keyalg RSA -keysize 2048 -validity 10000

Once you run the keytool utility, you’ll be prompted to type in a password. *Make sure you remember the password

You can change your_key_name with any name you want, as well as your_key_alias. This key uses key-size 2048, instead of default 1024 for security reason.

Step 2. Adding Keystore to your project

Firstly, you need to copy the file your_key_name.keystore and paste it under the android/app directory in your React Native project folder.

On Terminal:

mv my-release-key.keystore /android/app

You need to open your android\app\build.gradle file and add the keystore configuration. There are two ways of configuring the project with keystore. First, the common and unsecured way:

build.gradle - keystore Configuration

This is not a good security practice since you store the password in plain text. Instead of storing your keystore password in .gradle file, you can stipulate the build process to prompt you for these passwords if you are building from the command line.

To prompt for password with the Gradle build file, change the above config as:

Release Bundle Configuration Command

Step 3. Release APK Generation

Place your terminal directory to android using:
cd android

For Windows,
gradlew assembleRelease

For Linux and Mac OSX:
./gradlew assembleRelease

As a result, the APK creation process is done. You can find the generated APK at android/app/build/outputs/apk/app-release.apk. This is the actual app, which you can send to your phone or upload to the Google Play Store. Congratulations, you’ve just generated a React Native Release Build APK for Android.

How to generate android APK files for android mobile apps in React Native CLI

Figure 01: Artwork by Author [Image source: //www.canva.com/, //unsplash.com/]

In android mobile application development, it is an essential responsibility of the developer to test the app on a real device. For apps developed using React-Native-CLI, one of the best ways to test the app on a real device is to generate the APK file, install and run it on any android mobile device. Due to various errors and bugs, sometimes APK generation can be quite hectic. This article is an A-Z guide that will help anybody who is new to mobile app development with React-Native-CLI, to build an APK file quickly while easily resolving the possible errors.

However, before following the procedure in this article make sure that your project is run properly without any errors or bugs.

For ease of reference I have presented the content under 04 subsections as follows:

1. Generate a Keystore
2. Adding Keystore to the Project and Building App Bundle
3. Release APK Generation
4. General Solutions for Possible Errors
5. Summary
6. References

1. Generate a Keystore

The first step is to generate a Keystore file which is a Java generated signing key. It will be used to create the ReactNative executable binary for Android. To generate Keystore, open the PowerShell terminal in your project [VS Code] and run the following command. Replace the fields ‘key_name’ and ‘key-alias’ with names as your wish.

keytool -genkey -v -keystore key_name.keystore -alias key_alias -keyalg RSA -keysize 2048 -validity 10000

Then you will be asked to provide a password for the Keystore and fill a few fields before generating the Keystore [Figure 2]. [Remember the password field is hidden. So you might not be able to view what you type. And save your ‘key-name’, ‘key-alias’, and ‘password’ because later you will need them again.]

Figure 02: Screenshot of the VS Code PowerShell

You can add some dummy values for the above field.

Figure 03: Screenshot of the VS Code PowerShell

You can add another password for ‘test-key-alias’ or just hit enter to generate the Keystore file [Figure 03]. The Keystore file will be created in the root directory but you have to copy and paste it in the path: ‘android/app/’ as shown in figure 04.

Figure 04: Screenshot of the project directories

2. Adding Keystore to the Project and Building App Bundle

Next, you must configure the project with Keystore. For that open the ‘build.gradle’ file in the path: ‘/android/app’ [the same path you save the Keystore earlier]. Add the ‘release’ to ‘signingConfig’ block and modify the ‘release’ in ‘buildTypes’ block in the build.gradle as follows.

Replace the Keystore name, alias and passwords with yours [Remember I told you to save them in section 01 🙂]. You can see that the above method is easy to configure but your password is directly put into the code base which is not an acceptable practice. To avoid that you can use the following alternative method to configure ‘build.gradle’ fields as follows. It is more secure and later when running the command to build the bundle you will be prompted to enter the password. You can either use the above method or the following way to configure the Keystore to the project.

Note: Always place the ‘signingConfigs’ before the ‘buildType’ blocks to avoid possible errors.

Before building the bundle you have to check whether there is a directory called ‘assets’ in the path ‘android/app/src/main’. If there is no assets folder then create a folder named ‘assets’ in the above path [Figure 5]. This is the directory where the app bundle is saved.

To create the app bundle, run the following command on the same terminal.

Note: The command is a single line of code. Therefore, you can copy the following and paste in notepad, then remove any line breaks before pasting directly on the terminal.

react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/src/main/res/

Note: The file name ‘index.js’ in the above command is the entry file in the project. In your project, if you have a different entry file [for example: ‘index.android.js’] then replace it with the relevant file name.

If the build is successful you can see the newly created bundle file with the name ‘index.android.bundle’ in the assets directory [Figure 05].

Figure 05: Screenshot of the project directories

3. Release APK Generation

This is the last line of barriers you are remaining to pass to generate the APK file. Follow the steps given below carefully to avoid any possible mistakes and errors:

First, go to the android directory in your project. You can manually go to the directory and open the terminal or run the following command [if you are in the root directory].

cd android

Next, run the following command to generate the APK file.

./gradlew assembleRelease

In some places, I observe that it is recommended to use ‘gradlew assembleRelease’ for Windows but the above command works in all 03 platforms Windows, Mac and Linux. In case it throws an error in Windows as below [Figure 06], you can always use the bash terminal instead of PowerShell or Command Prompt.

Figure 06: Screenshot of the error thrown in Windows PowerShell terminal in VS Code

If the above command ran successfully, good job 👏, then it will create the APK file with the name ‘app-release.apk’ in the path: ‘android/app/build/outputs/apk/release’ [Figure 07]. You can copy and install the generated APK file to your android mobile phone and run it.

Figure 07: Path of the generated APK file

But, unfortunately, it is not always the case that the generation of APK can be done in a single shot. There may be at least one ‘Build Failure’ you may encounter while trying to run the above commands. Next, we will discuss a few solutions that can be done to avoid such errors.

4. General Solutions for Possible Errors

If you face any error/issue when creating the app bundle in steps 1 and 2, most probably due to using the wrong terminal or typos in the command you run. Therefore again read the instructions carefully, especially the ‘Notes’, to avoid such minor mistakes.

Error 01: app:validateSigningRelease FAILED

The following error is due to missing keystore file. For sure you may have put the keystore in a different location or file name is differ from that of configured in ‘build.gradle’. It is possible to throw this error even closer to build the apk.

Task :app:validateSigningRelease FAILED
…
BUILD FAILED

Error 02 & 03: app:mergeReleaseResources & app:mergeReleaseResources

The majority of the build errors occur during the final step: releasing the APK. While building the APK, execution failure for some tasks can occur resulting in entire APK build failures.

Execution failed for task ‘:app:processReleaseResources’.
...
BUILD FAILED

or

Execution failed for task ‘:app:mergeReleaseResources’.
… 
BUILD FAILED

There are two options to resolve such errors:

1. Clean ‘drawable’ and ‘raw’ directories.

You can run the following commands to delete them:

rm -rf android/app/src/main/res/drawable-* 
rm -rf android/app/src/main/raw

Or to manually delete them, go to the directories ‘drawable’ and ‘raw’ directories in the paths: ‘android\app\src\main\res\drawable’ and ‘android\app\src\main\res\raw’ respectively. And delete all the content in each directory [Figure 08].

Figure 08: Screenshot of the ‘drawable’ and ‘raw’ directories

2. Re-configure the bundle-release

You can re-configure the entry file name, the path of the bundle-output created and the APK assets destinations by running the following command. Open the bash terminal in the root directory [project folder] and run the following command.

react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/build/intermediates/res/merged/release/

After that again move to the android directory and run the ‘./gredlew assembleRelease’ command again. It will successfully generate the APK file.

5. Summary

The first and foremost step before generating an APK file for a ReactNative project is to make sure that the code base is error-free and working as expected in the Android Emulator. Other than that, the basic steps of generating an APK file for a ReactNative project involves 03 major steps: generating the Keystore file, configuring the Keystore with the project and building the app bundle, and finally releasing the APK generation. There might be some errors associated with the process but they can be easily solved with a few modifications to the project and some additional commands.

6. References

How can I create my own APK?

How is APK file created?

How generate APK in React Native iOS?

How create Android app With React Native?