mirror of
https://github.com/zebrajr/react.git
synced 2026-01-15 12:15:22 +00:00
a86afe8e56
Stacked on https://github.com/facebook/react/pull/30986. Previously, we would call `installHook` at a top level of the JavaScript module. Because of this, having `require` statement for `react-devtools-core` package was enough to initialize the React DevTools global hook on the `window`. Now, the Hook can actually receive an argument - initial user settings for console patching. We expose this as a function `initialize`, which can be used by third parties (including React Native) to provide the persisted settings. The README was also updated to reflect the changes.
153 lines
9.4 KiB
Markdown
153 lines
9.4 KiB
Markdown
# `react-devtools-core`
|
|
|
|
This package provides low-level APIs to support renderers like [React Native](https://github.com/facebook/react-native). If you're looking for the standalone React DevTools UI, **we suggest using [`react-devtools`](https://github.com/facebook/react/tree/main/packages/react-devtools) instead of using this package directly**.
|
|
|
|
This package provides two entrypoints: labeled "backend" and "standalone" (frontend). Both APIs are described below.
|
|
|
|
# Backend API
|
|
|
|
Backend APIs are embedded in _development_ builds of renderers like [React Native](https://github.com/facebook/react-native) in order to connect to the React DevTools UI.
|
|
|
|
### Example
|
|
|
|
If you are building a non-browser-based React renderer, you can use the backend API like so:
|
|
|
|
```js
|
|
if (process.env.NODE_ENV !== 'production') {
|
|
const { initialize, connectToDevTools } = require("react-devtools-core");
|
|
|
|
initialize(settings);
|
|
// Must be called before packages like react or react-native are imported
|
|
connectToDevTools({...config});
|
|
}
|
|
```
|
|
|
|
> **NOTE** that this API (`connectToDevTools`) must be (1) run in the same context as React and (2) must be called before React packages are imported (e.g. `react`, `react-dom`, `react-native`).
|
|
|
|
### `initialize` arguments
|
|
| Argument | Description |
|
|
|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| `settings` | Optional. If not specified, or received as null, then default settings are used. Can be plain object or a Promise that resolves with the [plain settings object](#Settings). If Promise rejects, the console will not be patched and some console features from React DevTools will not work. |
|
|
|
|
#### `Settings`
|
|
| Spec | Default value |
|
|
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| <pre>{<br> appendComponentStack: boolean,<br> breakOnConsoleErrors: boolean,<br> showInlineWarningsAndErrors: boolean,<br> hideConsoleLogsInStrictMode: boolean<br>}</pre> | <pre>{<br> appendComponentStack: true,<br> breakOnConsoleErrors: false,<br> showInlineWarningsAndErrors: true,<br> hideConsoleLogsInStrictMode: false<br>}</pre> |
|
|
|
|
### `connectToDevTools` options
|
|
| Prop | Default | Description |
|
|
|------------------------|---------------|---------------------------------------------------------------------------------------------------------------------------|
|
|
| `host` | `"localhost"` | Socket connection to frontend should use this host. |
|
|
| `isAppActive` | | (Optional) function that returns true/false, telling DevTools when it's ready to connect to React. |
|
|
| `port` | `8097` | Socket connection to frontend should use this port. |
|
|
| `resolveRNStyle` | | (Optional) function that accepts a key (number) and returns a style (object); used by React Native. |
|
|
| `retryConnectionDelay` | `200` | Delay (ms) to wait between retrying a failed Websocket connection |
|
|
| `useHttps` | `false` | Socket connection to frontend should use secure protocol (wss). |
|
|
| `websocket` | | Custom `WebSocket` connection to frontend; overrides `host` and `port` settings. |
|
|
| `onSettingsUpdated` | | A callback that will be called when the user updates the settings in the UI. You can use it for persisting user settings. | |
|
|
|
|
|
|
### `connectWithCustomMessagingProtocol` options
|
|
| Prop | Description |
|
|
|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| `onSubscribe` | Function, which receives listener (function, with a single argument) as an argument. Called when backend subscribes to messages from the other end (frontend). |
|
|
| `onUnsubscribe` | Function, which receives listener (function) as an argument. Called when backend unsubscribes to messages from the other end (frontend). |
|
|
| `onMessage` | Function, which receives 2 arguments: event (string) and payload (any). Called when backend emits a message, which should be sent to the frontend. |
|
|
| `onSettingsUpdated` | A callback that will be called when the user updates the settings in the UI. You can use it for persisting user settings. |
|
|
|
|
Unlike `connectToDevTools`, `connectWithCustomMessagingProtocol` returns a callback, which can be used for unsubscribing the backend from the global DevTools hook.
|
|
|
|
# Frontend API
|
|
|
|
Frontend APIs can be used to render the DevTools UI into a DOM node. One example of this is [`react-devtools`](https://github.com/facebook/react/tree/main/packages/react-devtools) which wraps DevTools in an Electron app.
|
|
|
|
### Example
|
|
```js
|
|
import DevtoolsUI from "react-devtools-core/standalone";
|
|
|
|
// See the full list of API methods in documentation below.
|
|
const { setContentDOMNode, startServer } = DevtoolsUI;
|
|
|
|
// Render DevTools UI into a DOM element.
|
|
setContentDOMNode(document.getElementById("container"));
|
|
|
|
// Start socket server used to communicate between backend and frontend.
|
|
startServer(
|
|
// Port defaults to 8097
|
|
1234,
|
|
|
|
// Host defaults to "localhost"
|
|
"example.devserver.com",
|
|
|
|
// Optional config for secure socket (WSS).
|
|
{
|
|
key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
|
|
cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
|
|
}
|
|
);
|
|
```
|
|
|
|
### Exported methods
|
|
The `default` export is an object defining the methods described below.
|
|
|
|
These methods support chaining for convenience. For example:
|
|
```js
|
|
const DevtoolsUI = require("react-devtools-core/standalone");
|
|
DevtoolsUI.setContentDOMNode(element).startServer();
|
|
```
|
|
|
|
#### `connectToSocket(socket: WebSocket)`
|
|
> This is an advanced config function that is typically not used.
|
|
|
|
Custom `WebSocket` connection to use for communication between DevTools frontend and backend. Calling this method automatically initializes the DevTools UI (similar to calling `startServer()`).
|
|
|
|
#### `openProfiler()`
|
|
Automatically select the "Profiler" tab in the DevTools UI.
|
|
|
|
#### `setContentDOMNode(element: HTMLElement)`
|
|
Set the DOM element DevTools UI should be rendered into on initialization.
|
|
|
|
#### `setDisconnectedCallback(callback: Function)`
|
|
_Optional_ callback to be notified when DevTools `WebSocket` closes (or errors).
|
|
|
|
#### `setProjectRoots(roots: Array<string>)`
|
|
_Optional_ set of root directories for source files. These roots can be used to open an inspected component's source code using an IDE.
|
|
|
|
#### `setStatusListener(callback: Function)`
|
|
_Optional_ callback to be notified of socket server events (e.g. initialized, errored, connected).
|
|
|
|
This callback receives two parameters:
|
|
```js
|
|
function onStatus(
|
|
message: string,
|
|
status: 'server-connected' | 'devtools-connected' | 'error'
|
|
): void {
|
|
// ...
|
|
}
|
|
```
|
|
|
|
#### `startServer(port?: number, host?: string, httpsOptions?: Object, loggerOptions?: Object)`
|
|
Start a socket server (used to communicate between backend and frontend) and renders the DevTools UI.
|
|
|
|
This method accepts the following parameters:
|
|
| Name | Default | Description |
|
|
|---|---|---|
|
|
| `port` | `8097` | Socket connection to backend should use this port. |
|
|
| `host` | `"localhost"` | Socket connection to backend should use this host. |
|
|
| `httpsOptions` | | _Optional_ object defining `key` and `cert` strings. |
|
|
| `loggerOptions` | | _Optional_ object defining a `surface` string (to be included with DevTools logging events). |
|
|
|
|
# Development
|
|
|
|
Watch for changes made to the backend entry point and rebuild:
|
|
```sh
|
|
yarn start:backend
|
|
```
|
|
|
|
Watch for changes made to the standalone UI entry point and rebuild:
|
|
```sh
|
|
yarn start:standalone
|
|
```
|
|
|
|
Run the standalone UI using `yarn start` in the [`react-devtools`](https://github.com/facebook/react/tree/main/packages/react-devtools).
|