DevTools: Support mulitple DevTools instances per page (#22949)

This is being done so that we can embed DevTools within the new React (beta) docs.

The primary changes here are to `react-devtools-inline/backend`:
* Add a new `createBridge` API
* Add an option to the `activate` method to support passing in the custom bridge object.

The `react-devtools-inline` README has been updated to include these new methods.

To verify these changes, this commit also updates the test shell to add a new entry-point for multiple DevTools.

This commit also replaces two direct calls to `window.postMessage()` with `bridge.send()` (and adds the related Flow types).

packages/react-devtools-inline/README.md

@@ -56,7 +56,7 @@ const iframe = document.getElementById(frameID);
 const contentWindow = iframe.contentWindow;
 
 // This returns a React component that can be rendered into your app.
-// <DevTools {...props} />
+// e.g. render(<DevTools {...props} />);
 const DevTools = initialize(contentWindow);
 ```
 
@@ -177,32 +177,47 @@ Below is an example of an advanced integration with a website like [Replay.io](h
 
 ```js
 import {
-  createBridge,
+  activate as activateBackend,
+  createBridge as createBackendBridge,
+  initialize as initializeBackend,
+} from 'react-devtools-inline/backend';
+import {
+  createBridge as createFrontendBridge,
   createStore,
   initialize as createDevTools,
-} from "react-devtools-inline/frontend";
+} from 'react-devtools-inline/frontend';
 
