diff --git a/.eslintignore b/.eslintignore index 5e4165322a..7f1c5b3bd4 100644 --- a/.eslintignore +++ b/.eslintignore @@ -5,6 +5,7 @@ shells/browser/firefox/build shells/browser/shared/build shells/dev/dist packages/react-devtools-core/dist +packages/react-devtools-inline/dist vendor *.js.snap diff --git a/.gitignore b/.gitignore index 738522e01f..8ec77912d2 100644 --- a/.gitignore +++ b/.gitignore @@ -4,11 +4,13 @@ /shells/browser/firefox/*.pem /shells/browser/shared/build /packages/react-devtools-core/dist +/packages/react-devtools-inline/dist /shells/dev/dist build /node_modules -/packages/react-devtools-core/node_modules/ -/packages/react-devtools/node_modules/ +/packages/react-devtools-core/node_modules +/packages/react-devtools-inline/node_modules +/packages/react-devtools/node_modules npm-debug.log yarn-error.log .DS_Store diff --git a/package.json b/package.json index cdfd58da14..1540785118 100644 --- a/package.json +++ b/package.json @@ -34,6 +34,8 @@ "scripts": { "build:core:backend": "cd ./packages/react-devtools-core && yarn build:backend", "build:core:standalone": "cd ./packages/react-devtools-core && yarn build:standalone", + "build:core": "cd ./packages/react-devtools-core && yarn build", + "build:inline": "cd ./packages/react-devtools-inline && yarn build", "build:demo": "cd ./shells/dev && cross-env NODE_ENV=development cross-env TARGET=remote webpack --config webpack.config.js", "build:extension": "cross-env NODE_ENV=production yarn run build:extension:chrome && yarn run build:extension:firefox", "build:extension:dev": "cross-env NODE_ENV=development yarn run build:extension:chrome && yarn run build:extension:firefox", diff --git a/packages/react-devtools-core/package.json b/packages/react-devtools-core/package.json index c6ab52f812..035564a20a 100644 --- a/packages/react-devtools-core/package.json +++ b/packages/react-devtools-core/package.json @@ -1,6 +1,6 @@ { "name": "react-devtools-core", - "version": "4.0.0-alpha.6", + "version": "4.0.0-alpha.7", "description": "Use react-devtools outside of the browser", "license": "MIT", "main": "./dist/backend.js", diff --git a/packages/react-devtools-inline/README.md b/packages/react-devtools-inline/README.md new file mode 100644 index 0000000000..c678f2c5f0 --- /dev/null +++ b/packages/react-devtools-inline/README.md @@ -0,0 +1,134 @@ +# `react-devtools-inline` + +React DevTools implementation for embedding within a browser-based IDE (e.g. [CodeSandbox](https://codesandbox.io/), [StackBlitz](https://stackblitz.com/)). + +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 `iframe`1). + +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`. +1. Backend initialized in an `iframe`. +1. Backend activated. + +1 Sandboxed iframes are supported. + +## API + +### `react-devtools-inline/backend` + +* **`initialize(contentWindow)`** - +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!) +* **`activate(contentWindow)`** - +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. + +```js +import { activate, initialize } from 'react-devtools-inline/backend'; + +// Call this before importing React (or any other packages that might import React). +initialize(); + +// Call this only once the frontend has been initialized. +activate(); +``` + +### `react-devtools-inline/frontend` + +* **`initialize(contentWindow)`** - +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. + +```js +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. +// +const DevTools = initialize(contentWindow); +``` + +## 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. + +```js +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 be called before React is loaded into that frame. +initializeBackend(contentWindow); + +// React application can be injected into