Setting up React Native on macOS Mojave

React Native is the go-to platform if you’re versed in React and need to develop mobile applications. Instead of using a hybrid approach like several projects out there, React Native aims to develop native applications with the tooling we already use in web development.

For the most part, this approach works perfectly, specially if you’re part of small team and lack the resources to develop full native code for both Apple and Android devices, but you need to be aware of its pros and cons, as in any other decision you have to make. Fortunately, Airbnb published a very nice article covering this subject, so make sure you read it.

And after doing your own reserch, you decided that React Native will work just fine for your needs, so now what? Well, this article will show how to get your app up and running on simulators for both iOS and Android devices, as well as how to set up your project.

Installing Xcode

To use iOS simulators, you’ll need a Mac. You may be able to run your app using services like Appetize (which I haven’t tested), but given that my main development environment is macOS, this is what I’ll focus on this article.

Many web developers out there are used to installing only the command-line tools, without the Xcode IDE, so they can build extensions or even use homebrew. To use iOS simulators, you’ll need the full thing, so go to the App Store and install Xcode.

This may take a while. When is done, open Xcode and install the extra components.

Now, you can install the iOS simulators. Go to “Preferences > Components” and download as many simulators as you want. I usually install only the latest version, but that’s on you and how far back you want to support.

As far as Xcode goes, you’re done! Now, let’s set up the Android emulator.

Installing Android Studio

Android’s ecosystem is different than Apple’s. First, you can install several third party emulators, some free, some paid. If you don’t want to choose, just use Android Studio, the official IDE.

After downloading Android Studio, move the app to your /Applications folder.

Now, open the app and follow the instructions. If you don’t have an Android SDK available, you’ll see a screen like the following:

Just click on “Next” when Android Studio will install it for you.

When is done, you be presented with a welcome screen.

Go to “Configure > SDK Manager”, then head to “SDK Tools”. Click on the checkbox to install the Build Tools, which will be used by React Native command-line tools. Click in “Apply” to install it.

Now, notice the Android SDK Location available on the image above. You’ll need this value to define an environment variable on the terminal. This is where things get tricky because you may have configured your terminal different than mine, but in general lines, you’ll have to do one of the following:

• If you use bash, add the following lines to ~/.bashrc.
• If you use zsh, add the following lines to ~/.zshrc.

export JAVA_HOME="/Applications/Android Studio.app/Contents/jre/jdk/Contents/Home"
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH="$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"

Restart your terminal to reload your configuration. You can check your configurations like the following:

$ echo $JAVA_HOME
/Applications/Android Studio.app/Contents/jre/jdk/Contents/Home

$ echo $ANDROID_HOME
/Users/fnando/Library/Android/sdk

$ which java
/Applications/Android Studio.app/Contents/jre/jdk/Contents/Home/bin/java

$ which adb
/Users/fnando/Library/Android/sdk/platform-tools/adb

$ which emulator
/Users/fnando/Library/Android/sdk/emulator/emulator

If you see anything too far from the above output, make sure you added the export lines to the correct files and restarted your terminal.

Finally, you can create a virtual device. Back to the welcome screen, go to “Configure > AVD Manager”.

Click on “Create Virtual Device” and select a device definition. In this example I’m selecting Pixel 3.

When you’re done, click on “Next”. Now you have to choose which Android version you’re going to use. You can go with the latest stable version available, which right now is Android Pie. Make sure you click the “Download” link.

After downloading the system image, click on “Next” once more. You’ll be presented with the device profile you’re creating. Just click “Finish”.

Now you’re back to the list of virtual devices available on your computer and you can always create more.

To start the emulator, click the play button available under the “Actions” column. Always remember to start the emulator by clicking the play button; otherwise, you’ll see a message like No connected devices! when trying to run React Native on the Android emulator.

You can also start the emulator from the command-line. All you have to do is using the emulator command.

$ emulator -list-avds
Pixel_3_API_28

$ emulator -avd 'Pixel_3_API_28'
emulator: INFO: boot completed
emulator: INFO: boot time 34488 ms
emulator: Increasing screen off timeout, logcat buffer size to 2M.

Congrats! You’re done with configuring emulators. Now, let’s spin up a sample app and run it on both simulators.

Configuring React Native

The official documentation recommends installing react-native-cli globally, but I avoid installing global packages. We’re going to use npx to generate the app skeleton.

$ npx react-native-cli init sample
...

✨  Done in 5.90s.

  Run instructions for iOS:
    • cd /Users/fnando/Projects/sample && react-native run-ios
    - or -
    • Open ios/sample.xcodeproj in Xcode
    • Hit the Run button

  Run instructions for Android:
    • Have an Android emulator running (quickest way to get started), or a device connected.
    • cd /Users/fnando/Projects/sample && react-native run-android

