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 | ![React DevTools screenshot](https://user-images.githubusercontent.com/29597/63811956-bdd9b580-c8dd-11e9-8962-c568e475c425.png)
|
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://facebook.github.io/react-native/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 | ![React Native Inspector](http://i.imgur.com/ReFhREb.gif)
|
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 | ![React DevTools Inspector Integration](https://user-images.githubusercontent.com/29597/63811958-be724c00-c8dd-11e9-8587-37357334a0e1.gif)
|
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://facebook.github.io/react-native/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 | ![React DevTools Chrome Console Integration](https://user-images.githubusercontent.com/29597/63811957-be724c00-c8dd-11e9-9d1d-8eba440ef948.gif)
|
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 | ![Allow access to file URLs](https://user-images.githubusercontent.com/29597/64646784-95b58080-d3cc-11e9-943d-02474683398a.png)
|
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](http://facebook.github.io/react/) 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 | ## Development
|
113 |
|
114 | * Run `yarn start:backend` and `yarn start:standalone` in `../react-devtools-core`
|
115 | * Run `yarn start` in this folder
|
116 | * Refresh the app after it has recompiled a change
|
117 | * For React Native, copy `react-devtools-core` to its `node_modules` to test your changes.
|