react-devtools-core

What is react-devtools-core?

The react-devtools-core package provides the core functionality of React Developer Tools, which are used to inspect and debug React component hierarchies in the Chrome Developer Tools. It can be integrated into other environments, such as custom browsers, editors, or embedded inside apps.

What are react-devtools-core's main functionalities?

Standalone React DevTools

This code snippet demonstrates how to connect to the React DevTools from a standalone environment. It is useful when you want to debug React components within an environment that is not a web browser.

const { connectToDevTools } = require('react-devtools-core');
connectToDevTools({ host: 'localhost', port: 8097 });

Custom Integration

This code snippet shows how to start a React DevTools server. This can be used to integrate React DevTools into an environment where you have control over the server, such as an Electron app or a custom browser.

const { Server } = require('react-devtools-core');
const server = new Server({ port: 8097 });
server.on('ready', () => console.log('DevTools server started on port 8097.'));
server.start();

Other packages similar to react-devtools-core

redux-devtools-extension

This package provides tools for debugging application's state changes. While react-devtools-core is focused on React component hierarchies, redux-devtools-extension is focused on Redux state management.

mobx-react-devtools

Similar to react-devtools-core, this package is used for debugging React applications. However, it is specifically tailored for applications using MobX for state management, as opposed to React's context or Redux.

vue-devtools

Vue Devtools is for Vue.js applications what react-devtools-core is for React applications. It allows developers to inspect and debug Vue component hierarchies.

README

react-devtools-core

This package provides low-level APIs to support renderers like React Native. If you're looking for the standalone React DevTools UI, we suggest using 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 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:

if (process.env.NODE_ENV !== 'production') {
  const { connectToDevTools } = require("react-devtools-core");

  // 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).

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.

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.

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 which wraps DevTools in an Electron app.

Example

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:

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:

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:

yarn start:backend

Watch for changes made to the standalone UI entry point and rebuild:

yarn start:standalone

Run the standalone UI using yarn start in the react-devtools.

Changelog

15.2.0 (July 1, 2016)

React

• Add error codes to production invariants, with links to the view the full error text. (@keyanzhang in #6948)
• Include component stack information in PropType validation warnings. (@troydemonbreun in #6398, @sophiebits in #6771)
• Include component stack information in key warnings. (@keyanzhang in #6799)
• Stop validating props at mount time, only validate at element creation. (@keyanzhang in #6824)
• New invariant providing actionable error in missing instance case. (@yungsters in #6990)
• Add React.PropTypes.symbol to support ES2015 Symbols as props. (@puradox in #6377)
• Fix incorrect coercion of ref or key that are undefined in development (@gaearon in #6880)
• Fix a false positive when passing other element’s props to cloneElement (@ericmatthys in #6268)
• Warn if you attempt to define childContextTypes on a functional component (@Aweary in #6933)

React DOM

• Add warning for unknown properties on DOM elements. (@jimfb in #6800, @gm758 in #7152)
• Properly remove attributes from custom elements. (@grassator in #6748)
• Fix invalid unicode escape in attribute name regular expression. (@nbjahan in #6772)
• Add onLoad handling to <link> element. (@roderickhsiao in #6815)
• Add onError handling to <source> element. (@wadahiro in #6941)
• Handle value and defaultValue more accurately in the DOM. (@jimfb in #6406)
• Fix events issue in environments with mutated Object.prototype. (@Weizenlol in #6886)
• Fix issue where is="null" ended up in the DOM in Firefox. (@darobin in #6896)
• Improved performance of text escaping by using escape-html. (@aickin in #6862)
• Fix issue with dangerouslySetInnerHTML and SVG in Internet Explorer. (@joshhunt in #6982)
• Fix issue with <textarea> placeholders. (@jimfb in #7002)
• Fix controlled vs uncontrolled detection of <input type="radio"/>. (@jimfb in #7003)
• Improve performance of updating text content. (@trueadm in #7005)
• Ensure controlled <select> components behave the same on initial render as they do on updates. (@yiminghe in #5362)

React Perf Add-on

• Add isRunning() API. (@nfcampos in #6763)
• Improve accuracy of lifecycle hook timing. (@gaearon in #6858)
• Fix internal errors when using ReactPerf with portal components. (@gaearon in #6860)
• Fix performance regression. (@sophiebits in #6770)
• Add warning that ReactPerf is not enabled in production. (@sashashakun in #6884)

React CSSTransitionGroup Add-on

• Fix timing issue with null node. (@keyanzhang in #6958)

React Native Renderer

• Dependencies on React Native modules use CommonJS requires instead of providesModule. (@davidaurelio in #6715)