-// Custom Wall implementation enables serializing data
-// using an API other than window.postMessage()
+// DevTools uses "message" events and window.postMessage() by default,
+// but we can override this behavior by creating a custom "Wall" object.
 // For example...
 const wall = {
-  emit() {},
+  _listeners: [],
   listen(listener) {
-    wall._listener = listener;
+    wall._listeners.push(listener);
   },
-  async send(event, payload) {
-    const response = await fetch(...).json();
-    wall._listener(response);
+  send(event, payload) {
+    wall._listeners.forEach(listener => listener({event, payload}));
   },
 };
 
-// Create a Bridge and Store that use the custom Wall.
+// Initialize the DevTools backend before importing React (or any other packages that might import React).
+initializeBackend(contentWindow);
+
+// Prepare DevTools for rendering.
+// To use the custom Wall we've created, we need to also create our own "Bridge" and "Store" objects.
 const bridge = createBridge(target, wall);
 const store = createStore(bridge);
 const DevTools = createDevTools(target, { bridge, store });
 
-// Render DevTools with it.
-<DevTools {...otherProps} />;
+// You can render DevTools now:
+const root = createRoot(container);
+root.render(<DevTools {...otherProps} />);
+
+// Lastly, let the DevTools backend know that the frontend is ready.
+// To use the custom Wall we've created, we need to also pass in the "Bridge".
+activateBackend(contentWindow, {
+  bridge: createBackendBridge(contentWindow, wall),
+});
 ```
 
 ## Local development

packages/react-devtools-inline/src/backend.js

@@ -5,83 +5,57 @@ import Bridge from 'react-devtools-shared/src/bridge';
 import {initBackend} from 'react-devtools-shared/src/backend';
 import {installHook} from 'react-devtools-shared/src/hook';
 import setupNativeStyleEditor from 'react-devtools-shared/src/backend/NativeStyleEditor/setupNativeStyleEditor';
-import {
-  MESSAGE_TYPE_GET_SAVED_PREFERENCES,
-  MESSAGE_TYPE_SAVED_PREFERENCES,
-} from './constants';
 
-function startActivation(contentWindow: window) {
-  const {parent} = contentWindow;
-
-  const onMessage = ({data}) => {
-    switch (data.type) {
-      case MESSAGE_TYPE_SAVED_PREFERENCES:
-        // This is the only message we're listening for,
-        // so it's safe to cleanup after we've received it.
-        contentWindow.removeEventListener('message', onMessage);
-
-        const {
-          appendComponentStack,
-          breakOnConsoleErrors,
-          componentFilters,
-          showInlineWarningsAndErrors,
-          hideConsoleLogsInStrictMode,
-        } = data;
-
-        contentWindow.__REACT_DEVTOOLS_APPEND_COMPONENT_STACK__ = appendComponentStack;
-        contentWindow.__REACT_DEVTOOLS_BREAK_ON_CONSOLE_ERRORS__ = breakOnConsoleErrors;
-        contentWindow.__REACT_DEVTOOLS_COMPONENT_FILTERS__ = componentFilters;
-        contentWindow.__REACT_DEVTOOLS_SHOW_INLINE_WARNINGS_AND_ERRORS__ = showInlineWarningsAndErrors;
-        contentWindow.__REACT_DEVTOOLS_HIDE_CONSOLE_LOGS_IN_STRICT_MODE__ = hideConsoleLogsInStrictMode;
-
-        // TRICKY
-        // The backend entry point may be required in the context of an iframe or the parent window.
-        // If it's required within the parent window, store the saved values on it as well,
-        // since the injected renderer interface will read from window.
-        // Technically we don't need to store them on the contentWindow in this case,
-        // but it doesn't really hurt anything to store them there too.
-        if (contentWindow !== window) {
-          window.__REACT_DEVTOOLS_APPEND_COMPONENT_STACK__ = appendComponentStack;
-          window.__REACT_DEVTOOLS_BREAK_ON_CONSOLE_ERRORS__ = breakOnConsoleErrors;
-          window.__REACT_DEVTOOLS_COMPONENT_FILTERS__ = componentFilters;
-          window.__REACT_DEVTOOLS_SHOW_INLINE_WARNINGS_AND_ERRORS__ = showInlineWarningsAndErrors;
-          window.__REACT_DEVTOOLS_HIDE_CONSOLE_LOGS_IN_STRICT_MODE__ = hideConsoleLogsInStrictMode;
-        }
-
-        finishActivation(contentWindow);
-        break;
-      default:
-        break;
+import type {BackendBridge} from 'react-devtools-shared/src/bridge';
+import type {Wall} from 'react-devtools-shared/src/types';
+
+function startActivation(contentWindow: window, bridge: BackendBridge) {
+  const onSavedPreferences = data => {
+    // This is the only message we're listening for,
+    // so it's safe to cleanup after we've received it.
+    bridge.removeListener('savedPreferences', onSavedPreferences);
+
+    const {
+      appendComponentStack,
+      breakOnConsoleErrors,
+      componentFilters,
+      showInlineWarningsAndErrors,
+      hideConsoleLogsInStrictMode,
+    } = data;
+
+    contentWindow.__REACT_DEVTOOLS_APPEND_COMPONENT_STACK__ = appendComponentStack;
+    contentWindow.__REACT_DEVTOOLS_BREAK_ON_CONSOLE_ERRORS__ = breakOnConsoleErrors;
+    contentWindow.__REACT_DEVTOOLS_COMPONENT_FILTERS__ = componentFilters;
+    contentWindow.__REACT_DEVTOOLS_SHOW_INLINE_WARNINGS_AND_ERRORS__ = showInlineWarningsAndErrors;
+    contentWindow.__REACT_DEVTOOLS_HIDE_CONSOLE_LOGS_IN_STRICT_MODE__ = hideConsoleLogsInStrictMode;
+
+    // TRICKY
+    // The backend entry point may be required in the context of an iframe or the parent window.
+    // If it's required within the parent window, store the saved values on it as well,
+    // since the injected renderer interface will read from window.
+    // Technically we don't need to store them on the contentWindow in this case,
+    // but it doesn't really hurt anything to store them there too.
+    if (contentWindow !== window) {
+      window.__REACT_DEVTOOLS_APPEND_COMPONENT_STACK__ = appendComponentStack;
+      window.__REACT_DEVTOOLS_BREAK_ON_CONSOLE_ERRORS__ = breakOnConsoleErrors;
+      window.__REACT_DEVTOOLS_COMPONENT_FILTERS__ = componentFilters;
+      window.__REACT_DEVTOOLS_SHOW_INLINE_WARNINGS_AND_ERRORS__ = showInlineWarningsAndErrors;
+      window.__REACT_DEVTOOLS_HIDE_CONSOLE_LOGS_IN_STRICT_MODE__ = hideConsoleLogsInStrictMode;
     }
+
+    finishActivation(contentWindow, bridge);
   };
 
-  contentWindow.addEventListener('message', onMessage);
+  bridge.addListener('savedPreferences', onSavedPreferences);
 
   // The backend may be unable to read saved preferences directly,
   // because they are stored in localStorage within the context of the extension (on the frontend).
   // Instead it relies on the extension to pass preferences through.
   // Because we might be in a sandboxed iframe, we have to ask for them by way of postMessage().
-  parent.postMessage({type: MESSAGE_TYPE_GET_SAVED_PREFERENCES}, '*');
+  bridge.send('getSavedPreferences');
 }
 
-function finishActivation(contentWindow: window) {
-  const {parent} = contentWindow;
-
-  const bridge = new Bridge({
-    listen(fn) {
-      const onMessage = event => {
-        fn(event.data);
-      };
-      contentWindow.addEventListener('message', onMessage);
-      return () => {
-        contentWindow.removeEventListener('message', onMessage);
-      };
-    },
-    send(event: string, payload: any, transferable?: Array<any>) {
-      parent.postMessage({event, payload}, '*', transferable);
-    },
-  });
-
+function finishActivation(contentWindow: window, bridge: BackendBridge) {
   const agent = new Agent(bridge);
 
   const hook = contentWindow.__REACT_DEVTOOLS_GLOBAL_HOOK__;
@@ -100,8 +74,45 @@ function finishActivation(contentWindow: window) {
   }
 }
 
-export function activate(contentWindow: window): void {
-  startActivation(contentWindow);
+export function activate(
+  contentWindow: window,
+  {
+    bridge,
+  }: {|
+    bridge?: BackendBridge,
+  |} = {},
+): void {
+  if (bridge == null) {
+    bridge = createBridge(contentWindow);
+  }
+
+  startActivation(contentWindow, bridge);
+}
+
+export function createBridge(
+  contentWindow: window,
+  wall?: Wall,
+): BackendBridge {
+  const {parent} = contentWindow;
+
+  if (wall == null) {
+    wall = {
+      listen(fn) {
+        const onMessage = ({data}) => {
+          fn(data);
+        };
+        contentWindow.addEventListener('message', onMessage);
+        return () => {
+          contentWindow.removeEventListener('message', onMessage);
+        };
+      },
+      send(event: string, payload: any, transferable?: Array<any>) {
+        parent.postMessage({event, payload}, '*', transferable);
+      },
+    };
+  }
+
+  return (new Bridge(wall): BackendBridge);
 }
 
 export function initialize(contentWindow: window): void {

packages/react-devtools-inline/src/frontend.js

@@ -12,10 +12,6 @@ import {
   getShowInlineWarningsAndErrors,
   getHideConsoleLogsInStrictMode,
 } from 'react-devtools-shared/src/utils';
-import {
-  MESSAGE_TYPE_GET_SAVED_PREFERENCES,
-  MESSAGE_TYPE_SAVED_PREFERENCES,
-} from './constants';
 
 import type {Wall} from 'react-devtools-shared/src/types';
 import type {FrontendBridge} from 'react-devtools-shared/src/bridge';
@@ -68,49 +64,40 @@ export function initialize(
     store?: Store,
   |} = {},
 ): React.AbstractComponent<Props, mixed> {
-  const onGetSavedPreferencesMessage = ({data, source}) => {
-    if (source === 'react-devtools-content-script') {
-      // Ignore messages from the DevTools browser extension.
-    }
-
-    switch (data.type) {
-      case MESSAGE_TYPE_GET_SAVED_PREFERENCES:
-        // This is the only message we're listening for,
-        // so it's safe to cleanup after we've received it.
-        window.removeEventListener('message', onGetSavedPreferencesMessage);
-
-        // The renderer interface can't read saved preferences directly,
-        // because they are stored in localStorage within the context of the extension.
-        // Instead it relies on the extension to pass them through.
-        contentWindow.postMessage(
-          {
-            type: MESSAGE_TYPE_SAVED_PREFERENCES,
-            appendComponentStack: getAppendComponentStack(),
-            breakOnConsoleErrors: getBreakOnConsoleErrors(),
-            componentFilters: getSavedComponentFilters(),
-            showInlineWarningsAndErrors: getShowInlineWarningsAndErrors(),
-            hideConsoleLogsInStrictMode: getHideConsoleLogsInStrictMode(),
-          },
-          '*',
-        );
-        break;
-      default:
-        break;
-    }
-  };
-
-  window.addEventListener('message', onGetSavedPreferencesMessage);
-
   if (bridge == null) {
     bridge = createBridge(contentWindow);
   }
 
+  // Type refinement.
+  const frontendBridge = ((bridge: any): FrontendBridge);
+
   if (store == null) {
-    store = createStore(bridge);
+    store = createStore(frontendBridge);
   }
 
+  const onGetSavedPreferences = () => {
+    // This is the only message we're listening for,
+    // so it's safe to cleanup after we've received it.
+    frontendBridge.removeListener('getSavedPreferences', onGetSavedPreferences);
+
+    const data = {
+      appendComponentStack: getAppendComponentStack(),
+      breakOnConsoleErrors: getBreakOnConsoleErrors(),
+      componentFilters: getSavedComponentFilters(),
+      showInlineWarningsAndErrors: getShowInlineWarningsAndErrors(),
+      hideConsoleLogsInStrictMode: getHideConsoleLogsInStrictMode(),
+    };
+
+    // The renderer interface can't read saved preferences directly,
+    // because they are stored in localStorage within the context of the extension.
+    // Instead it relies on the extension to pass them through.
+    frontendBridge.send('savedPreferences', data);
+  };
+
+  frontendBridge.addListener('getSavedPreferences', onGetSavedPreferences);
+
   const ForwardRef = forwardRef<Props, mixed>((props, ref) => (
-    <DevTools ref={ref} bridge={bridge} store={store} {...props} />
+    <DevTools ref={ref} bridge={frontendBridge} store={store} {...props} />
   ));
   ForwardRef.displayName = 'DevTools';
 

packages/react-devtools-shared/src/backend/agent.js

@@ -225,6 +225,9 @@ export default class Agent extends EventEmitter<{|
       bridge.send('profilingStatus', true);
     }
 
+    // Send the Bridge protocol after initialization in case the frontend has already requested it.
+    this._bridge.send('bridgeProtocol', currentBridgeProtocol);
+
     // Notify the frontend if the backend supports the Storage API (e.g. localStorage).
     // If not, features like reload-and-profile will not work correctly and must be disabled.
     let isBackendStorageAPISupported = false;

packages/react-devtools-shared/src/bridge.js

@@ -176,10 +176,19 @@ type UpdateConsolePatchSettingsParams = {|
   browserTheme: BrowserTheme,
 |};
 
+type SavedPreferencesParams = {|
+  appendComponentStack: boolean,
+  breakOnConsoleErrors: boolean,
+  componentFilters: Array<ComponentFilter>,
+  showInlineWarningsAndErrors: boolean,
+  hideConsoleLogsInStrictMode: boolean,
+|};
+
 export type BackendEvents = {|
   bridgeProtocol: [BridgeProtocol],
   extensionBackendInitialized: [],
   fastRefreshScheduled: [],
+  getSavedPreferences: [],
   inspectedElement: [InspectedElementPayload],
   isBackendStorageAPISupported: [boolean],
   isSynchronousXHRSupported: [boolean],
@@ -223,6 +232,7 @@ type FrontendEvents = {|
   profilingData: [ProfilingDataBackend],
   reloadAndProfile: [boolean],
   renamePath: [RenamePath],
+  savedPreferences: [SavedPreferencesParams],
   selectFiber: [number],
   setTraceUpdatesEnabled: [boolean],
   shutdown: [],
@@ -277,7 +287,9 @@ class Bridge<
 
     this._wallUnlisten =
       wall.listen((message: Message) => {
-        (this: any).emit(message.event, message.payload);
+        if (message && message.event) {
+          (this: any).emit(message.event, message.payload);
+        }
       }) || null;
 
     // Temporarily support older standalone front-ends sending commands to newer embedded backends.

packages/react-devtools-shell/index.html → packages/react-devtools-shell/app.html

@@ -64,6 +64,6 @@
     <!-- This script installs the hook, injects the backend, and renders the DevTools UI -->
     <!-- In DEV mode, this file is served by the Webpack dev server -->
     <!-- For production builds, it's built by Webpack and uploaded from the local file system -->
-    <script src="dist/devtools.js"></script>
+    <script src="dist/app-devtools.js"></script>
   </body>
 </html>