"Fossies" - the Fresh Open Source Software Archive

Member "react-16.12.0/packages/react-devtools-inline/README.md" (12 Nov 2019, 5842 Bytes) of package /linux/www/react-16.12.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "README.md": 16.10.2_vs_16.11.0.

react-devtools-inline

React DevTools implementation for embedding within a browser-based IDE (e.g. CodeSandbox, StackBlitz).

This is a low-level package. If you’re looking for the standalone DevTools app, use the react-devtools package instead.

Usage

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

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:

  1. Frontend (DevTools interface) initialized in the main window.
  2. Backend initialized in an iframe.
  3. Backend activated.

1 Sandboxed iframes are supported.

API

react-devtools-inline/backend

import { activate, initialize } from 'react-devtools-inline/backend';

// This should be the iframe the React application is running in.
const iframe = document.getElementById(frameID);
const contentWindow = iframe.contentWindow;

// Call this before importing React (or any other packages that might import React).
initialize(contentWindow);

// Initialize the frontend...

// Call this only once the frontend has been initialized.
activate(contentWindow);

2 The backend must be initialized before React is loaded. (This means before any import or require statements or <script> tags that include React.)

react-devtools-inline/frontend

import { initialize } from 'react-devtools-inline/frontend';

// This should be the iframe the backend hook has been installed in.
const iframe = document.getElementById(frameID);
const contentWindow = iframe.contentWindow;

// This returns a React component that can be rendered into your app.
// <DevTools {...props} />
const DevTools = initialize(contentWindow);

3 Because the DevTools interface makes use of several new React APIs (e.g. suspense, concurrent mode) it should be rendered using either ReactDOM.createRoot or ReactDOM.createSyncRoot. It should not be rendered with ReactDOM.render.

Examples

Configuring a same-origin iframe

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.

import {
  activate as activateBackend,
  initialize as initializeBackend
} from 'react-devtools-inline/backend';
import { initialize as initializeFrontend } from 'react-devtools-inline/frontend';

// The React app you want to inspect with DevTools is running within this iframe:
const iframe = document.getElementById('target');
const { contentWindow } = iframe;

// Installs the global hook into the iframe.
// This must be called before React is loaded into that frame.
initializeBackend(contentWindow);

// React application can be injected into <iframe> at any time now...
// Note that this would need to be done via <script> tag injection,
// as setting the src of the <iframe> would load a new page (withou the injected backend).

// Initialize DevTools UI to listen to the hook we just installed.
// This returns a React component we can render anywhere in the parent window.
const DevTools = initializeFrontend(contentWindow);

// <DevTools /> interface can be rendered in the parent window at any time now...
// Be sure to use either ReactDOM.createRoot()
// or ReactDOM.createSyncRoot() to render this component.

// Let the backend know the frontend is ready and listening.
activateBackend(contentWindow);

Configuring a sandboxed iframe

Sandboxed iframes are also supported but require more complex initialization.

iframe.html

import { activate, initialize } from "react-devtools-inline/backend";

// The DevTooks hook needs to be installed before React is even required!
// The safest way to do this is probably to install it in a separate script tag.
initialize(window);

// Wait for the frontend to let us know that it's ready.
function onMessage({ data }) {
  switch (data.type) {
    case "activate-backend":
      window.removeEventListener("message", onMessage);

      activate(window);
      break;
    default:
      break;
  }
}

window.addEventListener("message", onMessage);

main-window.html

import { initialize } from "react-devtools-inline/frontend";

const iframe = document.getElementById("target");
const { contentWindow } = iframe;

// Initialize DevTools UI to listen to the iframe.
// This returns a React component we can render anywhere in the main window.
// Be sure to use either ReactDOM.createRoot()
// or ReactDOM.createSyncRoot() to render this component.
const DevTools = initialize(contentWindow);

// Let the backend know to initialize itself.
// We can't do this directly because the iframe is sandboxed.
// Only initialize the backend once the DevTools frontend has been initialized.
iframe.onload = () => {
  contentWindow.postMessage(
    {
      type: "activate-backend"
    },
    "*"
  );
};

Development

Watch for changes made to the source code and rebuild:

yarn start