Expand Getting Started, Debugging, Running on Device guides.

Summary:
- Clarified PATH instructions.
- Expand running on device instructions for iOS.
- Add Android production release instructions.
- Misc. cleanup.
Closes https://github.com/facebook/react-native/pull/14142

Differential Revision: D5116072

Pulled By: hramos

fbshipit-source-id: d95274f61a9b26282977d43d3307b726a6b93704
This commit is contained in:
Hector Ramos 2017-05-23 15:59:58 -07:00 committed by Facebook Github Bot
parent a79043035e
commit 674a64284f
6 changed files with 109 additions and 71 deletions

View File

@ -14,7 +14,7 @@ React Native supports a few keyboard shortcuts in the iOS Simulator. They are de
## Accessing the In-App Developer Menu
You can access the developer menu by shaking your device or by selecting "Shake Gesture" inside the Hardware menu in the iOS Simulator. 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.
You can access the developer menu by shaking your device or by selecting "Shake Gesture" inside the Hardware menu in the iOS Simulator. You can also use the `⌘D` keyboard shortcut when your app is running in the iOS Simulator, or `⌘M` when running in an Android emulator.
![](img/DeveloperMenu.png)
@ -22,7 +22,7 @@ You can access the developer menu by shaking your device or by selecting "Shake
## Reloading JavaScript
Instead of recompiling your app every time you make a change, you can reload your app's JavaScript code instantly. To do so, select "Reload" from the Developer Menu. You can also press **`Command`**`⌘` + **`R`** in the iOS Simulator, or press **`R`** twice on Android emulators.
Instead of recompiling your app every time you make a change, you can reload your app's JavaScript code instantly. To do so, select "Reload" from the Developer Menu. You can also press `⌘R` in the iOS Simulator, or tap `R` twice on Android emulators.
### Automatic reloading
@ -61,7 +61,7 @@ In CI/Xcode, YellowBoxes can also be disabled by setting the `IS_TESTING` enviro
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).
Select `Tools → Developer Tools` from the Chrome Menu to open the [Developer Tools](https://developer.chrome.com/devtools). You may also access the DevTools using keyboard shortcuts (**`Command`**`⌘` + **`Option`**`⌥` + **`I`** on Mac, **`Ctrl`** + **`Shift`** + **`I`** on Windows). You may also want to 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.
Select `Tools → Developer Tools` from the Chrome Menu to open the [Developer Tools](https://developer.chrome.com/devtools). You may also access the DevTools using keyboard shortcuts (`⌘⌥I` on macOS, `Ctrl` `Shift` `I` on Windows). You may also want to 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.
> Note: the React Developer Tools Chrome extension does not work with React Native, but you can use its standalone version instead. Read [this section](docs/debugging.html#react-developer-tools) to learn how.
@ -75,7 +75,7 @@ The debugger will receive a list of all project roots, separated by a space. For
## React Developer Tools
With React Native 0.43 or higher, you can use [the standalone version of React Developer Tools](https://github.com/facebook/react-devtools/tree/master/packages/react-devtools) to debug the React component hierarchy. To use it, install the `react-devtools` package globally:
You can use [the standalone version of React Developer Tools](https://github.com/facebook/react-devtools/tree/master/packages/react-devtools) to debug the React component hierarchy. To use it, install the `react-devtools` package globally:
```
npm install -g react-devtools
@ -91,11 +91,11 @@ react-devtools
It should connect to your simulator within a few seconds.
> Note: if you prefer to avoid global installations, you can add `react-devtools` as a project dependency. With Yarn, you can run `yarn add --dev react-devtools`, and then run `yarn react-devtools` from your project folder to open the DevTools. With npm, you can run `npm install --save-dev react-devtools`, add `"react-devtools": "react-devtools"` to the `scripts` section in your `package.json`, and then run `npm run react-devtools` from your project folder to open the DevTools.
> Note: if you prefer to avoid global installations, you can add `react-devtools` as a project dependency. Add the `react-devtools` package to your project using `npm install --save-dev react-devtools`, then add `"react-devtools": "react-devtools"` to the `scripts` section in your `package.json`, and then run `npm run react-devtools` from your project folder to open the DevTools.
### Integration with React Native Inspector
You can open the [in-app developer menu](#accessing-the-in-app-developer-menu) and choose "Show Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:
Open the in-app developer menu and choose "Show Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:
![React Native Inspector](img/Inspector.gif)
@ -109,7 +109,7 @@ You can choose "Hide Inspector" in the same menu to exit this mode.
When debugging JavaScript in Chrome, you can inspect the props and state of the React components in the browser console.
First, follow the [instructions for debugging in Chrome](docs/debugging.html#chrome-developer-tools) to open the Chrome console.
First, follow the instructions for debugging in Chrome to open the Chrome console.
Make sure that the dropdown in the top left corner of the Chrome console says `debuggerWorker.js`. **This step is essential.**
@ -138,8 +138,6 @@ You can enable a performance overlay to help you debug performance problems by s
## Accessing console logs
Note: if you're using Create React Native App, these already appear in the same terminal output as the packager.
You can display the console logs for an iOS or Android app by using the following commands in a terminal while the app is running:
```
@ -149,9 +147,11 @@ $ react-native log-android
You may also access these through `Debug → Open System Log...` in the iOS Simulator or by running `adb logcat *:S ReactNative:V ReactNativeJS:V` in a terminal while an Android app is running on a device or emulator.
> If you're using Create React Native App, console logs already appear in the same terminal output as the packager.
## Debugging on a device with Chrome Developer Tools
Note: if you're using Create React Native App, this is configured for you already.
> If you're using Create React Native App, this is configured for you already.
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.
@ -201,8 +201,8 @@ Alternatively, select "Dev Settings" from the Developer Menu, then update the "D
4. Run ```react-native run-android ```
5. In a new chrome tab, open : ```chrome://inspect```, click on 'Inspect device' (the one followed by "Powered by Stetho")
5. In a new Chrome tab, open: ```chrome://inspect```, then click on 'Inspect device' (the one followed by "Powered by Stetho").
## Debugging native code
When working with native code (e.g. when writing native modules) you can launch the app from Android Studio or Xcode and take advantage of the debugging features (setup breakpoints, etc.) as you would in case of building a standard native app.
When working with native code, such as when writing native modules, you can launch the app from Android Studio or Xcode and take advantage of the native debugging features (setting up breakpoints, etc.) as you would in case of building a standard native app.

View File

@ -133,13 +133,19 @@ Congratulations! You've successfully run and modified your first React Native ap
## Now what?
- If you're curious to learn more about React Native, continue on
to the [Tutorial](docs/tutorial.html).
- Create React Native App also has a [user guide](https://github.com/react-community/create-react-native-app/blob/master/react-native-scripts/template/README.md) you can reference if you have questions specific to the tool.
- If you can't get this to work, see the [Troubleshooting](https://github.com/react-community/create-react-native-app/blob/master/react-native-scripts/template/README.md#troubleshooting) section in the README for Create React Native App.
If you're curious to learn more about React Native, continue on
to the [Tutorial](docs/tutorial.html).
### Running your app on a simulator or virtual device
Create React Native App makes it really easy to run your React Native app on a physical device without setting up a development environment. If you want to run your app on the iOS Simulator or an Android Virtual Device, please refer to the instructions for building projects with native code to learn how to install Xcode and set up your Android development environment.
Once you've set these up, you can launch your app on on an Android Virtual Device by running `npm run android`, or on the iOS Simulator by running `npm run ios` (macOS only).
### Caveats
Because you don't build any native code when using Create React Native App to create a project, it's not possible to include custom native modules beyond the React Native APIs and components that are available in the Expo client app.
@ -384,37 +390,37 @@ Finally, click "Apply" to download and install the Android SDK and related build
<block class="native mac windows linux android" />
#### 3. Set up the ANDROID_HOME environment variable
#### 3. Configure the ANDROID_HOME environment variable
The React Native tools require some environment variables to be set up in order to build apps with native code.
<block class="native mac linux android" />
Add the following lines to your `$HOME/.bash_profile` config file:
<block class="native mac android" />
Add the following lines to your `~/.profile` (or equivalent) config file:
```
export ANDROID_HOME=${HOME}/Library/Android/sdk
export PATH=${PATH}:${ANDROID_HOME}/tools
export PATH=${PATH}:${ANDROID_HOME}/platform-tools
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/platform-tools
```
Type `source ~/.profile` to load the config into your current shell.
> Please make sure you export the correct path for `ANDROID_HOME`. If you installed the Android SDK using Homebrew, it would be located at `/usr/local/opt/android-sdk`. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under **Appearance & Behavior****System Settings****Android SDK**.
<block class="native linux android" />
Add the following lines to your `~/.profile` (or equivalent) config file:
```
export ANDROID_HOME=${HOME}/Android/Sdk
export PATH=${PATH}:${ANDROID_HOME}/tools
export PATH=${PATH}:${ANDROID_HOME}/platform-tools
export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/platform-tools
```
Type `. ~/.profile` to load the config into your current shell.
<block class="native mac linux android" />
> Please make sure you export the correct path for `ANDROID_HOME` if you did not install the Android SDK using Android Studio. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under **Appearance & Behavior****System Settings****Android SDK**.
> `.bash_profile` is specific to `bash`. If you're using another shell, you will need to edit the appropriate shell-specific config file.
Type `source $HOME/.bash_profile` to load the config into your current shell. Verify that ANDROID_HOME has been added to your path by running `echo $PATH`.
> Please make sure you use the correct Android SDK path. You can find the actual location of the SDK in the Android Studio "Preferences" dialog, under **Appearance & Behavior****System Settings****Android SDK**.
<block class="native windows android" />
@ -475,7 +481,7 @@ Either way, you will need to prepare the device to run Android apps for developm
### Using a physical device
If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and [enabling USB debugging](https://developer.android.com/training/basics/firstapp/running-app.html). You can then proceed to the next step.
If you have a physical Android device, you can use it for development in place of an AVD by plugging it in to your computer using a USB cable and following the instructions [here](docs/running-on-device.html).
### Using a virtual device
@ -538,6 +544,12 @@ You should see your new app running in the iOS Simulator shortly.
`react-native run-ios` is just one way to run your app. You can also run it directly from within Xcode or [Nuclide](https://nuclide.io/).
> If you can't get this to work, see the [Troubleshooting](docs/troubleshooting.html#content) page.
### Running on a device
The above command will automatically run your app on the iOS Simulator by default. If you want to run the app on an actual physical iOS device, please follow the instructions [here](docs/running-on-device.html).
<block class="native mac windows linux android" />
## Running your React Native application
@ -563,6 +575,8 @@ If everything is set up correctly, you should see your new app running in your A
`react-native run-android` is just one way to run your app - you can also run it directly from within Android Studio or [Nuclide](https://nuclide.io/).
> If you can't get this to work, see the [Troubleshooting](docs/troubleshooting.html#content) page.
<block class="native mac ios android" />
### Modifying your app
@ -572,12 +586,12 @@ Now that you have successfully run the app, let's modify it.
<block class="native mac ios" />
- 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 changes!
- Hit `⌘R` in your iOS Simulator to reload the app and see your changes!
<block class="native mac android" />
- 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 changes!
- Press the `R` key twice or select `Reload` from the Developer Menu (`⌘M`) to see your changes!
<block class="native windows linux android" />
@ -586,7 +600,7 @@ Now that you have successfully run the app, 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 and edit some lines.
- Press the `R` key twice or select `Reload` from the Developer Menu to see your changes!
- Press the `R` key twice or select `Reload` from the Developer Menu (`⌘M`) to see your changes!
<block class="native mac ios android" />
@ -600,32 +614,31 @@ Congratulations! You've successfully run and modified your first React Native ap
### That's it!
Congratulations! You've successfully run and modified a React Native app.
Congratulations! You've successfully run and modified your first React Native app.
<center><img src="img/react-native-congratulations.png" width="150"></img></center>
<block class="native mac ios" />
## Now What?
## Now what?
- If you're curious to learn more about React Native, continue on
to the [Tutorial](docs/tutorial.html).
- If you can't get this to work, see the [Troubleshooting](docs/troubleshooting.html#content) page.
- Turn on [Live Reload](docs/debugging.html#reloading-javascript) in the Developer Menu. Your app will now reload automatically whenever you save any changes!
- If you want to add this new React Native code to an existing application, check out the [Integration guide](docs/integration-with-existing-apps.html).
If you're curious to learn more about React Native, continue on
to the [Tutorial](docs/tutorial.html).
<block class="native windows linux mac android" />
## Now What?
## Now what?
- If you're curious to learn more about React Native, continue on
to the [Tutorial](docs/tutorial.html).
- If you can't get this to work, see the [Troubleshooting](docs/troubleshooting.html#content) page.
- Turn on [Live Reload](docs/debugging.html#reloading-javascript) in the Developer Menu. Your app will now reload automatically whenever you save any changes!
- If you want to add this new React Native code to an existing application, check out the [Integration guide](docs/integration-with-existing-apps.html).
If you're curious to learn more about React Native, continue on
to the [Tutorial](docs/tutorial.html).
<script>
// Convert <div>...<span><block /></span>...</div>

View File

@ -9,7 +9,7 @@ next: upgrading
previous: integration-with-existing-apps
---
It's always a good idea to test your app on an actual device before releasing it to your users. This document will guide you through the necessary steps to run your React Native app on a device.
It's always a good idea to test your app on an actual device before releasing it to your users. This document will guide you through the necessary steps to run your React Native app on a device and to get it ready for production.
<div class="toggler">
<style>
@ -39,18 +39,21 @@ It's always a good idea to test your app on an actual device before releasing it
display: block;
}
</style>
<span>Mobile OS:</span>
<a href="javascript:void(0);" class="button-ios" onclick="display('platform', 'ios')">iOS</a>
<a href="javascript:void(0);" class="button-android" onclick="display('platform', 'android')">Android</a>
<span>Development OS:</span>
<a href="javascript:void(0);" class="button-mac" onclick="display('os', 'mac')">macOS</a>
<a href="javascript:void(0);" class="button-linux" onclick="display('os', 'linux')">Linux</a>
<a href="javascript:void(0);" class="button-windows" onclick="display('os', 'windows')">Windows</a>
<span>Target OS:</span>
<a href="javascript:void(0);" class="button-ios" onclick="display('platform', 'ios')">iOS</a>
<a href="javascript:void(0);" class="button-android" onclick="display('platform', 'android')">Android</a>
</div>
<block class="linux windows ios" />
A Mac is required in order to build your app for iOS devices.
## Running your app on iOS devices
A Mac is required in order to build your app for iOS devices. Alternatively, you can refer to the [Quick Start instructions](docs/getting-started.html) to learn how to build your app using Create React Native App, which will allow you to run your app using the Expo client app.
<block class="mac ios" />
@ -58,13 +61,25 @@ A Mac is required in order to build your app for iOS devices.
Register for a [Apple developer account](https://developer.apple.com/) if you don't have one yet.
Connect your device to your Mac using a USB to Lightning cable. Navigate to the `ios` folder in your project, then open the `.xcodeproj` file within it using Xcode.
### 1. Plug in your device via USB
Select your app in the Project Navigator and look for the "General" tab. Go to "Signing" and make sure your Apple developer account is selected.
Connect your iOS device to your Mac using a USB to Lightning cable. Navigate to the `ios` folder in your project, then open the `.xcodeproj` file within it using Xcode.
Open the "Product" menu from Xcode's menubar, then go to "Destination". Look for and select your device from the list. Xcode will then register your device for development.
If this is your first time running an app on your iOS device, you may need to register your device for development. Open the **Product** menu from Xcode's menubar, then go to **Destination**. Look for and select your device from the list. Xcode will then register your device for development.
If everything is set up correctly, your device will be listed as the build target in the Xcode toolbar. You can now press the **Build and run** button or select "Run" from the "Product" menu. Your app will launch on your device shortly.
### 2. Configure code signing
Select your project in the Xcode Project Navigator, then select your main target (it should share the same name as your project). Look for the "General" tab. Go to "Signing" and make sure your Apple developer account or team is selected under the Team dropdown.
![](img/RunningOnDeviceCodeSigning.png)
Repeat this step for the Tests target in your project.
### 3. Build and Run your app
If everything is set up correctly, your device will be listed as the build target in the Xcode toolbar, and it will also appear in the Devices pane (`⇧⌘2`). You can now press the **Build and run** button (`⌘R`) or select **Run** from the **Product** menu. Your app will launch on your device shortly.
![](img/RunningOnDeviceReady.png)
> If you run into any issues, please take a look at Apple's [Launching Your App on a Device](https://developer.apple.com/library/content/documentation/IDEs/Conceptual/AppDistributionGuide/LaunchingYourApponDevices/LaunchingYourApponDevices.html#//apple_ref/doc/uid/TP40012582-CH27-SW4) docs.
@ -162,7 +177,9 @@ $ react-native run-android
## Connecting to the development server
You can also iterate quickly on a device using the development server. You only have to be on the same Wi-Fi network as your computer. Enable Live reloading from the [Developer menu](docs/debugging.html#accessing-the-in-app-developer-menu) and your app will reload whenever your JavaScript code has changed.
You can also iterate quickly on a device using the development server. You only have to be on the same Wi-Fi network as your computer. Shake your device to open the [Developer menu](docs/debugging.html#accessing-the-in-app-developer-menu), then enable Live Reload. Your app will reload whenever your JavaScript code has changed.
![](img/DeveloperMenu.png)
> If you have any issues, ensure that your Mac and device are on the same network and can reach each other. Many open wireless networks with captive portals are configured to prevent devices from reaching other devices on the network. You may use your device's Personal Hotspot feature in this case.
@ -176,7 +193,7 @@ You can also iterate quickly on a device by connecting to the development server
<block class="mac windows linux android" />
You can use this method if your device is running Android 5.0 (Lollipop), it has USB debugging enabled, and it is connected via USB to your development machine.
You can use this method if your device is running Android 5.0 (Lollipop) or newer, it has USB debugging enabled, and it is connected via USB to your development machine.
<block class="mac windows linux android" />
@ -222,25 +239,33 @@ You can now enable Live reloading from the [Developer menu](docs/debugging.html#
You have built a great app using React Native, and you are now itching to release it in the App Store. The process is the same as any other native iOS app, with some additional considerations to take into account.
Building an app for distribution in the App Store requires using the `Release` scheme in Xcode. To do this, go to **Product****Scheme****Edit Scheme (cmd + <)**, make sure you're in the **Run** tab from the side, and set the Build Configuration dropdown to `Release`.
### 1. Enable App Transport Security
Apps built for `Release` will automatically disable the in-app Developer menu, which will prevent your users from inadvertently accessing the menu in production. It will also load the JavaScript locally, so you can put the app on a device and test whilst not connected to the computer.
App Transport Security is a security feature introduced in iOS 9 that rejects all HTTP requests that are not sent over HTTPS. This can result in HTTP traffic being blocked, including the developer React Native server. ATS is disabled for `localhost` by default in React Native projects in order to make development easier.
You should re-enable ATS prior to building your app for production by removing the `localhost` entry from the `NSExceptionDomains` dictionary in your `Info.plist` file in the `ios/` folder. You can also re-enable ATS from within Xcode by opening your target properties under the Info pane and editing the App Transport Security Settings entry.
> If your application needs to access HTTP resources on production, see [this post](http://ste.vn/2015/06/10/configuring-app-transport-security-ios-9-osx-10-11/) to learn how to configure ATS on your project.
### 2. Configure release scheme
Building an app for distribution in the App Store requires using the `Release` scheme in Xcode. Apps built for `Release` will automatically disable the in-app Developer menu, which will prevent your users from inadvertently accessing the menu in production. It will also bundle the JavaScript locally, so you can put the app on a device and test whilst not connected to the computer.
To configure your app to be built using the `Release` scheme, go to **Product****Scheme****Edit Scheme**. Select the **Run** tab in the sidebar, then set the Build Configuration dropdown to `Release`.
![](img/ConfigureReleaseScheme.png)
### 3. Build app for release
You can now build your app for release by tapping `⌘B` or selecting **Product****Build** from the menu bar. Once built for release, you'll be able to distribute the app to beta testers and submit the app to the App Store.
> Hint
>
> You can also use the `React Native CLI` to perform this operation using the option `--configuration` with the value `Release` (e.g. `react-native run-ios --configuration Release`).
Once built for release, you'll be able to distribute the app to beta testers and submit the app to the App Store.
<block class="mac windows linux android" />
### App Transport Security
## Building your app for production
App Transport Security is a security feature, added in iOS 9, that rejects all HTTP requests that are not sent over HTTPS. This can result in HTTP traffic being blocked, including the developer React Native server.
ATS is disabled by default in projects generated using the React Native CLI in order to make development easier. You should re-enable ATS prior to building your app for production by removing the `NSAllowsArbitraryLoads` entry from your `Info.plist` file in the `ios/` folder.
To learn more about how to configure ATS on your own Xcode projects, see [this post on ATS][cats].
[cats]: http://ste.vn/2015/06/10/configuring-app-transport-security-ios-9-osx-10-11/
You have built a great app using React Native, and you are now itching to release it in the Play Store. The process is the same as any other native Android app, with some additional considerations to take into account. Follow the guide for [generating a signed APK](docs/signed-apk-android.html) to learn more.
<script>
// Convert <div>...<span><block /></span>...</div>

Binary file not shown.

After

Width:  |  Height:  |  Size: 68 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 107 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB