Added CHANGELOG and READMEs for DevTools v4 NPM packages (#16404)
Brian Vaughn committed
Aug 15, 2019 at 10:06 UTC
6edff8f5e1c961ff65c182820442525c212216bb
4 files changed
+430
packages/react-devtools-core/README.md
new
+44
@@ -0,0 +1,44 @@
1
+# `react-devtools-core`
2
+
3
+A standalone React DevTools implementation.
4
+
5
+This is a low-level package. If you're looking for the Electron app you can run, **use `react-devtools` package instead.**
6
+
7
+## API
8
+
9
+### `react-devtools-core`
10
+
11
+This is similar requiring the `react-devtools` package, but provides several configurable options. Unlike `react-devtools`, requiring `react-devtools-core` doesn't connect immediately but instead exports a function:
12
+
13
+```js
14
+const { connectToDevTools } = require("react-devtools-core");
15
+connectToDevTools({
16
+ // Config options
17
+});
18
+
19
+```
20
+
21
+Run `connectToDevTools()` in the same context as React to set up a connection to DevTools.
22
+Be sure to run this function *before* importing e.g. `react`, `react-dom`, `react-native`.
23
+
24
+The `options` object may contain:
25
+* `host: string` (defaults to "localhost") - Websocket will connect to this host.
26
+* `port: number` (defaults to `8097`) - Websocket will connect to this port.
27
+* `websocket: Websocket` - Custom websocked to use. Overrides `host` and `port` settings if provided.
28
+* `resolveNativeStyle: (style: number) => ?Object` - Used by the React Native style plug-in.
29
+* `isAppActive: () => boolean` - If provided, DevTools will poll this method and wait until it returns true before connecting to React.
30
+
31
+## `react-devtools-core/standalone`
32
+
33
+Renders the DevTools interface into a DOM node.
34
+
35
+```js
36
+require("react-devtools-core/standalone")
37
+ .setContentDOMNode(document.getElementById("container"))
38
+ .setStatusListener(status => {
39
+ // This callback is optional...
40
+ })
41
+ .startServer(port);
42
+```
43
+
44
+Reference the `react-devtools` package for a complete integration example.
\ No newline at end of file
packages/react-devtools-inline/README.md
new
+146
@@ -0,0 +1,146 @@
1
+# `react-devtools-inline`
2
+
3
+React DevTools implementation for embedding within a browser-based IDE (e.g. [CodeSandbox](https://codesandbox.io/), [StackBlitz](https://stackblitz.com/)).
4
+
5
+This is a low-level package. If you're looking for the standalone DevTools app, **use the `react-devtools` package instead.**
6
+
7
+## Usage
8
+
9
+This package exports two entry points: a frontend (to be run in the main `window`) and a backend (to be installed and run within an `iframe`<sup>1</sup>).
10
+
11
+The frontend and backend can be initialized in any order, but **the backend must not be activated until after the frontend has been initialized**. Because of this, the simplest sequence is:
12
+
13
+1. Frontend (DevTools interface) initialized in the main `window`.
14
+1. Backend initialized in an `iframe`.
15
+1. Backend activated.
16
+
17
+<sup>1</sup> Sandboxed iframes are supported.
18
+
19
+## API
20
+
21
+### `react-devtools-inline/backend`
22
+
23
+* **`initialize(contentWindow)`** -
24
+Installs the global hook on the window. This hook is how React and DevTools communicate. **This method must be called before React is loaded.** (This means before any `import` or `require` statements!)
25
+* **`activate(contentWindow)`** -
26
+Lets the backend know when the frontend is ready. It should not be called until after the frontend has been initialized, else the frontend might miss important tree-initialization events.
27
+
28
+```js
29
+import { activate, initialize } from 'react-devtools-inline/backend';
30
+
31
+// Call this before importing React (or any other packages that might import React).
32
+initialize();
33
+
34
+// Call this only once the frontend has been initialized.
35
+activate();
36
+```
37
+
38
+### `react-devtools-inline/frontend`
39
+
40
+* **`initialize(contentWindow)`** -
41
+Configures the DevTools interface to listen to the `window` the backend was injected into. This method returns a React component that can be rendered directly<sup>2</sup>.
42
+
43
+```js
44
+import { initialize } from 'react-devtools-inline/frontend';
45
+
46
+// This should be the iframe the backend hook has been installed in.
47
+const iframe = document.getElementById(frameID);
48
+const contentWindow = iframe.contentWindow;
49
+
50
+// This returns a React component that can be rendered into your app.
51
+// <DevTools {...props} />
52
+const DevTools = initialize(contentWindow);
53
+```
54
+
55
+<sup>2</sup> Because the DevTools interface makes use of several new React APIs (e.g. suspense, concurrent mode) it should be rendered using either `ReactDOM.unstable_createRoot` or `ReactDOM.unstable_createSyncRoot`. It should not be rendered with `ReactDOM.render`.
56
+
57
+## Examples
58
+
59
+### Configuring a same-origin `iframe`
60
+
61
+The simplest way to use this package is to install the hook from the parent `window`. This is possible if the `iframe` is not sandboxed and there are no cross-origin restrictions.
62
+
63
+```js
64
+import {
65
+ activate as activateBackend,
66
+ initialize as initializeBackend
67
+} from 'react-devtools-inline/backend';
68
+import { initialize as initializeFrontend } from 'react-devtools-inline/frontend';
69
+
70
+// The React app you want to inspect with DevTools is running within this iframe:
71
+const iframe = document.getElementById('target');
72
+const { contentWindow } = iframe;
73
+
74
+// Installs the global hook into the iframe.
75
+// This must be called before React is loaded into that frame.
76
+initializeBackend(contentWindow);
77
+
78
+// React application can be injected into <iframe> at any time now...
79
+// Note that this would need to be done via <script> tag injection,
80
+// as setting the src of the <iframe> would load a new page (withou the injected backend).
81
+
82
+// Initialize DevTools UI to listen to the hook we just installed.
83
+// This returns a React component we can render anywhere in the parent window.
84
+const DevTools = initializeFrontend(contentWindow);
85
+
86
+// <DevTools /> interface can be rendered in the parent window at any time now...
87
+// Be sure to use either ReactDOM.unstable_createRoot()
88
+// or ReactDOM.unstable_createSyncRoot() to render this component.
89
+
90
+// Let the backend know the frontend is ready and listening.
91
+activateBackend(contentWindow);
92
+```
93
+
94
+### Configuring a sandboxed `iframe`
95
+
96
+Sandboxed `iframe`s are also supported but require more complex initialization.
97
+
98
+**`iframe.html`**
99
+```js
100
+import { activate, initialize } from "react-devtools-inline/backend";
101
+
102
+// The DevTooks hook needs to be installed before React is even required!
103
+// The safest way to do this is probably to install it in a separate script tag.
104
+initialize(window);
105
+
106
+// Wait for the frontend to let us know that it's ready.
107
+function onMessage({ data }) {
108
+ switch (data.type) {
109
+ case "activate-backend":
110
+ window.removeEventListener("message", onMessage);
111
+
112
+ activate(window);
113
+ break;
114
+ default:
115
+ break;
116
+ }
117
+}
118
+
119
+window.addEventListener("message", onMessage);
120
+```
121
+
122
+**`main-window.html`**
123
+```js
124
+import { initialize } from "react-devtools-inline/frontend";
125
+
126
+const iframe = document.getElementById("target");
127
+const { contentWindow } = iframe;
128
+
129
+// Initialize DevTools UI to listen to the iframe.
130
+// This returns a React component we can render anywhere in the main window.
131
+// Be sure to use either ReactDOM.unstable_createRoot()
132
+// or ReactDOM.unstable_createSyncRoot() to render this component.
133
+const DevTools = initialize(contentWindow);
134
+
135
+// Let the backend know to initialize itself.
136
+// We can't do this directly because the iframe is sandboxed.
137
+// Only initialize the backend once the DevTools frontend has been initialized.
138
+iframe.onload = () => {
139
+ contentWindow.postMessage(
140
+ {
141
+ type: "activate-backend"
142
+ },
143
+ "*"
144
+ );
145
+};
146
+```
\ No newline at end of file
packages/react-devtools/CHANGELOG.md
new
+142
@@ -0,0 +1,142 @@
1
+# React DevTools changelog
2
+
3
+<!-- ## [Unreleased]
4
+<details>
5
+ <summary>
6
+ Changes that have landed in master but are not yet released.
7
+ Click to see more.
8
+ </summary>
9
+
10
+ <!-- Upcoming changes go here
11
+</details> -->
12
+
13
+## 4.0.0 (release date TBD)
14
+
15
+### General changes
16
+
17
+#### Improved performance
18
+The legacy DevTools extension used to add significant performance overhead, making it unusable for some larger React applications. That overhead has been effectively eliminated in version 4.
19
+
20
+[Learn more](https://github.com/bvaughn/react-devtools-experimental/blob/master/OVERVIEW.md) about the performance optimizations that made this possible.
21
+
22
+#### Component stacks
23
+
24
+React component authors have often requested a way to log warnings that include the React ["component stack"](https://reactjs.org/docs/error-boundaries.html#component-stack-traces). DevTools now provides an option to automatically append this information to warnings (`console.warn`) and errors (`console.error`).
25
+
26
+
27
+
28
+It can be disabled in the general settings panel:
29
+
30
+
31
+
32
+### Components tree changes
33
+
34
+#### Component filters
35
+
36
+Large component trees can sometimes be hard to navigate. DevTools now provides a way to filter components so that you can hide ones you're not interested in seeing.
37
+
38
+
39
+
40
+Host nodes (e.g. HTML `<div>`, React Native `View`) are now hidden by default, but you can see them by disabling that filter.
41
+
42
+Filter preferences are remembered between sessions.
43
+
44
+#### No more in-line props
45
+
46
+Components in the tree no longer show in-line props. This was done to [make DevTools faster](https://github.com/bvaughn/react-devtools-experimental/blob/master/OVERVIEW.md) and to make it easier to browse larger component trees.
47
+
48
+You can view a component's props, state, and hooks by selecting it:
49
+
50
+
51
+
52
+#### "Rendered by" list
53
+
54
+In React, an element's "owner" refers the thing that rendered it. Sometimes an element's parent is also its owner, but usually they're different. This distinction is important because props come from owners.
55
+
56
+
57
+
58
+When you are debugging an unexpected prop value, you can save time if you skip over the parents.
59
+
60
+DevTools v4 adds a new "rendered by" list in the right hand pane that allows you to quickly step through the list of owners to speed up your debugging.
61
+
62
+
63
+
64
+#### Owners tree
65
+
66
+The inverse of the "rendered by" list is called the "owners tree". It is the list of things rendered by a particular component- (the things it "owns"). This view is kind of like looking at the source of the component's render method, and can be a helpful way to explore large, unfamiliar React applications.
67
+
68
+Double click a component to view the owners tree and click the "x" button to return to the full component tree:
69
+
70
+
71
+
72
+#### No more horizontal scrolling
73
+
74
+Deeply nested components used to require both vertical and horizontal scrolling to see, making it easy to "get lost" within large component trees. DevTools now dynamically adjusts nesting indentation to eliminate horizontal scrolling.
75
+
76
+
77
+
78
+#### Improved hooks support
79
+
80
+Hooks now have the same level of support as props and state: values can be edited, arrays and objects can be drilled into, etc.
81
+
82
+
83
+
84
+#### Improved search UX
85
+
86
+Legacy DevTools search filtered the components tree to show matching nodes as roots. This made the overall structure of the application harder to reason about, because it displayed ancestors as siblings.
87
+
88
+Search results are now shown inline similar to the browser's find-in-page search.
89
+
90
+
91
+
92
+#### Higher order components
93
+
94
+[Higher order components](https://reactjs.org/docs/higher-order-components.html) (or HOCs) often provide a [custom `displayName`](https://reactjs.org/docs/higher-order-components.html#convention-wrap-the-display-name-for-easy-debugging) following a convention of `withHOC(InnerComponentName)` in order to make it easier to identify components in React warnings and in DevTools.
95
+
96
+The new Components tree formats these HOC names (along with several built-in utilities like `React.memo` and `React.forwardRef`) as a special badge to the right of the decorated component name.
97
+
98
+
99
+
100
+Components decorated with multiple HOCs show the topmost badge and a count. Selecting the component shows all of the HOCs badges in the properties panel.
101
+
102
+
103
+
104
+#### Suspense toggle
105
+
106
+React's experimental [Suspense API](https://reactjs.org/docs/react-api.html#suspense) lets components "wait" for something before rendering. `<Suspense>` components can be used to specify loading states when components deeper in the tree are waiting to render.
107
+
108
+DevTools lets you test these loading states with a new toggle:
109
+
110
+
111
+
112
+### Profiler changes
113
+
114
+#### Reload and profile
115
+
116
+The profiler is a powerful tool for performance tuning React components. Legacy DevTools supported profiling, but only after it detected a profiling-capable version of React. Because of this there was no way to profile the initial _mount_ (one of the most performance sensitive parts) of an application.
117
+
118
+This feature is now supported with a "reload and profile" action:
119
+
120
+
121
+
122
+#### Import/export
123
+
124
+Profiler data can now be exported and shared with other developers to enable easier collaboration.
125
+
126
+
127
+
128
+Exports include all commits, timings, interactions, etc.
129
+
130
+#### "Why did this render?"
131
+
132
+"Why did this render?" is a common question when profiling. The profiler now helps answer this question by recording which props and state change between renders.
133
+
134
+
135
+
136
+Because this feature adds a small amount of overhead, it can be disabled in the profiler settings panel.
137
+
138
+#### Component renders list
139
+
140
+The profiler now displays a list of each time the selected component rendered during a profiling session, along with the duration of each render. This list can be used to quickly jump between commits when analyzing the performance of a specific component.
141
+
142
+
\ No newline at end of file
packages/react-devtools/README.md
new
+98
@@ -0,0 +1,98 @@
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
+<img src="http://i.imgur.com/IXeHiZD.png" width="600" alt="Screenshot of React DevTools running with React Native">
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
+
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
+You can choose "Hide Inspector" in the same menu to exit this mode.
53
+
54
+### Inspecting Component Instances
55
+
56
+When debugging JavaScript in Chrome, you can inspect the props and state of the React components in the browser console.
57
+
58
+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.
59
+
60
+Make sure that the dropdown in the top left corner of the Chrome console says `debuggerWorker.js`. **This step is essential.**
61
+
62
+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.
63
+
64
+
65
+
66
+
67
+## Usage with React DOM
68
+
69
+The standalone shell can also be useful with React DOM (e.g. to debug apps in Safari or inside of an iframe).
70
+
71
+Run `react-devtools` from the terminal to launch the standalone DevTools app:
72
+```sh
73
+react-devtools
74
+```
75
+
76
+Add `<script src="http://localhost:8097"></script>` as the very first `<script>` tag in the `<head>` of your page when developing:
77
+
78
+```html
79
+<!doctype html>
80
+<html lang="en">
81
+ <head>
82
+ <script src="http://localhost:8097"></script>
83
+```
84
+
85
+This will ensure the developer tools are connected. **Don’t forget to remove it before deploying to production!**
86
+
87
+>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.
88
+
89
+## Advanced
90
+
91
+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.
92
+
93
+## Developing
94
+
95
+* Run `yarn start:backend` and `yarn start:standalone` in `../react-devtools-core`
96
+* Run `yarn start` in this folder
97
+* Refresh the app after it has recompiled a change
98
+* For React Native, copy `react-devtools-core` to its `node_modules` to test your changes.
\ No newline at end of file