Update README.md

gaearon · gaearon · commit 81cea2be59ae · 2015-12-14T04:03:54.000Z
diff --git a/README.md b/README.md
@@ -19,89 +19,164 @@ A live-editing time travel environment for [Redux](https://github.com/rackt/redu
 * If the reducers throw, you will see during which action this happened, and what the error was
 * With `persistState()` store enhancer, you can persist debug sessions across page reloads
 
+### Overview
+
+Redux DevTools is a development time package that provides power-ups for your Redux development workflow. Be careful to strip its code in production! To use Redux DevTools, you need to choose a “monitor”—a React component that will serve as a UI for the DevTools. Different tasks and workflows require different UIs, so Redux DevTools is built to be flexible in this regard. We recommend using [`LogMonitor`](https://github.com/gaearon/redux-devtools-log-monitor) for inspecting the state and time travel, and wrap it in a [`DockMonitor`](https://github.com/gaearon/redux-devtools-dock-monitor) to quckly move it across the screen. That said, when you’re comfortable rolling up your own setup, feel free to do this, and share it with us.
+
 ### Installation
 
 ```
 npm install --save-dev redux-devtools
 ```
 
-DevTools is a [store enhancer](http://rackt.github.io/redux/docs/Glossary.html#store-enhancer), which should be added to your middleware stack *after* [`applyMiddleware`](http://rackt.github.io/redux/docs/api/applyMiddleware.html) as `applyMiddleware` is potentially asynchronous. Otherwise, DevTools won’t see the raw actions emitted by asynchronous middleware such as [redux-promise](https://github.com/acdlite/redux-promise) or [redux-thunk](https://github.com/gaearon/redux-thunk).
+You’ll also likely want to install some monitors:
+
+```
+npm install --save-dev redux-devtools-log-monitor
+npm install --save-dev redux-devtools-dock-monitor
+```
+
+### Usage
+
+#### Create a `DevTools` Component
 
-To use, first create a `DevTools` component by passing a `monitor` component to `createDevTools`. In the following example our `monitor` consists of [`redux-devtools-log-monitor`](https://github.com/gaearon/redux-devtools-log-monitor) docked within [`redux-devtools-dock-monitor`](https://github.com/gaearon/redux-devtools-dock-monitor):
+Somewhere in your project, create a `DevTools` component by passing a `monitor` element to `createDevTools`. In the following example our `monitor` consists of [`LogMonitor`](https://github.com/gaearon/redux-devtools-log-monitor) docked within [`DockMonitor`](https://github.com/gaearon/redux-devtools-dock-monitor):
 
-####containers/DevTools.js
+##### `containers/DevTools.js`
 
 ```js
 import React from 'react';
 
-// createDevTools takes a monitor and produces a DevTools component
+// Exported from redux-devtools
 import { createDevTools } from 'redux-devtools';
 
-// Monitor component for Redux DevTools
+// Monitors are separate packages, and you can make a custom one
 import LogMonitor from 'redux-devtools-log-monitor';
-
-// Dock component to contain a Redux DevTools monitor
 import DockMonitor from 'redux-devtools-dock-monitor';
 
-export default createDevTools(
-  <DockMonitor toggleVisibilityKey='H'
-               changePositionKey='Q'>
-    <LogMonitor />
+// createDevTools takes a monitor and produces a DevTools component
+const DevTools = createDevTools(
+  // Monitors are individually adjustable with props
+  // Consult their repositories to learn about those props
+  <DockMonitor toggleVisibilityKey='ctrl-h'
+               changePositionKey='ctrl-q'>
+    <LogMonitor theme='tomorrow' />
   </DockMonitor>
 );
+
+export default DevTools;
+```
+
+Note that you can use `LogMonitor` directly without wrapping it in `DockMonitor` if you’d like to display the DevTools UI somewhere right inside your application:
+
+```js
+// If you'd rather not use docking UI, use <LogMonitor> directly
+const DevTools = createDevTools(
+  <LogMonitor theme='solarized' />
+);
 ```
 
-Note that it is not essential to put [`redux-devtools-log-monitor`](https://github.com/gaearon/redux-devtools-log-monitor) inside the dock component, it can be placed wherever you like in the component tree.
+#### Use `DevTools.instrument()` Store Enhancer
+
+The `DevTools` component you created with `createDevTools()` has a special static method called `instrument()`. It returns a [store enhancer](http://rackt.github.io/redux/docs/Glossary.html#store-enhancer) that you need to use in development.
+
+A store enhancer is a function that takes `createStore` and returns an enhanced version of it that you will use instead. You probably already used another store enhancer—[`applyMiddleware()`](http://redux.js.org/docs/api/applyMiddleware.html). Unlike `applyMiddleware()`, you will need to be careful to only use `DevTools.instrument()` in development environment, and never in production.
+
+The easiest way to apply several store enhancers in a row is to use the [`compose()`](http://redux.js.org/docs/api/compose.html) utility function that ships with Redux. It is the same `compose()` that you can find in Underscore and Lodash. In our case, we would use it to compose several store enhancers into one: `compose(applyMiddleware(m1, m2, m3), DevTools.instrument())`.
+
+It’s important that you should add `DevTools.instrument()` *after* `applyMiddleware` in your `compose()` function arguments. This is because `applyMiddleware` is potentially asynchronous, but `DevTools.instrument()` expects all actions to be plain objects rather than actions interpreted by asynchronous middleware such as [redux-promise](https://github.com/acdlite/redux-promise) or [redux-thunk](https://github.com/gaearon/redux-thunk). So make sure `applyMiddleware()` goes first in the `compose()` call, and `DevTools.instrument()` goes after it.
 
-Next add `instrument()` and (optionally) `persistState()` to your store enhancers, and create your store:
+If you’d like, you may add another store enhancer called `persistState()`. It ships with this package, and it lets you serialize whole sessions (including all dispatched actions and the state of the monitors) by a URL key. So if you visit `http://localhost:3000/?debug_session=reproducing_weird_bug`, do something in the app, then open `http://localhost:3000/?debug_session=some_other_feature`, and then go back to `http://localhost:3000/?debug_session=reproducing_weird_bug`, the state will be restored. The implementation of `persistState()` is fairly naïve but you can take it as an inspiration and build a proper UI for it if you feel like it!
+
+#### Exclude DevTools from Production Builds
+
+Finally, to make sure we’re not pulling any DevTools-related code in the production builds, we will envify our code. With Webpack, you can use `DefinePlugin` (Browserify equivalent is called [`envify`](https://github.com/zertosh/loose-envify)) to turn magic constants like `process.env.NODE_ENV` into `'production'` or `'development'` strings depending on the environment, and import and render `redux-devtools` conditionally when `process.env.NODE_ENV` is not `'production'`. Then, if you have an Uglify step before production, Uglify will eliminate dead `if (false)` branches with `redux-devtools` imports.
+
+If you are using ES6 modules with Webpack 1.x and Babel, you might try putting your `import` statement inside an `if (process.env.NODE_ENV !== 'production)` to exclude the DevTools package from your production bundle. However this ES6 specification forbids it, so this won’t compile. Instead, you can use a conditional CommonJS `require`. Babel will let it compile, and Uglify will eliminate the dead branches before Webpack creates a bundle. This is why we recommend creating a `configureStore.js` file that either directs you to `configureStore.dev.js` or `configureStore.prod.js` depending on the configuration. While it is a little bit more maintenance, the upside is that you can be sure you won’t pull any development dependencies into the production builds, and that you can easily enable different middleware (e.g. crash reporting, logging) in the production environment.
+
+##### `store/configureStore.js`
+
+```js
+// Use ProvidePlugin (Webpack) or loose-envify (Browserify)
+// together with Uglify to strip the dev branch in prod build.
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('./configureStore.prod');
+} else {
+  module.exports = require('./configureStore.dev');
+}
+```
+
+##### `store/configureStore.prod.js`
 
 ```js
+import { createStore, applyMiddleware, compose } from 'redux';
+import rootReducer from '../reducers';
+
+const finalCreateStore = compose(
+  // Middleware you want to use in production:
+  applyMiddleware(p1, p2, p3),
+  // Other store enhancers if you use any
+)(createStore);
 
-import { createStore, compose } from 'redux';
+export default function configureStore(initialState) {
+  return finalCreateStore(rootReducer, initialState);
+};
+```
+
+##### `store/configureStore.dev.js`
+
+```js
+import { createStore, applyMiddleware, compose } from 'redux';
 import { persistState } from 'redux-devtools';
 import rootReducer from '../reducers';
 import DevTools from '../containers/DevTools';
 
 const finalCreateStore = compose(
-  // Enables your middleware:
-  applyMiddleware(m1, m2, m3), // any Redux middleware, e.g. redux-thunk
-
-  // Provide support for DevTools
+  // Middleware you want to use in development:
+  applyMiddleware(d1, d2, d3),
+  // Required! Enable Redux DevTools with the monitors you chose
   DevTools.instrument(),
-
-  // Lets you write ?debug_session=<name> in address bar to persist debug sessions
-  persistState(
-    window.location.href.match(
-      /[?&]debug_session=([^&]+)\b/
-    )
-  )
+  // Optional. Lets you write ?debug_session=<key> in address bar to persist debug sessions
+  persistState(getDebugSessionKey())
 )(createStore);
 
+function getDebugSessionKey() {
+  // You can write custom logic here!
+  // By default we try to read the key from ?debug_session=<key> in the address bar
+  const matches = window.location.href.match(/[?&]debug_session=([^&]+)\b/);
+  return (matches && matches.length > 0)? matches[1] : null;
+}
+
 export default function configureStore(initialState) {
   const store = finalCreateStore(rootReducer, initialState);
 
-  // enable hot reloading for the store
+  // Hot reload reducers (requires Webpack or Browserify HMR to be enabled)
   if (module.hot) {
     module.hot.accept('../reducers', () =>
-      store.replaceReducer(require('../reducers'))
+      store.replaceReducer(require('../reducers')/*.default if you use Babel 6+ */)
     );
   }
 
   return store;
 }
 ```
 
-Finally, include the DevTools component in your page:
+#### Render `<DevTools>` in Your App
+
+Finally, include the `DevTools` component in your page.  
+A naïve way to do this would be to render it right in your `index.js`:
 
-####index.js
+##### `index.js`
 
 ```js
 import React from 'react';
 import { render } from 'react-dom';
 import { Provider } from 'react-redux';
 import configureStore from './store/configureStore';
-import TodoApp from './TodoApp';
-import DevTools from './DevTools';
+import TodoApp from './containers/TodoApp';
+
+// Don't do this! You’re bringing DevTools into the production bundle.
+import DevTools from './containers/DevTools';
 
 const store = configureStore();
 
@@ -116,13 +191,9 @@ render(
 );
 ```
 
-**Make sure to only use DevTools in development!** In production it will be terribly slow because currently actions just accumulate forever.
-
-In Webpack, you can use `DefinePlugin` to turn magic constants like `__DEV__` into `true` or `false` depending on the environment, and import and render `redux-devtools` conditionally behind `if (__DEV__)`. Then, if you have an Uglify step before production, Uglify will eliminate dead `if (false)` branches with `redux-devtools` imports.
-
-If you are using ES6 modules with Webpack 1.x, you might try putting your `import` statement inside an `if (__DEV__)` to exclude the DevTools package from your production bundle. This will not work. However, you can work around this by creating separate `dev` and `prod` Root components that are dynamically imported using commonJS `require`:
+We recommend a different approach. Create a `Root.js` component that renders the root of your application (usually some component surrounded by a `<Provider>`). Then use the same trick with conditional `require` statements to have two versions of it, one for development, and one for production:
 
-####containers/Root.js
+##### `containers/Root.js`
 
 ```js
 if (process.env.NODE_ENV === 'production') {
@@ -132,7 +203,7 @@ if (process.env.NODE_ENV === 'production') {
 }
 ```
 
-####Root.dev.js
+##### `containers/Root.dev.js`
 
 ```js
 import React, { Component } from 'react';
@@ -155,7 +226,7 @@ export default class Root extends Component {
 }
 ```
 
-####Root.prod.js
+##### `containers/Root.prod.js`
 
 ```js
 import React, { Component } from 'react';
@@ -174,6 +245,62 @@ export default class Root extends Component {
 }
 ```
 
+#### Adjusting the Appearance
+
+When you use [`DockMonitor`](https://github.com/gaearon/redux-devtools-dock-monitor), you usually want to render `<DevTools>` at the root of your app. It will appear in a docked container above it. However, you can also render it anywhere else in your React component tree. In this case, you’d create a development and a production version of some other component that would either include or exclude `<DevTools>`.
+
+For example (you don’t have to do that!), you may prefer to display the DevTools in a separate window instead of rendering it inside the page. In this case, you can remove `DockMonitor` from `DevTools.js` and just use the `LogMonitor`, and have some code like this:
+
+##### `index.js`
+
+```js
+import React from 'react';
+import { Provider } from 'react-redux';
+import { render } from 'react-dom';
+import configureStore from './store/configureStore';
+import App from './containers/App';
+
+const store = configureStore();
+
+render(
+  <Provider store={store}>
+    <App />
+  </Provider>,
+  document.getElementById('root')
+);
+
+if (process.env.NODE_ENV !== 'production') {
+  const showDevTools = require('./showDevTools');
+  showDevTools(store);
+}
+```
+
+##### `showDevTools.js`
+
+```js
+import React from 'react';
+import { render } from 'react-dom';
+import DevTools from './containers/DevTools';
+
+export default function showDevTools(store) {
+  const popup = window.open(null, 'Redux DevTools', 'menubar=no,location=no,resizable=yes,scrollbars=no,status=no');
+  // Reload in case it already exists
+  popup.location.reload();
+  
+  setTimeout(() => {
+    popup.document.write('<div id="react-devtools-root"></div>');
+    render(
+      <DevTools store={store} />,
+      popup.document.getElementById('react-devtools-root')
+    );
+  }, 10);
+}
+```
+
+Personal preferences vary, and whether to put the DevTools in a separate window, in a dock, or right inside you app’s user interface, is up to you. Make sure to check the documentation for the monitors you use and learn about the different props they support for customizing the appearance and the behavior.
+
+Note that there are no useful props you can pass to the `DevTools` component other than the `store`. The `store` prop is needed if you don’t wrap `<DevTools>` in a `<Provider>`—just like with any connected component. To adjust the monitors, you need to pass props to them inside `DevTools.js` itself inside the `createDevTools()` call when they are used.
+
 ### Running Examples
 
 You can do this:
@@ -183,7 +310,7 @@ git clone https://github.com/gaearon/redux-devtools.git
 cd redux-devtools
 npm install
 
-cd examples/counter
+cd examples/counter # or examples/todomvc
 npm install
 npm start
 open http://localhost:3000
@@ -192,8 +319,6 @@ open http://localhost:3000
 Try clicking on actions in the log, or changing some code inside `examples/counter/reducers/counter`.  
 For fun, you can also open `http://localhost:3000/?debug_session=123`, click around, and then refresh.
 
-Oh, and you can do the same with the TodoMVC example as well.
-
 ### Custom Monitors
 
 **DevTools accepts monitor components so you can build a completely custom UI.** [`redux-devtools-log-monitor`](https://github.com/gaearon/redux-devtools-log-monitor) and [`redux-devtools-dock-monitor`](https://github.com/gaearon/redux-devtools-dock-monitor) are just examples of what is possible.
@@ -205,7 +330,7 @@ Some crazy ideas for custom monitors:
 * A slider that lets you jump between computed states just by dragging it
 * An in-app layer that shows the last N states right in the app (e.g. for animation)
 * A time machine like interface where the last N states of your app reside on different Z layers
-* Feel free to come up with and implement your own! Check [`redux-devtools-log-monitor`](https://github.com/gaearon/redux-devtools-log-monitor) propTypes to see what you can do.
+* Feel free to come up with and implement your own! Check [`LogMonitor`](https://github.com/gaearon/redux-devtools-log-monitor) propTypes to see what you can do.
 
 In fact some of these are implemented already:
 
