Update docs

zalmoxisus · Oct 4, 2016 · 28d8fdb · 28d8fdb
1 parent 7a8bc12
commit 28d8fdb
Show file tree

Hide file tree

Showing 10 changed files with 142 additions and 135 deletions.
diff --git a/README.md b/README.md
@@ -27,18 +27,18 @@
 
   If you have a basic [store](http://redux.js.org/docs/api/createStore.html) as described in the official [redux-docs](http://redux.js.org/index.html), simply replace:
   ```javascript
-  let store = createStore(reducer);
+  const store = createStore(reducer);
   ```
   with
   ```javascript
-  let store = createStore(reducer, window.devToolsExtension && window.devToolsExtension());
+  const store = createStore(reducer, window.__REDUX_DEVTOOLS_EXTENSION__ && window.__REDUX_DEVTOOLS_EXTENSION__());
   ```
 
-  Or with [initialState](http://redux.js.org/docs/api/createStore.html) but without middleware and enhancers arguments:
+  Or with [preloadedState](http://redux.js.org/docs/api/createStore.html) but without middleware and enhancers arguments:
 
   ```javascript
-  let store = createStore(reducer, initialState, 
-    window.devToolsExtension && window.devToolsExtension()
+  const store = createStore(reducer, preloadedState, 
+    window.__REDUX_DEVTOOLS_EXTENSION__ && window.__REDUX_DEVTOOLS_EXTENSION__()
   );
   ```
 
@@ -51,45 +51,91 @@
   ```javascript
   import { createStore, applyMiddleware, compose } from 'redux';
 
-  let store = createStore(reducer, initialState, compose(
+  const store = createStore(reducer, preloadedState, compose(
     applyMiddleware(...middleware)
   ));
   ```
-  to this:
+  to:
   ```javascript
-  let store = createStore(reducer, initialState, compose(
-    applyMiddleware(...middleware),
-    window.devToolsExtension ? window.devToolsExtension() : f => f
+  import { createStore, applyMiddleware, compose } from 'redux';
+
+  const composeEnhancers = window.__REDUX_DEVTOOLS_EXTENSION_COMPOSE__ || compose;
+  const store = createStore(reducer, preloadedState, composeEnhancers(
+    applyMiddleware(...middleware)
   ));
   ```
-
-#### 1.3 Together with Redux DevTools
-  You can use this extension together with vanilla [Redux DevTools](https://github.com/gaearon/redux-devtools) as a fallback, but not both simultaneously:
+  When the extension is not installed, we’re using Redux compose here.
+
+  In case you don’t want to allow the extension in production, [envify the code](https://github.com/gaearon/redux-devtools/blob/master/docs/Walkthrough.md#exclude-devtools-from-production-builds) and add `process.env.NODE_ENV !== 'production' && ` before `window.__REDUX_DEVTOOLS_EXTENSION_COMPOSE__`.
+
+  To specify [extension’s options](https://github.com/zalmoxisus/redux-devtools-extension/blob/master/docs/API/Arguments.md#windowdevtoolsextensionconfig) use it like that:
   ```js
-  window.devToolsExtension ? window.devToolsExtension() : DevTools.instrument()
+  const composeEnhancers =
+    process.env.NODE_ENV !== 'production' &&
+    typeof window === 'object' &&
+    window.__REDUX_DEVTOOLS_EXTENSION_COMPOSE__ ?   
+      window.__REDUX_DEVTOOLS_EXTENSION_COMPOSE__({
+        name: 'MyApp', actionsBlacklist: ['REDUX_STORAGE_SAVE']
+      }) : compose;
+
+  const enhancer = composeEnhancers(
+    applyMiddleware(...middleware),
+    // other store enhancers if any
+  );
+  const store = createStore(reducer, enhancer);
   ```
 
-  [Make sure not to render DevTools when using the extension](https://github.com/zalmoxisus/redux-devtools-extension/issues/57) or you'll probably want to render the monitor from vanilla DevTools as follows: 
+  [See the post for more details](https://medium.com/@zalmoxis/improve-your-development-workflow-with-redux-devtools-extension-f0379227ff83).
+
+#### 1.3 Use `redux-devtools-extension` package from npm
+
+  To make things easier, there's a npm package to install:
+  ```
+  npm install --save redux-devtools-extension
+  ```
+  and to use like that:
   ```js
-  { !window.devToolsExtension ? <DevTools /> : null }
+  import { createStore, applyMiddleware } from 'redux';
+  import { composeWithDevTools } from 'redux-devtools-extension';
+
+  const store = createStore(reducer, composeWithDevTools(
+    applyMiddleware(...middleware),
+    // other store enhancers if any
+  ));
   ```
-
-#### 1.4 Use with universal (isomorphic) apps
-```javascript
-  typeof window === 'object' && typeof window.devToolsExtension !== 'undefined' ? window.devToolsExtension() : f => f
-```
+  or if needed to apply [extension’s options](https://github.com/zalmoxisus/redux-devtools-extension/blob/master/docs/API/Arguments.md#windowdevtoolsextensionconfig):
+  ```js
+  import { createStore, applyMiddleware } from 'redux';
+  import { composeWithDevTools } from 'redux-devtools-extension';
+
+  const composeEnhancers = composeWithDevTools({
+    name: 'MyApp', actionsBlacklist: ['REDUX_STORAGE_SAVE']
+  });
+  const store = createStore(reducer, composeEnhancers(
+    applyMiddleware(...middleware),
+    // other store enhancers if any
+  ));
+  ```  
+  There’re just [few lines of code](https://github.com/zalmoxisus/redux-devtools-extension/blob/master/npm-package/index.js). If you don’t want to allow the extension in production, just use ‘redux-devtools-extension/developmentOnly’ instead of ‘redux-devtools-extension’.
+
 #### 1.5 For React Native, hybrid, desktop and server side Redux apps
   Include [`Remote Redux DevTools`](https://github.com/zalmoxisus/remote-redux-devtools)'s store enhancer, and from the extension's context menu choose 'Open Remote DevTools' or press Alt+Shift+arrow up for remote monitoring.
 
-### 2. For advanced usage see [our documentation](http://zalmoxisus.github.io/redux-devtools-extension/).
+### 2. Without Redux
+  See [the post](https://medium.com/@zalmoxis/redux-devtools-without-redux-or-how-to-have-a-predictable-state-with-any-architecture-61c5f5a7716f) for more details on how to use the extension with any architecture.
+
+## API Reference
+  - [Parameters](docs/API/Arguments.md)
+  - [Methods](docs/API/Methods.md)
+  - [Create Redux store right in the extension](docs/API/Methods.md).
 
 ## Demo
 Open these urls to test the extension:
 
  - [Counter](http://zalmoxisus.github.io/examples/counter/)
  - [TodoMVC](http://zalmoxisus.github.io/examples/todomvc/)
- - [Redux Form](http://erikras.github.io/redux-form/#/examples/simple)
  - [Redux Router](http://zalmoxisus.github.io/examples/router/)
+ - [Redux Form](http://erikras.github.io/redux-form/#/examples/simple)
 
 Also you may run them from `./examples` folder.
 

diff --git a/docs/API/Arguments.md b/docs/API/Arguments.md
@@ -1,11 +1,6 @@
-# API Reference
+# Parameters
 
-`window.devToolsExtension` function can be used in 2 ways:
- 1. [Apply as a Redux store enhancer](#windowdevtoolsextensionconfig)
- 2. [Create Redux store right in the extension](#windowdevtoolsextensionreducer-preloadedstate-config).
-
-
-### `window.devToolsExtension([config])`
+Use `window.__REDUX_DEVTOOLS_EXTENSION__([config])` or `window.__REDUX_DEVTOOLS_EXTENSION_COMPOSE__([config])()`
 - [`config`] *(object)*: options
   - **name** (*string*) - the instance name to be showed on the monitor page. Default value is `document.title`.
   - **actionCreators** (*array* or *object*) - action creators to dispatch remotely. See [the example](https://github.com/zalmoxisus/redux-devtools-extension/commit/477e69d8649dfcdc9bf84dd45605dab7d9775c03).
@@ -20,7 +15,7 @@
       Example of usage:
 
       ```js
-      const store = createStore(rootReducer, window.devToolsExtension && window.devToolsExtension({
+      const store = createStore(rootReducer, window.__REDUX_DEVTOOLS_EXTENSION__ && window.__REDUX_DEVTOOLS_EXTENSION__({
         deserializeState: (state) => ({
           todos: {
             ...state.todos,
@@ -35,7 +30,7 @@
       Example of usage:
 
       ```js
-      const store = Redux.createStore(reducer, window.devToolsExtension && window.devToolsExtension({
+      const store = Redux.createStore(reducer, window.__REDUX_DEVTOOLS_EXTENSION__ && window.__REDUX_DEVTOOLS_EXTENSION__({
         serializeState: (key, value) => (
           value && mori.isMap(value) ? mori.toJs(value) : value
         )
@@ -53,41 +48,8 @@
         action.type === 'FILE_DOWNLOAD_SUCCESS' && action.data ?
         { ...action, data: '<<LONG_BLOB>>' } : action
       );
-      const store = createStore(rootReducer, window.devToolsExtension && window.devToolsExtension({
+      const store = createStore(rootReducer, window.__REDUX_DEVTOOLS_EXTENSION__ && window.__REDUX_DEVTOOLS_EXTENSION__({
         actionsFilter,
-        statesFilter: (state) => state.data ? { ...state, data: '<<LONG_BLOB>>' } : state)
+        statesFilter: (state) => state.data ? { ...state, data: '<<LONG_BLOB>>' } : state
       }));
       ```
-  - **getMonitor** (*function*) - return monitor object with the following properties:
-    - **active** (*boolean*) - is `true` if the application is monitored (the monitor is open).
-    - **start** (*function*) - starts monitoring (relaying logs to the monitor).
-    - **stop** (*function*) - stop monitoring (the monitor will not get new changes till you `start` it again with the function above).
-    - **update** (*function*) - update state history. Usually you want to use it when stopped monitoring (with the function above) and want to update the logs explicitly (useful for apps which dispatch actions too frequently).   
-    - **isHotReloaded** (*function*) - return `true` if reducers just got hot reloaded (useful for dealing with side effects, which didn't get hot-reloaded).
-    - **isMonitorAction** (*function*) - return `true` if the last action was dispatched by the monitor (was: 'TOGGLE_ACTION', 'SWEEP', 'SET_ACTIONS_ACTIVE', 'IMPORT_STATE').
-    - **isTimeTraveling** (*function*) - return `true` if the state was set by moving back and forth (the last action was dispatched by the monitor was 'JUMP_TO_STATE'). Usually you want to use it to skip side effects. 
-
-      Example of usage:
-
-      ```js
-      export let isMonitorAction;
-      export default function configureStore(initialState) {
-        return createStore(reducer, initialState, 
-          window.devToolsExtension && window.devToolsExtension({
-            getMonitor: (monitor) => { isMonitorAction = monitor.isMonitorAction; }
-          }) : f => f
-        );
-      }  
-      ```
-      Then import it, for example, like [here](https://github.com/zalmoxisus/redux-devtools-extension/blob/master/examples/counter/components/Counter.js).
-
-### `window.devToolsExtension(reducer, [preloadedState, config])`
-> Note: This is not intended to replace Redux' `createStore`. Use this approach only when you want to inspect changes outside of Redux or when not using Redux inside your application.
-
-1. `reducer` *(Function)*: A [reducing function](https://github.com/reactjs/redux/blob/master/docs/Glossary.md#reducer) that returns the next [state tree](https://github.com/reactjs/redux/blob/master/docs/Glossary.md#state), given the current state tree and an [action](https://github.com/reactjs/redux/blob/master/docs/Glossary.md#action) to handle.
-
-2. [`preloadedState`] *(any)*: The initial state. You may optionally specify it to hydrate the state from the server in universal apps, or to restore a previously serialized user session. If you produced `reducer` with [`combineReducers`](https://github.com/reactjs/redux/tree/master/docs/api/combineReducers.md), this must be a plain object with the same shape as the keys passed to it. Otherwise, you are free to pass anything that your `reducer` can understand.
-
-3. [`config`] *(Object)*: options. See [above](#windowdevtoolsextensionconfig) for details.
-
-[Example of usage](https://github.com/zalmoxisus/redux-devtools-extension/commit/1810d2c1f0e8be1daf8f2d8f7bbeb4f8c528d90b).
diff --git a/docs/API/CreateStore.md b/docs/API/CreateStore.md
@@ -0,0 +1,12 @@
+### `window.__REDUX_DEVTOOLS_EXTENSION__(reducer, [preloadedState, config])`
+> Note: This is not intended to replace Redux' `createStore`. Use this approach only when you want to inspect changes outside of Redux or when not using Redux inside your application.
+
+1. `reducer` *(Function)*: A [reducing function](https://github.com/reactjs/redux/blob/master/docs/Glossary.md#reducer) that returns the next [state tree](https://github.com/reactjs/redux/blob/master/docs/Glossary.md#state), given the current state tree and an [action](https://github.com/reactjs/redux/blob/master/docs/Glossary.md#action) to handle.
+
+2. [`preloadedState`] *(any)*: The initial state. You may optionally specify it to hydrate the state from the server in universal apps, or to restore a previously serialized user session. If you produced `reducer` with [`combineReducers`](https://github.com/reactjs/redux/tree/master/docs/api/combineReducers.md), this must be a plain object with the same shape as the keys passed to it. Otherwise, you are free to pass anything that your `reducer` can understand.
+
+3. [`config`] *(Object)*: options. See [parameters](Arguments.md) for details.
+
+[Example of usage](https://github.com/zalmoxisus/redux-devtools-extension/commit/1810d2c1f0e8be1daf8f2d8f7bbeb4f8c528d90b).
+
+[See the post for more details](https://medium.com/@zalmoxis/redux-devtools-without-redux-or-how-to-have-a-predictable-state-with-any-architecture-61c5f5a7716f).
diff --git a/docs/API/Methods.md b/docs/API/Methods.md
@@ -2,53 +2,31 @@
 
 > Note that this API is still excremental and is subject to future changes. 
 
-Use the following methods of `window.devToolsExtension`:
+Use the following methods of `window.__REDUX_DEVTOOLS_EXTENSION__`:
 
-- [open](#windowdevtoolsextensionopenposition)
-- [notifyErrors](#windowdevtoolsextensionnotifyerrorsonerror)
-- [send](#windowdevtoolsextensionlistenonmessage-instanceid)
-- [connect](#windowdevtoolsextensionconnectconfig)
-- [disconnect](#windowdevtoolsextensiondisconnect)
+- [open](#openposition)
+- [notifyErrors](#notifyerrorsonerror)
+- [send](#listenonmessage-instanceid)
+- [connect](#connectconfig)
+- [disconnect](#disconnect)
 
-### window.devToolsExtension.open([position])
+### open([position])
 
 Open monitor window. 
 
 ##### Arguments
 
 - [`position`] *String* - window position: `left`, `right`, `bottom`. Also can be `panel` to [open it in a Chrome panel](../FAQ.md#how-to-keep-devtools-window-focused-all-the-time-in-a-chrome-panel). Or `remote` to [open remote monitor](../FAQ.md#how-to-get-it-work-with-webworkers-react-native-hybrid-desktop-and-server-side-apps). By default is `left`.
 
-### window.devToolsExtension.notifyErrors([onError])
+### notifyErrors([onError])
 
 Show notifications for uncaught exceptions.
 
 ##### Arguments
 
 - [`onError`] *Function* to call when there's an exceptions.
 
-### window.devToolsExtension.updateStore(store, instanceId)
-
-Specify a new `store` object to be used by the extension. For example, in case of Redux Saga we can use like this:
-
-```js
-const sagaMiddleware = createSagaMiddleware();
-const store = createStore(
-  reducer,
-  compose(
-    applyMiddleware(sagaMiddleware),
-    window.devToolsExtension && window.devToolsExtension()
-  )
-);
-sagaMiddleware.run(rootSaga);
-if (window.devToolsExtension) window.devToolsExtension.updateStore(store);
-```
-
-##### Arguments
-
-- `store` *Object* to update.
-- [`instanceId`] *String* - instance id for which to update the store (in case your specified it in the config).  
-
-### window.devToolsExtension.send(action, state, [shouldStringify, instanceId])
+### send(action, state, [shouldStringify, instanceId])
 
 Send a new action and state manually to be shown on the monitor.
 
@@ -59,7 +37,7 @@ Send a new action and state manually to be shown on the monitor.
 - [`shouldStringify`] *Boolean* - indicates whether to serialize `action` and `state`.
 - [`instanceId`] *String* - instance id for which to attach the log.  
 
-### window.devToolsExtension.listen(onMessage, instanceId)
+### listen(onMessage, instanceId)
 
 Send a new action and state manually to be shown on the monitor.
 
@@ -68,7 +46,7 @@ Send a new action and state manually to be shown on the monitor.
 - `onMessage` *Function* to call when there's an action form the monitor.
 - `instanceId` *String* - instance id for which to handle actions.  
 
-### window.devToolsExtension.connect([config])
+### connect([config])
 
 ##### Arguments
 
@@ -78,7 +56,7 @@ Send a new action and state manually to be shown on the monitor.
 *Object* containing the following methods:
 
 - `subscribe(listener)` - adds a change listener. It will be called any time an action is dispatched form the monitor.
-- `unsubscribe()` - unsubscribes the change listener. You can use [window.devToolsExtension.disconnect](#windowdevtoolsextensiondisconnect) to remove all listeners.
+- `unsubscribe()` - unsubscribes the change listener. You can use [window.__REDUX_DEVTOOLS_EXTENSION__.disconnect](#disconnect) to remove all listeners.
 - `send(action, state)` - sends a new action and state manually to be shown on the monitor. If action is `null` then we suppose we send `liftedState`. 
 - `init(state)` - sends the initial state to the monitor.
 - `error(message)` - sends the error message to be shown in Dispatcher monitor.
@@ -89,7 +67,7 @@ Example of usage:
 let isStarted = false;
 let isLiftedAction = false;
 
-const devTools = window.devToolsExtension.connect();
+const devTools = window.__REDUX_DEVTOOLS_EXTENSION__.connect();
 devTools.subscribe((message) => {
   if (message.type === 'START') {
     isStarted = true;
@@ -114,6 +92,8 @@ store.subscribe(() => {
 
 There's [a simpler example](https://github.com/zalmoxisus/redux-devtools-extension/blob/master/examples/react-counter-messaging/components/Counter.js).
 
-### window.devToolsExtension.disconnect()
+[See the post for more details](https://medium.com/@zalmoxis/redux-devtools-without-redux-or-how-to-have-a-predictable-state-with-any-architecture-61c5f5a7716f).
+
+### disconnect()
 
 Remove extensions listener and disconnect extensions background script connection.
diff --git a/docs/API/README.md b/docs/API/README.md
@@ -0,0 +1,5 @@
+# API Reference
+
+- [Parameters](Arguments.md)
+- [Methods](Methods.md)
+- [Create Redux store right in the extension](Methods.md)
diff --git a/docs/Credits.md b/docs/Credits.md
@@ -1,7 +1,11 @@
 # Credits
 
  - Built using [Crossbuilder](https://github.com/zalmoxisus/crossbuilder) boilerplate.
- - Includes [Dan Abramov](https://github.com/gaearon)'s [redux-devtools](https://github.com/gaearon/redux-devtools).
- - Inspired from [Taylor Hakes](https://github.com/taylorhakes)' [work](https://github.com/taylorhakes/redux-devtools/tree/chrome-devtools).
+ - Includes [Dan Abramov](https://github.com/gaearon)'s [redux-devtools](https://github.com/gaearon/redux-devtools) and the following monitors:
+    - [Log Monitor](https://github.com/gaearon/redux-devtools-log-monitor)
+    - [Inspector](https://github.com/alexkuz/redux-devtools-inspector)
+    - [Dispatch](https://github.com/YoruNoHikage/redux-devtools-dispatch)
+    - [Slider](https://github.com/calesce/redux-slider-monitor)
+    - [Chart](https://github.com/romseguy/redux-devtools-chart-monitor)
  - [The logo icon](https://github.com/reactjs/redux/issues/151) made by [Keith Yong](https://github.com/keithyong) .
  - Examples from [Redux](https://github.com/rackt/redux/tree/master/examples).