| 1 | # `react-devtools`
|
| 2 |
|
| 3 | React DevTools is available as a built-in extension for Chrome and Firefox browsers. This package enables you to debug a React app elsewhere (e.g. a mobile browser, an embedded webview, Safari, inside an iframe).
|
| 4 |
|
| 5 | It works both with React DOM and React Native.
|
| 6 |
|
| 7 | 
|
| 8 |
|
| 9 | ## Installation
|
| 10 | Install the `react-devtools` package. Because this is a development tool, a global install is often the most convenient:
|
| 11 | ```sh
|
| 12 | # Yarn
|
| 13 | yarn global add react-devtools
|
| 14 |
|
| 15 | # NPM
|
| 16 | npm install -g react-devtools
|
| 17 | ```
|
| 18 |
|
| 19 | If you prefer to avoid global installations, you can add `react-devtools` as a project dependency. With Yarn, you can do this by running:
|
| 20 | ```sh
|
| 21 | yarn add --dev react-devtools
|
| 22 | ```
|
| 23 |
|
| 24 | With NPM you can just use [NPX](https://www.npmjs.com/package/npx):
|
| 25 | ```sh
|
| 26 | npx react-devtools
|
| 27 | ```
|
| 28 |
|
| 29 | ## Usage with React Native
|
| 30 | Run `react-devtools` from the terminal to launch the standalone DevTools app:
|
| 31 | ```sh
|
| 32 | react-devtools
|
| 33 | ```
|
| 34 |
|
| 35 | If you're not in a simulator then you also need to run the following in a command prompt:
|
| 36 | ```sh
|
| 37 | adb reverse tcp:8097 tcp:8097
|
| 38 | ```
|
| 39 |
|
| 40 | If you're using React Native 0.43 or higher, it should connect to your simulator within a few seconds.
|
| 41 |
|
| 42 | ### Integration with React Native Inspector
|
| 43 |
|
| 44 | You can open the [in-app developer menu](https://reactnative.dev/docs/debugging.html#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:
|
| 45 |
|
| 46 | 
|
| 47 |
|
| 48 | However, when `react-devtools` is running, Inspector will enter a special 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:
|
| 49 |
|
| 50 | 
|
| 51 |
|
| 52 |
|
| 53 | You can choose "Hide Inspector" in the same menu to exit this mode.
|
| 54 |
|
| 55 | ### Inspecting Component Instances
|
| 56 |
|
| 57 | When debugging JavaScript in Chrome, you can inspect the props and state of the React components in the browser console.
|
| 58 |
|
| 59 | First, follow the [instructions for debugging in Chrome](https://reactnative.dev/docs/debugging.html#chrome-developer-tools) to open the Chrome console.
|
| 60 |
|
| 61 | Make sure that the dropdown in the top left corner of the Chrome console says `debuggerWorker.js`. **This step is essential.**
|
| 62 |
|
| 63 | 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.
|
| 64 |
|
| 65 | 
|
| 66 |
|
| 67 |
|
| 68 | ## Usage with React DOM
|
| 69 |
|
| 70 | The standalone shell can also be useful with React DOM (e.g. to debug apps in Safari or inside of an iframe).
|
| 71 |
|
| 72 | Run `react-devtools` from the terminal to launch the standalone DevTools app:
|
| 73 | ```sh
|
| 74 | react-devtools
|
| 75 | ```
|
| 76 |
|
| 77 | Add `<script src="http://localhost:8097"></script>` as the very first `<script>` tag in the `<head>` of your page when developing:
|
| 78 |
|
| 79 | ```html
|
| 80 | <!doctype html>
|
| 81 | <html lang="en">
|
| 82 | <head>
|
| 83 | <script src="http://localhost:8097"></script>
|
| 84 | ```
|
| 85 |
|
| 86 | This will ensure the developer tools are connected. **Don’t forget to remove it before deploying to production!**
|
| 87 |
|
| 88 | >If you install `react-devtools` as a project dependency, you may also replace the `<script>` suggested above with a JavaScript import (`import 'react-devtools'`). It is important that this import comes before any other imports in your app (especially before `react-dom`). Make sure to remove the import before deploying to production, as it carries a large DevTools client with it. If you use Webpack and have control over its configuration, you could alternatively add `'react-devtools'` as the first item in the `entry` array of the development-only configuration, and then you wouldn’t need to deal either with `<script>` tags or `import` statements.
|
| 89 |
|
| 90 | ## Advanced
|
| 91 |
|
| 92 | By default DevTools listen to port `8097` on `localhost`. If you need to customize host, port, or other settings, see the `react-devtools-core` package instead.
|
| 93 |
|
| 94 | ## FAQ
|
| 95 |
|
| 96 | ### The React Tab Doesn't Show Up
|
| 97 |
|
| 98 | **If you are running your app from a local `file://` URL**, don't forget to check "Allow access to file URLs" on the Chrome Extensions settings page. You can find it by opening Settings > Extensions:
|
| 99 |
|
| 100 | 
|
| 101 |
|
| 102 | Or you could develop with a local HTTP server [like `serve`](https://www.npmjs.com/package/serve).
|
| 103 |
|
| 104 | **The React tab won't show up if the site doesn't use React**, or if React can't communicate with the devtools. When the page loads, the devtools sets a global named `__REACT_DEVTOOLS_GLOBAL_HOOK__`, then React communicates with that hook during initialization. You can test this on the [React website](https://reactjs.org/) or by inspecting [Facebook](https://www.facebook.com/).
|
| 105 |
|
| 106 | **If your app is inside of CodePen**, make sure you are registered. Then press Fork (if it's not your pen), and then choose Change View > Debug. The Debug view is inspectable with DevTools because it doesn't use an iframe.
|
| 107 |
|
| 108 | **If your app is inside an iframe, a Chrome extension, React Native, or in another unusual environment**, try [the standalone version instead](https://github.com/facebook/react/tree/master/packages/react-devtools). Chrome apps are currently not inspectable.
|
| 109 |
|
| 110 | **If you still have issues** please [report them](https://github.com/facebook/react/issues/new?labels=Component:%20Developer%20Tools). Don't forget to specify your OS, browser version, extension version, and the exact instructions to reproduce the issue with a screenshot.
|
| 111 |
|
| 112 | ## Local development
|
| 113 | The standalone DevTools app can be built and tested from source following the instructions below.
|
| 114 |
|
| 115 | ### Prerequisite steps
|
| 116 | DevTools depends on local versions of several NPM packages<sup>1</sup> also in this workspace. You'll need to either build or download those packages first.
|
| 117 |
|
| 118 | <sup>1</sup> Note that at this time, an _experimental_ build is required because DevTools depends on the `createRoot` API.
|
| 119 |
|
| 120 | #### Build from source
|
| 121 | To build dependencies from source, run the following command from the root of the repository:
|
| 122 | ```sh
|
| 123 | yarn build-for-devtools
|
| 124 | ```
|
| 125 | #### Download from CI
|
| 126 | To use the latest build from CI, run the following command from the root of the repository:
|
| 127 | ```sh
|
| 128 | ./scripts/release/download-experimental-build.js
|
| 129 | ```
|
| 130 | ### Build steps
|
| 131 | You can test the standalone DevTools by running the following:
|
| 132 |
|
| 133 | * **First, complete the prerequisite steps above! If you don't do it, none of the steps below will work.**
|
| 134 | * Then, run `yarn start:backend` and `yarn start:standalone` in `../react-devtools-core`
|
| 135 | * Run `yarn start` in this folder
|
| 136 | * Refresh the app after it has recompiled a change
|
| 137 | * For React Native, copy `react-devtools-core` to its `node_modules` to test your changes.
|