Update docs for getDefaultMiddleware

Author: markerikson

docs/api/configureStore.md

@@ -14,7 +14,7 @@ function configureStore({
     // A single reducer function that will be used as the root reducer,
     // or an object of slice reducers that will be passed to combineReducers()
     reducer: Object<string, Function> | Function,
-    // An array of Redux middlewares.  If not supplied, defaults to just redux-thunk.
+    // An array of Redux middlewares.  If not supplied, adds the middleware returned by getDefaultMiddleware()
     middleware: Array<MiddlewareFunction>,
     // Built-in support for devtools. Defaults to true.
     devTools: boolean,

docs/api/getDefaultMiddleware.md

@@ -7,6 +7,77 @@ hide_title: true
 
 # `getDefaultMiddleware`
 
-`getDefaultMiddleware` is useful if you need to add custom middlewares without removing `redux-starter-kit`'s default middleware.
+Returns an array containing the default list of middleware.
 
-Currently it returns an array with `redux-thunk`.
+## Intended Usage
+
+By default, [`configureStore`](./configureStore.md) adds some middleware to the Redux store setup automatically.
+
+```js
+const store = configureStore({
+    reducer : rootReducer,
+})
+
+// Store has one or more middleware added, because the middleware list was not customized
+```
+
+If you want to customize the list of middleware, you can supply an array of middleware functions to `configureStore`:
+
+```js
+const store = configureStore({
+    reducer : rootReducer,
+    middleware : [thunk, logger],
+})
+
+// Store specifically has the thunk and logger middleware applied
+```
+
+However, when you supply the `middleware` option, you are responsible for defining _all_ the middleware you want added
+to the store. `configureStore` will not add any extra middleware beyond what you listed.
+
+`getDefaultMiddleware` is useful if you want to add some custom middleware, but also still want to have the default
+middleware added as well:
+
+```js
+const store = configureStore({
+    reducer : rootReducer,
+    middleware: [...getDefaultMiddleware(), logger]
+})
+
+// Store has all of the default middleware added, _plus_ the logger middleware
+```
+
+
+## Included Default Middleware
+
+### Development
+
+One of the goals of `redux-starter-kit` is to provide opinionated defaults and prevent common mistakes.  As part of that,
+`getDefaultMiddleware` includes some middleware that are added **in development builds of your app only** to 
+provide runtime checks for two common issues:
+
+- [`redux-immutable-state-invariant`](https://github.com/leoasis/redux-immutable-state-invariant): deeply compares 
+state values for mutations.  It can detect mutations in reducers during a dispatch, and also mutations that occur between
+dispatches (such as in a component or a selector).  When a mutation is detect, it will throw an error and indicate the key
+path for where the mutated value was detected in the state tree.
+- `serializable-state-invariant-middleware`: a custom middleware created specifically for use in `redux-starter-kit`.  Similar in
+concept to `redux-immutable-state-invariant`, but deeply checks In adyour state tree and your actions for non-serializable values
+such as functions, Promises, Symbols, and other non-plain-JS-data values.  When a non-serializable value is detected, a
+console error will be printed with the key path for where the non-serializable value was detected.
+
+In addition to these development tool middleware, it also adds [`redux-thunk`](https://github.com/reduxjs/redux-thunk)
+by default, since thunks are the basic recommended side effects middleware for Redux.
+
+Currently, the return value is:
+
+```js
+[immutableStateInvariant, thunk, serializableStateInvariant]
+```
+
+### Production
+
+Currently, the return value is:
+
+```js
+[thunk]
+```