You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/debugging.md
+77-83Lines changed: 77 additions & 83 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,141 +14,135 @@ React Native provides an in-app developer menu which offers several debugging op
14
14
15
15
Alternatively for Android devices and emulators, you can run `adb shell input keyevent 82` in your terminal.
16
16
17
-
17
+
18
18
19
19
:::note
20
20
The Dev Menu is disabled in release (production) builds.
21
21
:::
22
22
23
-
## LogBox
24
-
25
-
Errors and warnings in development builds are displayed in LogBox inside your app.
26
-
27
-
:::note
28
-
LogBox is disabled in release (production) builds.
29
-
:::
23
+
## Opening the Debugger
30
24
31
-
### Console Errors and Warnings
32
-
33
-
Console errors and warnings are displayed as on-screen notifications with a red or yellow badge, and the number of errors or warning in the console respectively. To view a console error or warnings, tap the notification to view the full screen information about the log and to paginate through all of the logs in the console.
34
-
35
-
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.
25
+
The debugger allows you to understand and debug how your JavaScript code is running, similar to a web browser.
36
26
37
27
:::info
38
-
Ignore logs as a last resort and create a task to fix any logs that are ignored.
28
+
**In Expo projects**, press <kbd>j</kbd> in the CLI to directly open the Hermes Debugger.
Hermes supports the Chrome debugger by implementing the Chrome DevTools Protocol. This means Chrome's tools can be used to directly debug JavaScript running on Hermes, on an emulator or on a physical device.
50
35
51
-
### Unhandled Errors
36
+
1. In a Chrome browser window, navigate to `chrome://inspect`.
37
+
2. Use the "Configure..." button to add the dev server address (typically `localhost:8081`).
38
+
3. You should now see a "Hermes React Native" target with an **"inspect"** link. Click this to open the debugger.
52
39
53
-
Unhandled JavaScript errors such as `undefined is not a function` will automatically open a full screen LogBox error with the source of the error. These errors are dismissable and minimizable so that you can see the state of your app when these errors occur, but should always be addressed.
40
+
54
41
55
-
### Syntax Errors
42
+
</TabItem>
43
+
<TabItemvalue="flipper">
56
44
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).
45
+
[Flipper](https://fbflipper.com/)is a native debugging tool which provides JavaScript debugging capabilities for React Native via an embedded Chrome DevTools panel.
58
46
59
-
## JavaScript debugging
47
+
To debug JavaScript code in Flipper, select **"Open Debugger"** from the Dev Menu. Learn more about Flipper [here](https://fbflipper.com/docs/features/react-native/).
60
48
61
-
### Flipper
49
+
:::info
50
+
To debug using Flipper, the Flipper app must be [installed on your system](https://fbflipper.com/docs/getting-started/).
51
+
:::
62
52
63
-
To debug JavaScript code in Flipper, select "Open Debugger" from the Dev Menu. This will automatically open the debugger tab inside Flipper.
53
+
64
54
65
-
To install and get started with Flipper, follow [this guide](https://fbflipper.com/docs/getting-started/).
55
+
:::warning
56
+
Debugging React Native apps with Flipper is [deprecated in React Native 0.73](https://github.com/react-native-community/discussions-and-proposals/pull/641). We will eventually remove out-of-the box support for JS debugging via Flipper.
57
+
:::
66
58
67
-
### Expo CLI
59
+
</TabItem>
60
+
<TabItemvalue="new-debugger">
68
61
69
-
If you're using Expo CLI in a project running with Hermes, you can debug your JavaScript code by starting your project with `npx expo start` and then pressing <kbd>j</kbd> to open the debugger in Google Chrome or Microsoft Edge.
62
+
:::note
63
+
**This is an experimental feature** and several features may not work reliably today. When this feature does launch in future, we intend for it to work more completely than the current debugging methods.
64
+
:::
70
65
71
-
## Chrome Developer Tools
66
+
The React Native team is working on a new JavaScript debugger experience, intended to replace Flipper, with a preview available as of React Native 0.73.
72
67
73
-
:::info
74
-
**Starting from version 0.73, Remote Debugging is deprecated.** These Chrome DevTools steps use the _Remote Debugging_ workflow, where JS code is executed in Chrome's V8 engine on the dev machine during debugging, instead of on-device. This method is incompatible with some New Architecture features such as JSI.
68
+
The new debugger can be enabled via React Native CLI. This will also enable <kbd>j</kbd> to debug.
75
69
76
-
Please prefer using Flipper or [direct debugging with Safari](#safari-developer-tools).
77
-
:::
70
+
```sh
71
+
npx react-native start --experimental-debugger
72
+
```
78
73
79
-
<details>
80
-
<summary>Re-enabling Remote Debugging in React Native 0.73</summary>
74
+
When selecting **"Open Debugger"** in the Dev Menu, this will launch the new debugger using Google Chrome or Microsoft Edge.
81
75
82
-
If your project still relies on this feature, you can manually enable it manually through the `NativeDevSettings.setIsDebuggingRemotely` function.
76
+
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.
-[React Developer Tools on react.dev](https://react.dev/learn/react-developer-tools)
110
97
111
-
On Android 5.0+ devices connected via USB, you can use the [`adb` command line tool](https://developer.android.com/tools/help/adb.html) to set up port forwarding from the device to your computer:
98
+
:::
112
99
113
-
```sh
114
-
adb reverse tcp:8081 tcp:8081
115
-
```
100
+
## LogBox
116
101
117
-
Alternatively, select "Settings" from the Dev Menu, then update the "Debug server host for device" setting to match the IP address of your computer.
102
+
Errors and warnings in development builds are displayed in LogBox inside your app.
118
103
119
-
</TabItem>
120
-
</Tabs>
104
+
121
105
122
106
:::note
123
-
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.
107
+
LogBox is disabled in release (production) builds.
124
108
:::
125
109
126
-
<details>
127
-
<summary>Advanced: Debugging using a custom JavaScript debugger</summary>
110
+
### Console Errors and Warnings
128
111
129
-
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.
112
+
Console errors and warnings are displayed as on-screen notifications with a red or yellow badge, and a notification count. To see more about an error or warning, tap the notification to see an expanded view and to paginate through other logs.
130
113
131
-
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.
114
+
LogBox notifications can be disabled using `LogBox.ignoreAllLogs()`. This can be useful when giving product demos, for example. Additionally, notifications can be disabled on a per-log basis via `LogBox.ignoreLogs()`. This can be useful for noisy warnings or those that cannot be fixed, e.g. in a third-party dependency.
132
115
133
-
:::note
134
-
Custom debugger commands executed this way should be short-lived processes, and they shouldn't produce more than 200 kilobytes of output.
116
+
:::info
117
+
Ignore logs as a last resort and create a task to fix any logs that are ignored.
135
118
:::
136
119
137
-
</details>
120
+
```js
121
+
import {LogBox} from'react-native';
138
122
139
-
## Safari Developer Tools
123
+
// Ignore log notification by message
124
+
LogBox.ignoreLogs([
125
+
// Exact message
126
+
'Warning: componentWillReceiveProps has been renamed',
140
127
141
-
You can use Safari to debug the iOS version of your app when using JSC.
128
+
// Substring or regex match
129
+
/GraphQL error: .*/,
130
+
]);
142
131
143
-
- On a physical device go to: `Settings → Safari → Advanced → Make sure "Web Inspector" is turned on` (This step is not needed on the Simulator)
144
-
- On your Mac enable Develop menu in Safari: `Settings... (or Preferences...) → Advanced → Select "Show Develop menu in menu bar"`
145
-
- Select your app's JSContext: `Develop → Simulator (or other device) → JSContext`
146
-
- Safari's Web Inspector should open which has a Console and a Debugger
132
+
// Ignore all log notifications
133
+
LogBox.ignoreAllLogs();
134
+
```
147
135
148
-
While sourcemaps may not be enabled by default, you can follow [this guide](https://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.
136
+
### Syntax Errors
149
137
150
-
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.
138
+
When a JavaScript syntax error occurs, LogBox will open with the location of the error. In this state, LogBox is not dismissable since your code cannot be executed. LogBox will automatically dismiss once the syntax error is fixed — either via Fast Refresh or after a manual reload.
151
139
152
140
## Performance Monitor
153
141
154
-
You can enable a performance overlay to help you debug performance problems by selecting "Perf Monitor" in the Dev Menu.
142
+
On Android and iOS, an in-app performance overlay can be toggled during development by selecting **"Perf Monitor"** in the Dev Menu. Learn more about this feature [here](/docs/performance).
143
+
144
+
145
+
146
+
:::info
147
+
The Performance Monitor runs in-app and is a guide. We recommend investigating the native tooling under Android Studio and Xcode for accurate performance measurements.
0 commit comments