diff --git a/releases/next/docs/debugging.html b/releases/next/docs/debugging.html index 80a18a45050..a6cf382edc9 100644 --- a/releases/next/docs/debugging.html +++ b/releases/next/docs/debugging.html @@ -1,4 +1,4 @@ -Debugging – React Native | A framework for building native apps using React
React Nativenext

Quick Start

Basics

Sample Applications

Community Resources

Guides

Guides (iOS)

Guides (Android)

components

apis

Polyfills

Debugging #

Edit on GitHub

In-app Errors and Warnings #

Errors and warnings are displayed inside your app in development builds.

Errors #

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.

Warnings #

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.

As with a RedBox, you can use console.warn() to trigger a YellowBox.

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: ...'];

RedBoxes and YellowBoxes are automatically disabled in release (production) builds.

Accessing the In-App Developer Menu #

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.

The Developer Menu is disabled in release (production) builds.

Reloading JavaScript #

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.

You will need to rebuild your app for changes to take effect in certain situations:

  • 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).

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.

In Chrome, press Command⌘ + Option⌥ + I or select View → Developer → Developer Tools to toggle the developer tools console. Enable Pause On Caught Exceptions for a better debugging experience.

Debugging on a device with Chrome Developer Tools #

On iOS devices, open the file 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 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.

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
React Nativenext

Quick Start

Basics

Sample Applications

Community Resources

Guides

Guides (iOS)

Guides (Android)

components

apis

Polyfills

Debugging #

Edit on GitHub

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.

The Developer Menu is disabled in release (production) builds.

Reloading JavaScript #

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.

If you are using a Dvorak/Colemak layout, use the Command⌘ + P keyboard shortcut to reload the simulator.

You will need to rebuild your app for changes to take effect in certain situations:

  • 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).

If the Command⌘ + R keyboard shortcut does not seem to reload the iOS Simulator, go to the Hardware menu, select Keyboard, and make sure that "Connect Hardware Keyboard" is checked.

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".

In-app Errors and Warnings #

Errors and warnings are displayed inside your app in development builds.

Errors #

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.

Warnings #

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.

As with a RedBox, you can use console.warn() to trigger a YellowBox.

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: ...'];

RedBoxes and YellowBoxes are automatically disabled in release (production) builds.

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. If your app is failing to build, check the Issues Navigator in Xcode.

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.

In Chrome, press Command⌘ + Option⌥ + I or select View → Developer → Developer Tools to toggle the developer tools console. Enable Pause On Caught Exceptions for a better debugging experience.

Debugging on a device with Chrome Developer Tools #

On iOS devices, open the file 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 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.

If you run into any issues, it may be possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. Try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.

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.

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
React Nativenext

Quick Start

Basics

Sample Applications

Community Resources

Guides

Guides (iOS)

Guides (Android)

components

apis

Polyfills

Running On Device #

Edit on GitHub

Note that running on device requires Apple Developer account and provisioning your iPhone. This guide covers only React Native specific topic.

Accessing development server from device #

You can iterate quickly on device using development server. To do that, your laptop and your phone have to be on the same wifi network.

  1. Open AwesomeApp/ios/AwesomeApp/AppDelegate.m
  2. Change the IP in the URL from localhost to your laptop's IP. On Mac, you can find the IP address in System Preferences / Network.
  3. Temporarily disable App Transport Security (ATS) by adding the NSAllowsArbitraryLoads entry to your Info.plist file. Since ATS does not allow insecure HTTP requests to IP addresses, you must completely disable it to run on a device. This is only a requirement for development on a device, and unless you can't workaround an issue you should leave ATS enabled for production builds. For more information, see this post on configuring ATS.
  4. In Xcode select your phone as build target and press "Build and run"

Hint

Shake the device to open development menu (reload, debug, etc.)

Using offline bundle #

When you run your app on device, we pack all the JavaScript code and the images used into the app's resources. This way you can test it without development server running and submit the app to the AppStore.

  1. Open AwesomeApp/ios/AwesomeApp/AppDelegate.m
  2. Uncomment jsCodeLocation = [[NSBundle mainBundle] ...
  3. The JS bundle will be built for dev or prod depending on your app's scheme (Debug = development build with warnings, Release = minified prod build with perf optimizations). To change the scheme navigate to Product > Scheme > Edit Scheme... in xcode and change Build Configuration between Debug and Release.

Disabling in-app developer menu #

When building your app for production, your app's scheme should be set to Release as detailed in the debugging documentation in order to disable the in-app developer menu.

Troubleshooting #

If curl command fails make sure the packager is running. Also try adding --ipv4 flag to the end of it.

Note that since v0.14 JS and images are automatically packaged into the iOS app using Bundle React Native code and images Xcode build phase.

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
React Nativenext

Quick Start

Basics

Sample Applications

Community Resources

Guides

Guides (iOS)

Guides (Android)

components

apis

Polyfills

Running On Device #

Edit on GitHub

Note that running on device requires Apple Developer account and provisioning your iPhone. This guide covers only React Native specific topic.

Accessing development server from device #

You can iterate quickly on device using development server. Ensure that you are on the same WiFi network as your computer.

  1. Open AwesomeApp/ios/AwesomeApp/AppDelegate.m
  2. Change the IP in the URL from localhost to your laptop's IP. On Mac, you can find the IP address in System Preferences / Network.
  3. Temporarily disable App Transport Security (ATS) by adding the NSAllowsArbitraryLoads entry to your Info.plist file. Since ATS does not allow insecure HTTP requests to IP addresses, you must completely disable it to run on a device. This is only a requirement for development on a device, and unless you can't workaround an issue you should leave ATS enabled for production builds. For more information, see this post on configuring ATS.
  4. In Xcode select your phone as build target and press "Build and run"

Hint

Shake the device to open development menu (reload, debug, etc.)

Using offline bundle #

When you run your app on device, we pack all the JavaScript code and the images used into the app's resources. This way you can test it without development server running and submit the app to the AppStore.

  1. Open AwesomeApp/ios/AwesomeApp/AppDelegate.m
  2. Uncomment jsCodeLocation = [[NSBundle mainBundle] ...
  3. The JS bundle will be built for dev or prod depending on your app's scheme (Debug = development build with warnings, Release = minified prod build with perf optimizations). To change the scheme navigate to Product > Scheme > Edit Scheme... in xcode and change Build Configuration between Debug and Release.

Disabling in-app developer menu #

When building your app for production, your app's scheme should be set to Release as detailed in the debugging documentation in order to disable the in-app developer menu.

Troubleshooting #

If curl command fails make sure the packager is running. Also try adding --ipv4 flag to the end of it.

Note that since v0.14 JS and images are automatically packaged into the iOS app using Bundle React Native code and images Xcode build phase.

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
React Nativenext

Quick Start

Basics

Sample Applications

Community Resources

Guides

Guides (iOS)

Guides (Android)

components

apis

Polyfills

Troubleshooting #

Edit on GitHub

Cmd-R does not reload the simulator #

Enable iOS simulator's "Connect hardware keyboard" from menu Hardware > Keyboard menu.

Keyboard Menu

If you are using a non-QWERTY/AZERTY keyboard layout you can use the Hardware > Shake Gesture to bring up the dev menu and click "Refresh". Alternatively, you can hit Cmd-P on Dvorak/Colemak layouts to reload the simulator.

You can use Cmd+M on Android to bring up the dev menu.

Port already in use red-screen #

red-screen

Something is probably already running on port 8081. You can either kill it or try to change which port the packager is listening to.

Kill process on port 8081 #

$ sudo lsof -n -i4TCP:8081 | grep LISTEN

then

$ kill -9 <cma process id>

Change the port in Xcode #

Edit AppDelegate.m to use a different port.

// OPTION 1 - // Load from development server. Start the server from the repository root: - // - // $ npm start - // - // To run on device, change `localhost` to the IP address of your computer, and make sure your computer and - // iOS device are on the same Wi-Fi network. - jsCodeLocation = [NSURL URLWithString:@"http://localhost:9381/index.ios.bundle"];

Watchman took too long to load #

Permission settings prevent Watchman from loading. A recent update solves this, get a HEAD install of Watchman if you are experiencing this error.

brew uninstall watchman -brew install --HEAD watchman

NPM locking error #

If in the react-native init <project> phase you saw npm fail with "npm WARN locking Error: EACCES" then try the following:

sudo chown -R $USER ~/.npm -sudo chown -R $USER /usr/local/lib/node_modules

Debugging in Chrome hangs and/or does not work well #

It is possible that one of your Chrome extensions is interacting in unexpected ways with the debugger. If you are having this issue, try disabling all of your extensions and re-enabling them one-by-one until you find the problematic extension.

Xcode Build Failures #

To see the exact error that is causing your build to fail, go into the Issues Navigator in the left sidebar.

React libraries missing #

If you are using CocoaPods, verify that you have added React along with the subspecs to the Podfile. For example, if you were using the <Text />, <Image /> and fetch() APIs, you would need to add these in your Podfile:

pod 'React', :path => '../node_modules/react-native', :subspecs => [ +Troubleshooting – React Native | A framework for building native apps using React
React Nativenext

Quick Start

Basics

Sample Applications

Community Resources

Guides

Guides (iOS)

Guides (Android)

components

apis

Polyfills

Troubleshooting #

Edit on GitHub

These are some common issues you may run into while setting up React Native. If you encounter something that is not listed here, try searching for the issue in GitHub.

Port already in use #

The React Native packager runs on port 8081. If another process is already using that port (such as McAfee Antivirus on Windows), you can either terminate that process, or change the port that the packager uses.

Terminating a process on port 8081 #

Run the following command on a Mac to find the id for the process that is listening on port 8081:

$ sudo lsof -n -i4TCP:8081 | grep LISTEN

Then run the following to terminate the process:

$ kill -9 <PID>

Using a port other than 8081 #

You can configure the packager to use a port other than 8081 by using the port parameter:

$ react-native start --port=8088

You will also need to update your applications to load the JavaScript bundle from the new port.

To change the port used by an iOS application, edit the AppDelegate.m file in the ios folder. Scroll down to the line where the bundle location is defined, and replace 8081 with the new port.

jsCodeLocation = [NSURL URLWithString:@"http://localhost:8088/index.ios.bundle"];

NPM locking error #

If you encounter an error such as "npm WARN locking Error: EACCES" while using the React Native CLI, try running the following:

sudo chown -R $USER ~/.npm +sudo chown -R $USER /usr/local/lib/node_modules

Missing libraries for React #

If you added React Native manually to your project, make sure you have included all the relevant dependencies that you are using, like RCTText.xcodeproj, RCTImage.xcodeproj. Next, the binaries built by these dependencies have to be linked to your app binary. Use the Linked Frameworks and Binaries section in the Xcode project settings. More detailed steps are here: Linking Libraries.

If you are using CocoaPods, verify that you have added React along with the subspecs to the Podfile. For example, if you were using the <Text />, <Image /> and fetch() APIs, you would need to add these in your Podfile:

pod 'React', :path => '../node_modules/react-native', :subspecs => [ 'RCTText', 'RCTImage', 'RCTNetwork', 'RCTWebSocket', -]

Next, make sure you have run pod install and that a Pods/ directory has been created in your project with React installed. CocoaPods will instruct you to use the generated .xcworkspace file henceforth to be able to use these installed dependencies.

If you are adding React manually, make sure you have included all the relevant dependencies, like RCTText.xcodeproj, RCTImage.xcodeproj depending on the ones you are using. Next, the binaries built by these dependencies have to be linked to your app binary. Use the Linked Frameworks and Binaries section in the Xcode project settings. More detailed steps are here: Linking Libraries.

Argument list too long: recursive header expansion failed #

In the project's build settings, User Search Header Paths and Header Search Paths are two configs that specify where Xcode should look for #import header files specified in the code. For Pods, CocoaPods uses a default array of specific folders to look in. Verify that this particular config is not overwritten, and that none of the folders configured are too large. If one of the folders is a large folder, Xcode will attempt to recursively search the entire directory and throw above error at some point.

To revert the User Search Header Paths and Header Search Paths build settings to their defaults set by CocoaPods - select the entry in the Build Settings panel, and hit delete. It will remove the custom override and return to the CocoaPod defaults.

Unable to connect to development server #

iOS #

Ensure that you are on the same WiFi network as your computer. If you're using a cell data plan, your phone can't access your computer's local IP address.

Android #

You need to run adb reverse tcp:8081 tcp:8081 to forward requests from the device to your computer. This works only on Android 5.0 and newer.

Module that uses WebSocket (such as Firebase) throws an exception #

React Native implements a polyfill for WebSockets. These polyfills are initialized as part of the react-native module that you include in your application through import React from 'react-native'. If you load another module that requires WebSockets, be sure to load/require it after react-native.

So:

import React from 'react-native'; -import Firebase from 'firebase';

Requiring firebase before react-native will result in a 'No transports available' redbox.

Discovered thanks to issue #3645. If you're curious, the polyfills are set up in InitializeJavaScriptAppEngine.js.

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)

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
© 2016 Facebook Inc.