Skip to content

Commit 1b23012

Browse files
huntiehuntie
authored
[docs] Reorganise Debugging docs (#3693)
1 parent ade8b4f commit 1b23012

File tree

4 files changed

+156
-131
lines changed

4 files changed

+156
-131
lines changed

‎docs/debugging.md‎

Lines changed: 46 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: debugging
3-
title: Debugging
3+
title: Debugging Basics
44
---
55

66
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants';
@@ -20,10 +20,6 @@ Alternatively for Android devices and emulators, you can run `adb shell input ke
2020
The Dev Menu is disabled in release (production) builds.
2121
:::
2222

23-
## Enabling Fast Refresh
24-
25-
Fast Refresh is a React Native feature that allows you to get near-instant feedback for changes in your React components. While debugging, it can help to have [Fast Refresh](fast-refresh.md) enabled. Fast Refresh is enabled by default, and you can toggle "Enable Fast Refresh" in the Dev Menu. When enabled, most of your edits should be visible within a second or two.
26-
2723
## LogBox
2824

2925
Errors and warnings in development builds are displayed in LogBox inside your app.
@@ -38,7 +34,9 @@ Console errors and warnings are displayed as on-screen notifications with a red
3834

3935
These notifications can be hidden using `LogBox.ignoreAllLogs()`. This is useful when giving product demos, for example. Additionally, notifications can be hidden on a per-log basis via `LogBox.ignoreLogs()`. This is useful when there's a noisy warning that cannot be fixed, like those in a third-party dependency.
4036

41-
> Ignore logs as a last resort and create a task to fix any logs that are ignored.
37+
:::info
38+
Ignore logs as a last resort and create a task to fix any logs that are ignored.
39+
:::
4240

4341
```tsx
4442
import {LogBox} from 'react-native';
@@ -56,162 +54,80 @@ Unhandled JavaScript errors such as `undefined is not a function` will automatic
5654

5755
### Syntax Errors
5856

59-
When syntax error occurs the full screen LogBox error will automatically open with the stack trace and location of the syntax error. This error is not dismissable because it represents invalid JavaScript execution that must be fixed before continuing with your app. To dismiss these errors, fix the syntax error and either save to automatically dismiss (with Fast Refresh enabled) or cmd+r to reload (with Fast Refresh disabled).
57+
When syntax error occurs the full screen LogBox error will automatically open with the stack trace and location of the syntax error. This error is not dismissable because it represents invalid JavaScript execution that must be fixed before continuing with your app. To dismiss these errors, fix the syntax error and either save to automatically dismiss (with Fast Refresh enabled) or <kbd>Cmd ⌘</kbd>/<kbd>Ctrl</kbd> + <kbd>R</kbd> to reload (with Fast Refresh disabled).
6058

6159
## Chrome Developer Tools
6260

63-
To debug the JavaScript code in Chrome, select "Open Debugger" from the Dev Menu. This will open a new tab at [http://localhost:8081/debugger-ui](http://localhost:8081/debugger-ui).
64-
65-
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.
66-
67-
> Note: on Android, if the times between the debugger and device have drifted; things such as animation, event behavior, etc., might not work properly or the results may not be accurate. Please correct this by running `` adb shell "date `date +%m%d%H%M%Y.%S%3N`" `` on your debugger machine. Root access is required for the use in real device.
61+
To debug JavaScript code in Chrome, select "Open Debugger" from the Dev Menu. This will open a new tab at [http://localhost:8081/debugger-ui](http://localhost:8081/debugger-ui).
6862

69-
> Note: the React Developer Tools Chrome extension does not work with React Native, but you can use its standalone version instead. Read [this section](debugging.md#react-developer-tools) to learn how.
70-
71-
### Debugging using a custom JavaScript debugger
72-
73-
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 "Open Debugger" from the Dev Menu to start debugging.
74-
75-
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.
63+
From here, select `More Tools → Developer Tools` from the Chrome menu to open [Chrome DevTools](https://developer.chrome.com/devtools). Alternatively, you can use the shortcut <kbd>⌥ Option</kbd> + <kbd>Cmd ⌘</kbd> + <kbd>I</kbd> (macOS) / <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>I</kbd> (Windows and Linux).
7664

77-
> Custom debugger commands executed this way should be short-lived processes, and they shouldn't produce more than 200 kilobytes of output.
65+
- If you're new to Chrome DevTools, we recommend learning about the [Console](https://developer.chrome.com/docs/devtools/#console) and [Sources](https://developer.chrome.com/docs/devtools/#sources) tabs in the docs.
66+
- You may want to enable [Pause on Caught Exceptions](https://developer.chrome.com/docs/devtools/javascript/breakpoints/#exceptions) for a better debugging experience.
7867

79-
## Safari Developer Tools
80-
81-
You can use Safari to debug the iOS version of your app without having to enable "Debug JS Remotely".
68+
:::info
69+
The React Developer Tools Chrome extension does not work with React Native, but you can use its standalone version instead. Read [this section](debugging.md#react-developer-tools) to learn how.
70+
:::
8271

83-
- On a physical device go to: `Settings → Safari → Advanced → Make sure "Web Inspector" is turned on` (This step is not needed on the Simulator)
84-
- On your Mac enable Develop menu in Safari: `Preferences → Advanced → Select "Show Develop menu in menu bar"`
85-
- Select your app's JSContext: `Develop → Simulator (or other device) → JSContext`
86-
- Safari's Web Inspector should open which has a Console and a Debugger
72+
:::note
73+
On Android, if the times between the debugger and device have drifted, things such as animations and event behavior might not work properly. This can be fixed by running `` adb shell "date `date +%m%d%H%M%Y.%S%3N`" ``. Root access is required if using a physical device.
74+
:::
8775

88-
While sourcemaps may not be enabled by default, you can follow [this guide](http://blog.nparashuram.com/2019/10/debugging-react-native-ios-apps-with.html) or [video](https://www.youtube.com/watch?v=GrGqIIz51k4) to enable them and set break points at the right places in the source code.
76+
### Debugging on a physical device
8977

90-
However, every time the app is reloaded (using live reload, or by manually reloading), a new JSContext is created. Choosing "Automatically Show Web Inspectors for JSContexts" saves you from having to select the latest JSContext manually.
78+
:::info
79+
If you're using Expo CLI, this is configured for you already.
80+
:::
9181

92-
## React Developer Tools
82+
<Tabs groupId="platform" defaultValue={constants.defaultPlatform} values={constants.platforms} className="pill-tabs">
83+
<TabItem value="ios">
9384

94-
You can use [the standalone version of React Developer Tools](https://github.com/facebook/react/tree/main/packages/react-devtools) to debug the React component hierarchy. To use it, install the `react-devtools` package globally:
85+
On iOS devices, open the file [`RCTWebSocketExecutor.mm`](https://github.com/facebook/react-native/blob/master/packages/react-native/React/CoreModules/RCTWebSocketExecutor.mm) and change "localhost" to the IP address of your computer, then select "Debug JS Remotely" from the Dev Menu.
9586

96-
> Note: Version 4 of `react-devtools` requires `react-native` version 0.62 or higher to work properly.
87+
</TabItem>
88+
<TabItem value="android">
9789

98-
<Tabs groupId="package-manager" queryString defaultValue={constants.defaultPackageManager} values={constants.packageManagers}>
99-
<TabItem value="npm">
90+
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 set up port forwarding from the device to your computer:
10091

101-
```shell
102-
npm install -g react-devtools
92+
```sh
93+
adb reverse tcp:8081 tcp:8081
10394
```
10495

105-
</TabItem>
106-
<TabItem value="yarn">
107-
108-
```shell
109-
yarn global add react-devtools
110-
```
96+
Alternatively, select "Settings" from the Dev Menu, then update the "Debug server host for device" setting to match the IP address of your computer.
11197

11298
</TabItem>
11399
</Tabs>
114100

115-
Now run `react-devtools` from the terminal to launch the standalone DevTools app:
116-
117-
```shell
118-
react-devtools
119-
```
120-
121-
![React DevTools](/docs/assets/ReactDevTools.png)
122-
123-
It should connect to your simulator within a few seconds.
124-
125-
:::info
126-
If connecting to the emulator proves troublesome (especially Android 12), try running `adb reverse tcp:8097 tcp:8097` in a new terminal.
127-
:::
128-
129-
:::info
130-
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.
101+
:::note
102+
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.
131103
:::
132104

133-
### Integration with React Native Inspector
105+
<details>
106+
<summary>Advanced: Debugging using a custom JavaScript debugger</summary>
134107

135-
Open the Dev Menu and choose "Toggle Inspector". It will bring up an overlay that lets you tap on any UI element and see information about it:
136-
137-
![React Native Inspector](/docs/assets/Inspector.gif)
138-
139-
However, when `react-devtools` is running, Inspector will enter a collapsed mode, and instead use the DevTools as primary UI. In this mode, clicking on something in the simulator will bring up the relevant components in the DevTools:
108+
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 "Open Debugger" from the Dev Menu to start debugging.
140109

141-
![React DevTools Inspector Integration](/docs/assets/ReactDevToolsInspector.gif)
110+
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.
142111

143-
You can choose "Toggle Inspector" in the same menu to exit this mode.
112+
:::note
113+
Custom debugger commands executed this way should be short-lived processes, and they shouldn't produce more than 200 kilobytes of output.
114+
:::
144115

145-
### Inspecting Component Instances
116+
</details>
146117

147-
When debugging JavaScript in Chrome, you can inspect the props and state of the React components in the browser console.
118+
## Safari Developer Tools
148119

149-
First, follow the instructions for debugging in Chrome to open the Chrome console.
120+
You can use Safari to debug the iOS version of your app without having to enable "Debug JS Remotely".
150121

151-
Make sure that the dropdown in the top left corner of the Chrome console says `debuggerWorker.js`. **This step is essential.**
122+
- On a physical device go to: `Settings → Safari → Advanced → Make sure "Web Inspector" is turned on` (This step is not needed on the Simulator)
123+
- On your Mac enable Develop menu in Safari: `Preferences → Advanced → Select "Show Develop menu in menu bar"`
124+
- Select your app's JSContext: `Develop → Simulator (or other device) → JSContext`
125+
- Safari's Web Inspector should open which has a Console and a Debugger
152126

153-
Then select a React component in React DevTools. There is a search box at the top that helps you find one by name. As soon as you select it, it will be available as `$r` in the Chrome console, letting you inspect its props, state, and instance properties.
127+
While sourcemaps may not be enabled by default, you can follow [this guide](http://blog.nparashuram.com/2019/10/debugging-react-native-ios-apps-with.html) or [video](https://www.youtube.com/watch?v=GrGqIIz51k4) to enable them and set break points at the right places in the source code.
154128

155-
![React DevTools Chrome Console Integration](/docs/assets/ReactDevToolsDollarR.gif)
129+
However, every time the app is reloaded (using live reload, or by manually reloading), a new JSContext is created. Choosing "Automatically Show Web Inspectors for JSContexts" saves you from having to select the latest JSContext manually.
156130

157131
## Performance Monitor
158132

159133
You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Dev Menu.
160-
161-
<hr style={{marginTop: 25, marginBottom: 25}} />
162-
163-
## Debugging Application State
164-
165-
[Reactotron](https://github.com/infinitered/reactotron) is an open-source desktop app that allows you to inspect Redux or MobX-State-Tree application state as well as view custom logs, run custom commands such as resetting state, store and restore state snapshots, and other helpful debugging features for React Native apps.
166-
167-
You can view installation instructions [in the README](https://github.com/infinitered/reactotron). If you're using Expo, here is an article detailing [how to install on Expo](https://shift.infinite.red/start-using-reactotron-in-your-expo-project-today-in-3-easy-steps-a03d11032a7a).
168-
169-
# Native Debugging
170-
171-
<div className="banner-native-code-required">
172-
<h3>Projects with Native Code Only</h3>
173-
<p>
174-
The following section only applies to projects with native code exposed. If you are using the managed Expo workflow, see the guide on <a href="https://docs.expo.dev/workflow/prebuild/" target="_blank">prebuild</a> to use this API.
175-
</p>
176-
</div>
177-
178-
## Accessing console logs
179-
180-
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:
181-
182-
```shell
183-
npx react-native log-ios
184-
npx react-native log-android
185-
```
186-
187-
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.
188-
189-
> If you're using Create React Native App or Expo CLI, console logs already appear in the same terminal output as the bundler.
190-
191-
## Debugging on a device with Chrome Developer Tools
192-
193-
> If you're using Create React Native App or Expo CLI, this is configured for you already.
194-
195-
On iOS devices, open the file [`RCTWebSocketExecutor.mm`](https://github.com/facebook/react-native/blob/main/packages/react-native/React/CoreModules/RCTWebSocketExecutor.mm) and change "localhost" to the IP address of your computer, then select "Debug JS Remotely" from the Dev Menu.
196-
197-
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:
198-
199-
`adb reverse tcp:8081 tcp:8081`
200-
201-
Alternatively, select "Settings" from the Dev Menu, then update the "Debug server host for device" setting to match the IP address of your computer.
202-
203-
> 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.
204-
205-
## Debugging native code
206-
207-
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.
208-
209-
Another option is to run your application using the React Native CLI and attach the native debugger of the native IDE (Android Studio or Xcode) to the process.
210-
211-
### Android Studio
212-
213-
On Android Studio you can do this by going on the "Run" option on the menu bar, clicking on "Attach to Process..." and selecting the running React Native app.
214-
215-
### Xcode
216-
217-
On Xcode click on "Debug" on the top menu bar, select the "Attach to process" option, and select the application in the list of "Likely Targets".

‎docs/native-debugging.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
id: native-debugging
3+
title: Native Debugging
4+
---
5+
6+
import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants';
7+
8+
<div className="banner-native-code-required">
9+
<h3>Projects with Native Code Only</h3>
10+
<p>
11+
The following section only applies to projects with native code exposed. If you are using the managed Expo workflow, see the guide on <a href="https://docs.expo.dev/workflow/prebuild/" target="_blank">prebuild</a> to use this API.
12+
</p>
13+
</div>
14+
15+
## Accessing native logs
16+
17+
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:
18+
19+
```sh
20+
npx react-native log-ios
21+
npx react-native log-android
22+
```
23+
24+
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.
25+
26+
:::info
27+
If you're using Expo CLI, console logs already appear in the same terminal output as the bundler.
28+
:::
29+
30+
## Debugging native code
31+
32+
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.

0 commit comments

Comments
 (0)