diff --git a/docs/Debugging.md b/docs/Debugging.md index e9378c63ca8d5d..a3143a77811157 100644 --- a/docs/Debugging.md +++ b/docs/Debugging.md @@ -7,59 +7,73 @@ permalink: docs/debugging.html next: testing --- -## Debugging React Native Apps -To access the in-app developer menu: +## In-app Errors and Warnings -1. On iOS shake the device or press `control + ⌘ + z` in the simulator. -2. On Android shake the device or press hardware menu button (available on older devices and in most of the emulators, e.g. in [genymotion](https://www.genymotion.com) you can press `⌘ + m` or `F2` to simulate hardware menu button click). You can also install [Frappé](http://getfrappe.com), a tool for OS X, which allows you to emulate shaking of devices remotely. You can use `⌘ + Shift + R` as a shortcut to trigger a **shake** from Frappé. +Errors and warnings are displayed inside your app in development builds. -> Hint +### Errors -> To disable the developer menu for production builds: -> -> 1. For iOS open your project in Xcode and select `Product` → `Scheme` → `Edit Scheme...` (or press `⌘ + <`). Next, select `Run` from the menu on the left and change the Build Configuration to `Release`. -> 2. For Android, by default, developer menu will be disabled in release builds done by gradle (e.g with gradle `assembleRelease` task). Although this behavior can be customized by passing proper value to `ReactInstanceManager#setUseDeveloperSupport`. +In-app errors are displayed in a full screen alert with a red background inside your app. This screen is known as a RedBox. You can use `console.error()` to manually trigger one. -### Android logging -Run `adb logcat *:S ReactNative:V ReactNativeJS:V` in a terminal to see your Android app's logs. +### Warnings -### Reload -Selecting `Reload` (or pressing `⌘ + r` in the iOS simulator) will reload the JavaScript that powers your application. If you have added new resources (such as an image to `Images.xcassets` on iOS or to `res/drawable` folder on Android) or modified any native code (Objective-C/Swift code on iOS or Java/C++ code on Android), you will need to re-build the app for the changes to take effect. +Warnings will be displayed on screen with a yellow background. These alerts are known as YellowBoxes. Click on the alerts to show more information or to dismiss them. -### YellowBox/RedBox -Using `console.warn` will display an on-screen log on a yellow background. Click on this warning to show more information about it full screen and/or dismiss the warning. +As with a RedBox, you can use `console.warn()` to trigger a YellowBox. -You can use `console.error` to display a full screen error on a red background. +YellowBoxes can be disabled during development by using `console.disableYellowBox = true;`. Specific warnings can be ignored programmatically by setting an array of prefixes that should be ignored: `console.ignoredYellowBox = ['Warning: ...'];` -By default, the warning box is enabled in `__DEV__`. Set the following flag to disable it: -```js -console.disableYellowBox = true; -console.warn('YellowBox is disabled.'); -``` -Specific warnings can be ignored programmatically by setting the array: -```js -console.ignoredYellowBox = ['Warning: ...']; -``` -Strings in `console.ignoredYellowBox` can be a prefix of the warning that should be ignored. +> RedBoxes and YellowBoxes are automatically disabled in release (production) builds. -### Chrome Developer Tools -To debug the JavaScript code in Chrome, select `Debug JS Remotely` from the developer menu. This will open a new tab at [http://localhost:8081/debugger-ui](http://localhost:8081/debugger-ui). +## Accessing the In-App Developer Menu -In Chrome, press `⌘ + option + i` or select `View` → `Developer` → `Developer Tools` to toggle the developer tools console. Enable [Pause On Caught Exceptions](http://stackoverflow.com/questions/2233339/javascript-is-there-a-way-to-get-chrome-to-break-on-all-errors/17324511#17324511) for a better debugging experience. +You can access the developer menu by shaking your device. You can also use the `Command⌘ + D` keyboard shortcut when your app is running in the iPhone Simulator, or `Command⌘ + M` when running in an Android emulator. -To debug on a real device: +> The Developer Menu is disabled in release (production) builds. -1. On iOS - open the file [`RCTWebSocketExecutor.m`](https://github.com/facebook/react-native/blob/master/Libraries/WebSocket/RCTWebSocketExecutor.m) and change `localhost` to the IP address of your computer. Shake the device to open the development menu with the option to start debugging. -2. On Android, if you're running Android 5.0+ device connected via USB you can use `adb` command line tool to setup port forwarding from the device to your computer. For that run: `adb reverse tcp:8081 tcp:8081` (see [this link](http://developer.android.com/tools/help/adb.html) for help on `adb` command). Alternatively, you can [open dev menu](#debugging-react-native-apps) on the device and select `Dev Settings`, then update `Debug server host for device` setting to the IP address of your computer. +## Reloading JavaScript -### Custom JavaScript debugger -To use a custom JavaScript debugger define the `REACT_DEBUGGER` environment variable to a command that will start your custom debugger. That variable will be read from the Packager process. If that environment variable is set, selecting `Debug JS Remotely` from the developer menu will execute that command instead of opening Chrome. The exact command to be executed is the contents of the REACT_DEBUGGER environment variable followed by the space separated paths of all project roots (e.g. If you set REACT_DEBUGGER="node /path/to/launchDebugger.js --port 2345 --type ReactNative" then the command "node /path/to/launchDebugger.js --port 2345 --type ReactNative /path/to/reactNative/app" will end up being executed). Custom debugger commands executed this way should be short-lived processes, and they shouldn't produce more than 200 kilobytes of output. +Selecting `Reload` from the Developer Menu will reload the JavaScript that powers your application. You can also press `Command⌘ + R` in the iOS Simulator, or press `R` twice on Android emulators. -### Live Reload -This option allows for your JS changes to trigger automatic reload on the connected device/emulator. To enable this option: +You will need to rebuild your app for changes to take effect in certain situations: -1. On iOS, select `Enable Live Reload` via the developer menu to have the application automatically reload when changes are made to the JavaScript. -2. On Android, [launch dev menu](#debugging-react-native-apps), go to `Dev Settings` and select `Auto reload on JS change` option +* You have added new resources to your native app's bundle, such as an image in `Images.xcassets` on iOS or in `res/drawable` folder on Android. +* You have modified native code (Objective-C/Swift on iOS or Java/C++ on Android). -### FPS (Frames per Second) Monitor -On `0.5.0-rc` and higher versions, you can enable a FPS graph overlay in the developers menu in order to help you debug performance problems. +### Automatic reloading + +You may enable Live Reload to automatically trigger a reload whenever your JavaScript code changes. + +Live Reload is available on iOS via the Developer Menu. On Android, select "Dev Settings" from the Developer Menu and enable "Auto reload on JS change". + +## Accessing logs + +To view detailed logs on iOS, open your app in Xcode, then Build and Run your app on a device or the iPhone Simulator. The console should appear automatically after the app launches. + +Run `adb logcat *:S ReactNative:V ReactNativeJS:V` in a terminal to display the logs for an Android app running on a device or an emulator. + +## Chrome Developer Tools + +To debug the JavaScript code in Chrome, select `Debug JS Remotely` from the Developer Menu. This will open a new tab at [http://localhost:8081/debugger-ui](http://localhost:8081/debugger-ui). + +In Chrome, press `Command⌘ + Option⌥ + I` or select `View` → `Developer` → `Developer Tools` to toggle the developer tools console. Enable [Pause On Caught Exceptions](http://stackoverflow.com/questions/2233339/javascript-is-there-a-way-to-get-chrome-to-break-on-all-errors/17324511#17324511) for a better debugging experience. + +### Debugging on a device with Chrome Developer Tools + +On iOS devices, open the file [`RCTWebSocketExecutor.m`](https://github.com/facebook/react-native/blob/master/Libraries/WebSocket/RCTWebSocketExecutor.m) and change `localhost` to the IP address of your computer, then select `Debug JS Remotely` from the Developer Menu. + +On Android 5.0+ devices connected via USB, you can use the [`adb` command line tool](http://developer.android.com/tools/help/adb.html) to setup port forwarding from the device to your computer: + +`adb reverse tcp:8081 tcp:8081` + +Alternatively, select `Dev Settings` from the Developer Menu, then update the `Debug server host for device` setting to match the IP address of your computer. + +### Debugging using a custom JavaScript debugger + +To use a custom JavaScript debugger in place of Chrome Developer Tools, set the `REACT_DEBUGGER` environment variable to a command that will start your custom debugger. You can then select `Debug JS Remotely` from the Developer Menu to start debugging. + +> The debugger will receive a list of all project roots, separated by a space. For example, if you set `REACT_DEBUGGER="node /path/to/launchDebugger.js --port 2345 --type ReactNative"`, then the command `node /path/to/launchDebugger.js --port 2345 --type ReactNative /path/to/reactNative/app` will be used to start your debugger. Custom debugger commands executed this way should be short-lived processes, and they shouldn't produce more than 200 kilobytes of output. + +## FPS (Frames per Second) Monitor + +You can enable a FPS graph overlay in the Developer Menu in order to help you debug performance problems. diff --git a/docs/QuickStart-GettingStarted.md b/docs/QuickStart-GettingStarted.md index cd30ef889ea67d..249296abf0e91f 100644 --- a/docs/QuickStart-GettingStarted.md +++ b/docs/QuickStart-GettingStarted.md @@ -56,35 +56,31 @@ block { display: none; } - + -## Installation +## Installing React Native -### Required Prerequisites +There's a few things you need to install first. You will need Node.js, the React Native command line tools, Watchman, and Xcode. -#### Homebrew + -[Homebrew](http://brew.sh/), in order to install the required NodeJS, in addition to some -recommended installs. +## Installing React Native -``` -/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -``` +There's a few things you need to install first. You will need Node.js, the React Native command line tools, Watchman, and Android Studio. -#### Node + -Use Homebrew to install [Node.js](https://nodejs.org/). +#### 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. +We recommend installing Node.js via [Homebrew](http://brew.sh/), a popular package manager for OS X: ``` brew install node ``` -#### React Native Command Line Tools +#### React Native command line tools -The React Native command line tools allow you to easily create and initialize projects, etc. +Use Node's package manager to install the React Native command line tools. These will allow you to easily create your first React Native project. ``` npm install -g react-native-cli @@ -93,69 +89,6 @@ 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](https://developer.apple.com/xcode/downloads/) 7.0 or higher is required. You can install Xcode via the App Store or [Apple developer downloads](https://developer.apple.com/xcode/downloads/). This will install the Xcode IDE and Xcode Command Line Tools. - -> While generally installed by default, you can verify that the Xcode Command Line Tools are installed by launching Xcode and selecting `Xcode | Preferences | Locations` and ensuring there is a version of the command line tools shown in the `Command Line Tools` list box. The Command Line Tools give you `git`, etc. - - - -#### Android Studio - -[Android Studio](http://developer.android.com/sdk/index.html) 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](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). - -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](img/react-native-android-studio-custom-install.png) - -- Choose both `Performance` and `Android Virtual Device` - -![additional installs](img/react-native-android-studio-additional-installs.png) - -- After installation, choose `Configure | SDK Manager` from the Android Studio welcome window. - -![configure sdk](img/react-native-android-studio-configure-sdk.png) - -- 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](img/react-native-android-studio-android-sdk-platforms.png) - -- 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](img/react-native-android-studio-android-sdk-build-tools.png) - -#### 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](https://facebook.github.io/watchman/docs/install.html) is a tool by Facebook for watching @@ -165,513 +98,103 @@ changes in the filesystem. It is recommended you install it for better performan brew install watchman ``` -#### Flow + -[Flow](http://www.flowtype.org), for static typechecking of your React Native code (when using -Flow as part of your codebase). +#### Xcode - -``` -brew install flow -``` +You can install Xcode via the [Mac App Store](https://itunes.apple.com/us/app/xcode/id497799835?mt=12), or download it directly from the [Apple Developer portal](https://developer.apple.com/xcode/downloads/). -#### 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`: +#### Android Studio -``` -# Your exact string here may be different. -PATH="~/Library/Android/sdk/tools:~/Library/Android/sdk/platform-tools:${PATH}" -export PATH -``` +Download and install [Android Studio](https://developer.android.com/studio/install.html). #### Gradle Daemon -Enable [Gradle Daemon](https://docs.gradle.org/2.9/userguide/gradle_daemon.html) which greatly improves incremental build times for changes in java code. - -### Other Optional Installs - -#### Git - -Git version control. If you have installed [Xcode](https://developer.apple.com/xcode/), Git is -already installed, otherwise run the following: - -``` -brew install git -``` - - - -#### Nuclide - -[Nuclide](http://nuclide.io) is an IDE from Facebook providing a first-class development environment -for writing, [running](http://nuclide.io/docs/platforms/react-native/#running-applications) and -[debugging](http://nuclide.io/docs/platforms/react-native/#debugging) -[React Native](http://nuclide.io/docs/platforms/react-native/) applications. - -Get started with Nuclide [here](http://nuclide.io/docs/quick-start/getting-started/). - - - -#### 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 Genymotion, see below. - -1. Download and install [Genymotion](https://www.genymotion.com/). -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](https://code.google.com/p/android/issues/detail?id=207563) 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](img/react-native-android-studio-avd.png) - -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 `/android/build.gradle` (https://github.com/facebook/react-native/issues/2720) +While optional, enabling [Gradle Daemon](https://docs.gradle.org/2.9/userguide/gradle_daemon.html) will greatly improve incremental build times for changes in Java code. -## Installation - -### Required Prerequisites - - - -#### Chocolatey +## Installing React Native -[Chocolatey](https://chocolatey.org) is a package manager for Windows similar to `yum` and -`apt-get`. See the [website](https://chocolatey.org) 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 Terminal and use Chocolatey to install Python 2. - -> Python 3 will currently not work when initializing a React Native project. - -``` -choco install python2 -``` +There's a few things you need to install first. You will need Node.js, the React Native command line tools, Watchman, and Android Studio. -#### Node +#### Node.js -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 -``` +Follow the [installation instructions for your Linux distribution](https://nodejs.org/en/download/package-manager/) to install Node.js 4 or newer. -Fire up the Termimal and use Chocolatey to install NodeJS. +We recommend installing Node.js via [Chocolatey](https://chocolatey.org), a popular package manager for Windows. Open a Command Prompt as Administrator, then run the following command: ``` choco install nodejs.install ``` - - -#### React Native Command Line Tools +##### Python -The React Native command line tools allow you to easily create and initialize projects, etc. +The React Native command line tools require Python2. Install it using Chocolatey: ``` -npm install -g react-native-cli +choco install python2 ``` -> If you see the error, `EACCES: permission denied`, please run the command: -> `sudo npm install -g react-native-cli`. - -#### Android Studio - -[Android Studio](http://developer.android.com/sdk/index.html) 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](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html), -> 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](img/react-native-android-studio-custom-install-linux.png) - -- Choose `Android Virtual Device` - -![additional installs](img/react-native-android-studio-additional-installs-linux.png) - - - -- 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](img/react-native-android-studio-custom-install-windows.png) - -- Verify installed components, particularly the emulator and the HAXM accelerator. They should be checked. - -![verify installs](img/react-native-android-studio-verify-installs-windows.png) - - - -- After installation, choose `Configure | SDK Manager` from the Android Studio welcome window. - - - -![configure sdk](img/react-native-android-studio-configure-sdk-linux.png) - - - -![configure sdk](img/react-native-android-studio-configure-sdk-windows.png) - - - -- 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](img/react-native-android-studio-android-sdk-platforms-linux.png) - - - -![platforms](img/react-native-android-studio-android-sdk-platforms-windows.png) - -- 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. +#### React Native command line tools - - -![build tools](img/react-native-android-studio-android-sdk-build-tools-linux.png) - - - -![build tools](img/react-native-android-studio-android-sdk-build-tools-windows.png) - - - -#### 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: +Use Node's package manager to install the React Native command line tools. These will allow you to easily create your first React Native project. ``` -# 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 +npm install -g react-native-cli ``` -> 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](img/react-native-android-sdk-environment-variable-windows.png) +> If you see the error, `EACCES: permission denied`, please run the command: +> `sudo npm install -g react-native-cli`. -> You need to restart the Command Prompt (Windows) to apply the new environment variables. + - +#### Android Studio -### Highly Recommended Installs +Download and install [Android Studio](https://developer.android.com/studio/install.html). #### 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](http://www.flowtype.org), 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 -``` +[Watchman](https://facebook.github.io/watchman) is a tool by Facebook for watching changes in the filesystem. It is recommended you install +it for better performance. You can follow the [Watchman installation guide](https://facebook.github.io/watchman/docs/install.html#installing-from-source) to compile and install from source. #### Gradle Daemon -Enable [Gradle Daemon](https://docs.gradle.org/2.9/userguide/gradle_daemon.html) 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](img/react-native-android-studio-kvm-linux.png) - -If your system supports KVM, you should install the -[Intel Android Emulator Accelerator](https://software.intel.com/en-us/android/articles/speeding-up-the-android-emulator-on-intel-architecture#_Toc358213272). - - - -#### 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](img/react-native-android-tools-environment-variable-windows.png) - - - -### Other Optional Installs - -#### Git - - - -Install Git [via your package manager](https://git-scm.com/download/linux) -(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](https://git-for-windows.github.io/). -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](http://nuclide.io/docs/platforms/react-native/#running-applications) and -[debugging](http://nuclide.io/docs/platforms/react-native/#debugging) -[React Native](http://nuclide.io/docs/platforms/react-native/) applications. - -Get started with Nuclide [here](http://nuclide.io/docs/quick-start/getting-started/). - - - -#### 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](https://www.genymotion.com/). -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](https://www.visualstudio.com/en-us/features/msft-android-emulator-vs.aspx) -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](https://code.google.com/p/android/issues/detail?id=207563) 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](img/react-native-android-studio-no-virtual-device-windows.png) - - - -If you see this, run `android avd` and create the virtual device manually. - - - -![avd](img/react-native-android-studio-avd-linux.png) - - - -![avd](img/react-native-android-studio-avd-windows.png) - - - -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 `/android/build.gradle` (https://github.com/facebook/react-native/issues/2720) +While optional, enabling [Gradle Daemon](https://docs.gradle.org/2.9/userguide/gradle_daemon.html) will greatly improve incremental build times for changes in Java code. -## Testing Installation +## Testing your React Native Installation +Use the React Native command line tools to generate a new React Native project called "AwesomeProject", then run `react-native run-ios` inside the newly created folder. + ``` react-native init AwesomeProject cd AwesomeProject react-native run-ios ``` +If everything is set up correctly, you should see your new app running in the iOS Simulator shortly. + > You can also > [open the `AwesomeProject`](http://nuclide.io/docs/quick-start/getting-started/#adding-a-project) > folder in [Nuclide](http://nuclide.io) and @@ -680,12 +203,16 @@ react-native run-ios +Use the React Native command line tools to generate a new React Native project called "AwesomeProject", then run `react-native run-android` inside the newly created folder. + ``` react-native init AwesomeProject cd AwesomeProject react-native run-android ``` +If everything is set up correctly, you should see your new app running in your Android emulator shortly. + > You can also > [open the `AwesomeProject`](http://nuclide.io/docs/quick-start/getting-started/#adding-a-project) > folder in [Nuclide](http://nuclide.io) and @@ -693,24 +220,23 @@ react-native run-android -### Modifying Project +### Modifying your app -Now that you successfully started the project, let's modify it: +Now that you have successfully run the app, let's modify it. -- Open `index.ios.js` in your text editor of choice (e.g. [Nuclide](http://nuclide.io/docs/platforms/react-native/)) and edit some lines. -- Hit ⌘-R in your iOS simulator to reload the app and see your change! +- Open `index.ios.js` in your text editor of choice and edit some lines. +- Hit `Command⌘ + 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](http://nuclide.io/docs/platforms/react-native/)) 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 +- Open `index.android.js` in your text editor of choice and edit some lines. +- Press the `R` key twice or select `Reload` from the Developer Menu to see your change! -### That's It +### That's it! Congratulations! You've successfully run and modified your first React Native app. @@ -718,7 +244,9 @@ Congratulations! You've successfully run and modified your first React Native ap -## Testing Installation +## Testing your React Native Installation + +Use the React Native command line tools to generate a new React Native project called "AwesomeProject", then run `react-native run-android` inside the newly created folder. ``` react-native init AwesomeProject @@ -726,33 +254,25 @@ cd AwesomeProject react-native run-android ``` - +If everything is set up correctly, you should see your new app running in your Android emulator shortly. -### 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 -``` +> A common issue is that the packager is not started automatically when you run +`react-native run-android`. You can start it manually using `react-native start`. -Or if you hit a `ERROR Watcher took too long to load` on Windows, try increasing the timeout in [this file](https://github.com/facebook/react-native/blob/5fa33f3d07f8595a188f6fe04d6168a6ede1e721/packager/react-packager/src/DependencyResolver/FileWatcher/index.js#L16) (under your `node_modules/react-native/`). +> If you hit a `ERROR Watcher took too long to load` on Windows, try increasing the timeout in [this file](https://github.com/facebook/react-native/blob/5fa33f3d07f8595a188f6fe04d6168a6ede1e721/packager/react-packager/src/DependencyResolver/FileWatcher/index.js#L16) (under your `node_modules/react-native/`). -### Modifying Project +### Modifying your app -Now that you successfully started the project, let's modify it: +Now that you have successfully run the app, let's modify it. -- Open `index.android.js` in your text editor of choice (e.g. [Nuclide](http://nuclide.io/docs/platforms/react-native/)) 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 +- Open `index.android.js` in your text editor of choice and edit some lines. +- Press the `R` key twice or select `Reload` from the Developer Menu to see your change! -### That's It +### That's it! Congratulations! You've successfully run and modified your first React Native app. @@ -772,8 +292,7 @@ Congratulations! You've successfully run and modified your first React Native ap -- If you run into any issues getting started, see the [Troubleshooting page](docs/troubleshooting.html#content). - +- If you run into any issues getting started, see the [Troubleshooting](docs/troubleshooting.html#content) and [Debugging](docs/debugging.html#content) pages. @@ -781,7 +300,7 @@ Congratulations! You've successfully run and modified your first React Native ap - If you want to run on a physical device, see the [Running on Android Device page](docs/running-on-device-android.html#content). -- If you run into any issues getting started, see the [Troubleshooting page](docs/troubleshooting.html#content). +- If you run into any issues getting started, see the [Troubleshooting](docs/troubleshooting.html#content) and [Debugging](docs/debugging.html#content) pages.