React Native0.27

Quick Start

Tutorials

Sample Applications

Community Resources

Guides

Guides (iOS)

Guides (Android)

components

apis

Polyfills

Getting Started #

Edit on GitHub
Platform: iOS Android OS: Mac Linux Windows

Unsupported #

Unfortunately, Apple only lets you develop for iOS on a Mac machine. Please check out the Android instructions instead.

Installation #

Required Prerequisites #

Homebrew #

Homebrew, in order to install the required NodeJS, in addition to some recommended installs.

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Node #

Use Homebrew to install Node.js.

NodeJS 4.0 or greater is required for React Native. The default Homebrew package for Node is currently 6.0, so that is not an issue.

brew install node

React Native Command Line Tools #

The React Native command line tools allow you to easily create and initialize projects, etc.

npm install -g react-native-cli

If you see the error, EACCES: permission denied, please run the command: sudo npm install -g react-native-cli.

Xcode #

Xcode 7.0 or higher. Open the App Store or go to https://developer.apple.com/xcode/downloads/. This will also install git as well.

Android Studio #

Android Studio 2.0 or higher.

Android Studio requires the Java Development Kit [JDK] 1.8 or higher. You can type javac -version to see what version you have, if any. If you do not meet the JDK requirement, you can download it.

Android Studio will provide you the Android SDK and emulator required to run and test your React Native apps.

Unless otherwise mentioned, keep all the setup defaults intact. For example, the Android Support Repository is installed automatically with Android Studio, and we need that for React Native.

You will need to customize your installation:

  • Choose a Custom installation

custom installation

  • Choose both Performance and Android Virtual Device

additional installs

  • After installation, choose Configure | SDK Manager from the Android Studio welcome window.

configure sdk

  • In the SDK Platforms window, choose Show Package Details and under Android 6.0 (Marshmallow), make sure that Google APIs, Intel x86 Atom System Image, Intel x86 Atom_64 System Image, and Google APIs Intel x86 Atom_64 System Image are checked.

platforms

  • In the SDK Tools window, choose Show Package Details and under Android SDK Build Tools, make sure that Android SDK Build-Tools 23.0.1 is selected.

build tools

ANDROID_HOME Environment Variable #

Ensure the ANDROID_HOME environment variable points to your existing Android SDK. To do that, add this to your ~/.bashrc, ~/.bash_profile (or whatever your shell uses) and re-open your terminal:

# If you installed the SDK without Android Studio, then it may be something like: # /usr/local/opt/android-sdk export ANDROID_HOME=~/Library/Android/sdk

Highly Recommended Installs #

Watchman #

Watchman is a tool by Facebook for watching changes in the filesystem. It is recommended you install it for better performance.

brew install watchman

Flow #

Flow, for static typechecking of your React Native code (when using Flow as part of your codebase).

brew install flow

Add Android Tools Directory to your PATH #

You can add the Android tools directory on your PATH in case you need to run any of the Android tools from the command line such as android avd. In your ~/.bash or ~/.bash_profile:

# Your exact string here may be different. PATH="~/Library/Android/sdk/tools:~/Library/Android/sdk/platform-tools:${PATH}" export PATH

Gradle Daemon #

Enable Gradle Daemon which greatly improves incremental build times for changes in java code.

Other Optional Installs #

Git #

Git version control. If you have installed Xcode, Git is already installed, otherwise run the following:

brew install git

Nuclide #

Nuclide is an IDE from Facebook providing a first-class development environment for writing, running and debugging React Native applications.

Get started with Nuclide here.

Genymotion #

Genymotion is an alternative to the stock Google emulator that comes with Android Studio. However, it's only free for personal use. If you want to use the stock Google emulator, see below.

  1. Download and install Genymotion.
  2. Open Genymotion. It might ask you to install VirtualBox unless you already have it.
  3. Create a new emulator and start it.
  4. To bring up the developer menu press ⌘+M

Troubleshooting #

Virtual Device Not Created When Installing Android Studio #

There is a known bug on some versions of Android Studio where a virtual device will not be created, even though you selected it in the installation sequence. You may see this at the end of the installation:

Creating Android virtual device Unable to create a virtual device: Unable to create Android virtual device

If you see this, run android avd and create the virtual device manually.

avd

Then select the new device in the AVD Manager window and click Start....

Shell Command Unresponsive Exception #

If you encounter:

Execution failed for task ':app:installDebug'. com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException

try downgrading your Gradle version to 1.2.3 in <project-name>/android/build.gradle (https://github.com/facebook/react-native/issues/2720)

Installation #

Required Prerequisites #

Chocolatey #

Chocolatey is a package manager for Windows similar to yum and apt-get. See the website for updated instructions, but installing from the Terminal should be something like:

@powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin

Normally when you run Chocolatey to install a package, you should run your Terminal as Administrator.

Python 2 #

Fire up the Termimal and use Chocolatey to install Python 2.

Python 3 will currently not work when initializing a React Native project.

choco install python2

Node #

Fire up the Terminal and type the following commands to install NodeJS from the NodeSource repository:

sudo apt-get install -y build-essential curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash - sudo apt-get install -y nodejs sudo ln -s /usr/bin/nodejs /usr/bin/node

Fire up the Termimal and use Chocolatey to install NodeJS.

choco install nodejs.install

React Native Command Line Tools #

The React Native command line tools allow you to easily create and initialize projects, etc.

npm install -g react-native-cli

If you see the error, EACCES: permission denied, please run the command: sudo npm install -g react-native-cli.

Android Studio #

Android Studio 2.0 or higher.

Android Studio requires the Java Development Kit [JDK] 1.8 or higher. You can type javac -version to see what version you have, if any. If you do not meet the JDK requirement, you can download it, or use a pacakage manager to install it (e.g. choco install jdk8, apt-get install default-jdk).

Android Studio will provide you the Android SDK and emulator required to run and test your React Native apps.

Unless otherwise mentioned, keep all the setup defaults intact. For example, the Android Support Repository is installed automatically with Android Studio, and we need that for React Native.

You will need to customize your installation:

  • Choose a Custom installation

custom installation

  • Choose Android Virtual Device

additional installs

  • Make sure all components are checked for the install, particularly the Android SDK and Android Device Emulator.

  • After the initial install, choose a Custom installation.

custom installation

  • Verify installed components, particularly the emulator and the HAXM accelerator. They should be checked.

verify installs

  • After installation, choose Configure | SDK Manager from the Android Studio welcome window.

configure sdk

configure sdk

  • In the SDK Platforms window, choose Show Package Details and under Android 6.0 (Marshmallow), make sure that Google APIs, Intel x86 Atom System Image, Intel x86 Atom_64 System Image, and Google APIs Intel x86 Atom_64 System Image are checked.

platforms

platforms

  • In the SDK Tools window, choose Show Package Details and under Android SDK Build Tools, make sure that Android SDK Build-Tools 23.0.1 is selected.

build tools

build tools

ANDROID_HOME Environment Variable #

Ensure the ANDROID_HOME environment variable points to your existing Android SDK.

To do that, add this to your ~/.bashrc, ~/.bash_profile (or whatever your shell uses) and re-open your terminal:

# If you installed the SDK without Android Studio, then it may be something like: # /usr/local/opt/android-sdk; Generally with Android Studio, the SDK is installed here... export ANDROID_HOME=~/Android/Sdk

You need to restart the Terminal to apply the new environment variables (or source the relevant bash file).

Go to Control Panel -> System and Security -> System -> Change settings -> Advanced System Settings -> Environment variables -> New

Your path to the SDK will vary to the one shown below.

env variable

You need to restart the Command Prompt (Windows) to apply the new environment variables.

Highly Recommended Installs #

Watchman #

Watchman is a tool by Facebook for watching changes in the filesystem. It is recommended you install it for better performance.

This also helps avoid a node file-watching bug.

Type the following into your terminal to compile watchman from source and install it:

git clone https://github.com/facebook/watchman.git cd watchman git checkout v4.5.0 # the latest stable release ./autogen.sh ./configure make sudo make install

Flow #

Flow, for static typechecking of your React Native code (when using Flow as part of your codebase).

Type the following in the terminal:

npm install -g flow-bin

Gradle Daemon #

Enable Gradle Daemon which greatly improves incremental build times for changes in java code.

touch ~/.gradle/gradle.properties && echo "org.gradle.daemon=true" >> ~/.gradle/gradle.properties
(if not exist "%USERPROFILE%/.gradle" mkdir "%USERPROFILE%/.gradle") && (echo org.gradle.daemon=true >> "%USERPROFILE%/.gradle/gradle.properties")

Android Emulator Accelerator #

You may have seen the following screen when installing Android Studio.

accelerator

If your system supports KVM, you should install the Intel Android Emulator Accelerator.

Add Android Tools Directory to your PATH #

You can add the Android tools directory on your PATH in case you need to run any of the Android tools from the command line such as android avd.

In your ~/.bashrc or ~/.bash_profile:

# Your exact string here may be different. PATH="~/Android/Sdk/tools:~/Android/Sdk/platform-tools:${PATH}" export PATH

Go to Control Panel -> System and Security -> System -> Change settings -> Advanced System Settings -> Environment variables -> highlight PATH -> Edit...

The location of your Android tools directories will vary.

env variable

Other Optional Installs #

Git #

Install Git via your package manager (e.g., sudo apt-get install git-all).

You can use Chocolatey to install git via:

choco install git

Alternatively, you can download and install Git for Windows. During the setup process, choose "Run Git from Windows Command Prompt", which will add git to your PATH environment variable.

Nuclide #

[Nuclide] is an IDE from Facebook providing a first-class development environment for writing, running and debugging React Native applications.

Get started with Nuclide here.

Genymotion #

Genymotion is an alternative to the stock Google emulator that comes with Android Studio. However, it's only free for personal use. If you want to use the stock Google emulator, see below.

  1. Download and install Genymotion.
  2. Open Genymotion. It might ask you to install VirtualBox unless you already have it.
  3. Create a new emulator and start it.
  4. To bring up the developer menu press ⌘+M

Visual Studio Emulator for Android #

The Visual Studio Emulator for Android is a free android emulator that is hardware accelerated via Hyper-V. It is an alternative to the stock Google emulator that comes with Android Studio. It doesn't require you to install Visual Studio at all.

To use it with react-native you just have to add a key and value to your registry:

  1. Open the Run Command (Windows+R)
  2. Enter regedit.exe
  3. In the Registry Editor navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Android SDK Tools
  4. Right Click on Android SDK Tools and choose New > String Value
  5. Set the name to Path
  6. Double Click the new Path Key and set the value to C:\Program Files\Android\sdk. The path value might be different on your machine.

You will also need to run the command adb reverse tcp:8081 tcp:8081 with this emulator.

Then restart the emulator and when it runs you can just do react-native run-android as usual.

Troubleshooting #

Unable to run mksdcard SDK Tool #

When installing Android Studio, if you get the error:

Unable to run mksdcard SDK tool

then install the standard C++ library:

sudo apt-get install lib32stdc++6

Virtual Device Not Created When Installing Android Studio #

There is a known bug on some versions of Android Studio where a virtual device will not be created, even though you selected it in the installation sequence. You may see this at the end of the installation:

Creating Android virtual device Unable to create a virtual device: Unable to create Android virtual device

no virtual device

If you see this, run android avd and create the virtual device manually.

avd

avd

Then select the new device in the AVD Manager window and click Start....

Shell Command Unresponsive Exception #

In case you encounter

Execution failed for task ':app:installDebug'. com.android.builder.testing.api.DeviceException: com.android.ddmlib.ShellCommandUnresponsiveException

try downgrading your Gradle version to 1.2.3 in <project-name>/android/build.gradle (https://github.com/facebook/react-native/issues/2720)

Testing Installation #

react-native init AwesomeProject cd AwesomeProject react-native run-ios

You can also open the AwesomeProject folder in Nuclide and run the application, or open ios/AwesomeProject.xcodeproj and hit the Run button in Xcode.

react-native init AwesomeProject cd AwesomeProject react-native run-android

You can also open the AwesomeProject folder in Nuclide and run the application.

Modifying Project #

Now that you successfully started the project, let's modify it:

  • Open index.ios.js in your text editor of choice (e.g. Nuclide) and edit some lines.
  • Hit ⌘-R in your iOS simulator to reload the app and see your change!
  • Open index.android.js in your text editor of choice (e.g. Nuclide) and edit some lines.
  • Press the R key twice OR open the menu (F2 by default, or ⌘-M in Genymotion) and select Reload JS to see your change!
  • Run adb logcat *:S ReactNative:V ReactNativeJS:V in a terminal to see your app's logs

That's It #

Congratulations! You've successfully run and modified your first React Native app.

Testing Installation #

react-native init AwesomeProject cd AwesomeProject react-native run-android

Troubleshooting Run #

A common issue is that the packager is not started automatically when you run react-native run-android. You can start it manually using:

cd AwesomeProject react-native start

Or if you hit a ERROR Watcher took too long to load on Windows, try increasing the timeout in this file (under your node_modules/react-native/).

Modifying Project #

Now that you successfully started the project, let's modify it:

  • Open index.android.js in your text editor of choice (e.g. Nuclide) and edit some lines.
  • Press the R key twice OR open the menu (F2 by default, or ctrl-M in the emulator) and select Reload JS to see your change!
  • Run adb logcat *:S ReactNative:V ReactNativeJS:V in a terminal to see your app's logs

That's It #

Congratulations! You've successfully run and modified your first React Native app.

Common Followups #

Common Followups #

Next →

We are planning improvements to the React Native documentation. Your responses to this short survey will go a long way in helping us provide valuable content. Thank you!

Take Survey