Go to the projects directory with cd sample and run react-native run-ios. This will compile the app, install it on the emulator and run a separate tab with Metro, the JavaScript bundler for React Native developed by Facebook.

$ react-native run-ios
...
info + exit 0

info

info ** BUILD SUCCEEDED **


info Installing build/sample/Build/Products/Debug-iphonesimulator/sample.app
info Launching org.reactjs.native.example.sample
org.reactjs.native.example.sample: 5043

This is the tab you should keep an eye on because any errors while running your app will be outputted to it. After everything is up and running, you’ll be able to see the sample app running on the iOS simulator.

Great! What about Android simulator? Make sure you have the virtual device running (remember, from the Android Studio’s welcome screen, choose “Configure > AVD Manager”, then press the play button). You can check for running devices by executing adb devices.

$ adb devices
List of devices attached
emulator-5554 device

Now, you can run react-native run-android. This will also compile a bunch of stuff and initialize the emulator.

$ react-native run-android
...

BUILD SUCCESSFUL in 14s
26 actionable tasks: 26 executed
info Running /Users/fnando/Library/Android/sdk/platform-tools/adb -s emulator-5554 reverse tcp:8081 tcp:8081
info Starting the app on emulator-5554 (/Users/fnando/Library/Android/sdk/platform-tools/adb -s emulator-5554 shell am start -n com.sample/com.sample.MainActivity)...
Starting: Intent { cmp=com.sample/.MainActivity }

You’ll be able to see the app running on the Android simulator if everything went smoothly.

Running physical devices

At some point you’re better off testing your apps on physical devices. This can help you fix bad user experience that wouldn’t bother on simulators.

Running the app on your iPhone

To run your app on the iPhone, open ios/sample.xcodeproj on Xcode. You can use open ios/sample.xcodeproj to open this file from your terminal.

First, you have to select a developer profile. Click on the project name and go to the target you’re building (in this case, sample). Change the bundle identifier to your own domain, otherwise you won’t be able to build the project. Then click “Add Account”, enter your Apple ID and password, and select your name under the dropdown. You may also have to select your developer account for the sampleTests target.

Connect your iPhone to the computer and click the simulator selector.

Your device will be available on the top of the list.

Finally, click the “Build and Run” button, or press cmd-R. This will install and open the app on your iPhone.

Running the app on your Android

I didn’t have an Android device, but decided to buy one to test the app on the real thing. After some research, I decided to buy a Xiaomi Mi A2 which costed me around $170 on Amazon. It’s a very nice device, even for daily usage. The good thing about it is that it comes with stock Android, and not the shitty modified version that some companies ship (looking at you, Samsung).

First, make sure Developer Options is enabled. Here, things can get tricky. Different devices can be activated differently. In my case, I had to go to “Settings > About phone” and tap the Build number 7 times in order to activate the developer mode. Then go to “Settings > System > Advanced > Developer Options” and activate “USB Debugging”.

To verify that your device is ready, run adb devices on your terminal.

$ adb devices
List of devices attached
bbb5cc28  device

Now, run react-native run-android. This command will install and open the app on your Android device.

Using TypeScript

This step is optional, but if you’re planning to release your app as an open-source project you may consider using TypeScript, the typed language that compiles down to JavaScript, created by Microsoft.

For new projects, all you have to do is running the generator with --template typescript.

$ npx react-native-cli init sample --template typescript
...
✨  Done in 4.96s.

  Run instructions for iOS:
    • cd /Users/fnando/Projects/sample_ts && react-native run-ios
    - or -
    • Open ios/sample_ts.xcodeproj in Xcode
    • Hit the Run button

  Run instructions for Android:
    • Have an Android emulator running (quickest way to get started), or a device connected.
    • cd /Users/fnando/Projects/sample_ts && react-native run-android

For existing projects, you’ll need to manually configure everything that the TypeScript template provides. I won’t cover this migration process here, so make sure you read the article published on the official blog.

Wrapping up

Despite all the efforts on developing the ecosystem, React Native is still immature and you’ll find that developing apps can be challenging. But even with all these difficulties, I consider React Native the best solution for small companies/teams that need to develop native apps.

Before deep diving into React Native, ask yourself if a PWA is a viable solution. Unfortunaly, PWA comes with its own challenges, like a different mindset for installing apps and inconsistencies between Android and iOS, as well as several device limitations, but it may be a good first step towards mobiles apps when responsive web is not enough, but React Native is too much.