diff --git a/.circleci/config.yml b/.circleci/config.yml
index a0b6dddef..f1bfdf810 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -115,8 +115,11 @@ workflows:
version: 2
build-and-test:
jobs:
- - build
-
+ - build:
+ filters:
+ branches:
+ ignore:
+ - gh-pages
- test-all:
requires:
- build
diff --git a/.gitignore b/.gitignore
index 4c811618c..0e984af99 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,3 +16,4 @@ dist/
*.ipr
*.iws
yarn-error.log
+build/
\ No newline at end of file
diff --git a/README.md b/README.md
index af46c2256..415468d4a 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-
+
# MobX
@@ -15,21 +15,21 @@ _Simple, scalable state management_
MobX is proudly sponsored by Mendix, Coinbase, Facebook Open Source, Canva, Algolia, Guilded, Auction Frontier, Mantro and TalentPlot for 100\$/month or more! And beyond that by many [individual backers](#backers) and through [one time contributions](https://github.com/mobxjs/mobx/blob/master/sponsors.md).
**🥇Gold sponsors (\$250+ pm):**
-
-
+
+
**🥈Silver sponsors (\$100+ pm):**
-
-
-
-
-
-
+
+
+
+
+
+
**🥉Bronze sponsors:**
-
-
-
+
+
+
# Installation
@@ -67,7 +67,7 @@ _Tip: Consider using the faster and smaller ES6 build if targetting a modern env
- Egghead.io course
- [Ten minute, interactive MobX + React tutorial](https://mobxjs.github.io/mobx/getting-started.html)
-- [The MobX book](https://books.google.nl/books?id=ALFmDwAAQBAJ&pg=PP1&lpg=PP1&dq=michel+weststrate+mobx+quick+start+guide:+supercharge+the+client+state+in+your+react+apps+with+mobx&source=bl&ots=D460fxti0F&sig=ivDGTxsPNwlOjLHrpKF1nweZFl8&hl=nl&sa=X&ved=2ahUKEwiwl8XO--ncAhWPmbQKHWOYBqIQ6AEwAnoECAkQAQ#v=onepage&q=michel%20weststrate%20mobx%20quick%20start%20guide%3A%20supercharge%20the%20client%20state%20in%20your%20react%20apps%20with%20mobx&f=false) by Pavan Podila and Michel Weststrate (which despite it's name is in-depth!)
+- [The MobX book](https://books.google.nl/books?id=ALFmDwAAQBAJ&pg=PP1&lpg=PP1&dq=michel+weststrate+mobx+quick+start+guide:+supercharge+the+client+state+in+your+react+apps+with+mobx&source=bl&ots=D460fxti0F&sig=ivDGTxsPNwlOjLHrpKF1nweZFl8&hl=nl&sa=X&ved=2ahUKEwiwl8XO--ncAhWPmbQKHWOYBqIQ6AEwAnoECAkQAQ#v=onepage&q=michel%20weststrate%20mobx%20quick%20start%20guide%3A%20supercharge%20the%20client%20state%20in%20your%20react%20apps%20with%20mobx&f=false) by Pavan Podila and Michel Weststrate (which despite its name is in-depth!)
- [Official MobX 4 documentation and API overview](https://mobxjs.github.io/mobx/refguide/api.html) ([MobX 3](https://github.com/mobxjs/mobx/blob/54557dc319b04e92e31cb87427bef194ec1c549c/docs/refguide/api.md), [MobX 2](https://github.com/mobxjs/mobx/blob/7c9e7c86e0c6ead141bb0539d33143d0e1f576dd/docs/refguide/api.md))
- [How to (not) use decorators](https://mobx.js.org/best/decorators.html)
- Videos:
@@ -87,7 +87,7 @@ _Anything that can be derived from the application state, should be derived. Aut
This includes the UI, data serialization, server communication, etc.
-
+
React and MobX together are a powerful combination. React renders the application state by providing mechanisms to translate it into a tree of renderable components. MobX provides the mechanism to store and update the application state that React then uses.
@@ -308,7 +308,7 @@ And finally, kudos to all the people that believed in, tried, validated and even
## Further resources and documentation
-- [The MobX book](https://books.google.nl/books?id=ALFmDwAAQBAJ&pg=PP1&lpg=PP1&dq=michel+weststrate+mobx+quick+start+guide:+supercharge+the+client+state+in+your+react+apps+with+mobx&source=bl&ots=D460fxti0F&sig=ivDGTxsPNwlOjLHrpKF1nweZFl8&hl=nl&sa=X&ved=2ahUKEwiwl8XO--ncAhWPmbQKHWOYBqIQ6AEwAnoECAkQAQ#v=onepage&q=michel%20weststrate%20mobx%20quick%20start%20guide%3A%20supercharge%20the%20client%20state%20in%20your%20react%20apps%20with%20mobx&f=false) by Pavan Podila and Michel Weststrate (which despite it's name is in-depth!)
+- [The MobX book](https://books.google.nl/books?id=ALFmDwAAQBAJ&pg=PP1&lpg=PP1&dq=michel+weststrate+mobx+quick+start+guide:+supercharge+the+client+state+in+your+react+apps+with+mobx&source=bl&ots=D460fxti0F&sig=ivDGTxsPNwlOjLHrpKF1nweZFl8&hl=nl&sa=X&ved=2ahUKEwiwl8XO--ncAhWPmbQKHWOYBqIQ6AEwAnoECAkQAQ#v=onepage&q=michel%20weststrate%20mobx%20quick%20start%20guide%3A%20supercharge%20the%20client%20state%20in%20your%20react%20apps%20with%20mobx&f=false) by Pavan Podila and Michel Weststrate (which despite its name is in-depth!)
- [MobX homepage](http://mobxjs.github.io/mobx/faq/blogs.html)
- [API overview](http://mobxjs.github.io/mobx/refguide/api.html)
- [Tutorials, Blogs & Videos](http://mobxjs.github.io/mobx/faq/blogs.html)
@@ -363,7 +363,7 @@ To use the [flow typings](flow-typed/mobx.js) shipped with MobX:
## Donating
Was MobX key in making your project a success?
-Join our [open collective](https://opencollective.com/mobx#) or use the [donate button](https://mobxjs.github.io/mobx/donate.html)!
+Join our [open collective](https://opencollective.com/mobx#)!
### Backers
diff --git a/docs/LINKS.md b/docs/LINKS.md
new file mode 100644
index 000000000..5e3cc5739
--- /dev/null
+++ b/docs/LINKS.md
@@ -0,0 +1,33 @@
+
+
+# Resources
+
+* [Ten minute interactive introduction to MobX and React](https://mobxjs.github.io/mobx/getting-started.html#demo)
+* How MobX works: [In depth explanation of MobX](https://medium.com/@mweststrate/becoming-fully-reactive-an-in-depth-explanation-of-mobservable-55995262a254#.wnlo6bw8y)
+* Clone the boilerplate repository containing the above example from: https://github.com/mweststrate/react-mobservable-boilerplate.
+* Or fork this [JSFiddle](https://jsfiddle.net/mweststrate/wgbe4guu/).
+
+## Related projects
+
+* [mobx-connect](https://github.com/nightwolfz/mobx-connect) MobX @connect decorator for react components. Similar to redux's @connect.
+* [rfx-stack](https://github.com/foxhound87/rfx-stack) RFX Stack - Universal App featuring: React + Feathers + MobX
+* [mobx-reactor](https://github.com/amsb/mobx-reactor) Connect MobX data stores to functional stateless React components with async actions and unidirectional data flow.
+* [mobx-model](https://github.com/ikido/mobx-model) Simplify mobx data stores that mimic backend models
+* [rx-mobx](https://github.com/chicoxyzzy/rx-mobx) Convert Mobx observables to RxJS and vice versa
+
+## More examples
+
+A nice list is WIP, but see this [github issue](https://github.com/mobxjs/mobx/issues/104) for a list of example projects, including routing, authorization, server side rendering etc.
+
+* [TodoMVC using MobX and React](https://github.com/mweststrate/mobx-todomvc)
+* The [ports of the _Notes_ and _Kanban_ examples](https://github.com/survivejs/mobservable-demo) from the book "SurviveJS - Webpack and React" to mobservable.
+* A simple webshop using [React + mobx](https://jsfiddle.net/mweststrate/46vL0phw) or [JQuery + mobx](http://jsfiddle.net/mweststrate/vxn7qgdw).
+* [Simple timer](https://jsfiddle.net/mweststrate/wgbe4guu/) application in JSFiddle.
+* [Simple ES5 MobX examples](https://github.com/mattruby/mobx-examples) Bite sized MobX examples all setup to run in jsFiddle.
+
+## Philosophy
+
+* [Making React reactive: the pursuit of high performing, easily maintainable React apps](https://www.mendix.com/tech-blog/making-react-reactive-pursuit-high-performing-easily-maintainable-react-apps/)
+* [SurviveJS interview on Mobservable, React and Flux](http://survivejs.com/blog/mobservable-interview/)
+* [Pure rendering in the light of time and state](https://medium.com/@mweststrate/pure-rendering-in-the-light-of-time-and-state-4b537d8d40b1)
+* [Official homepage](http://mobxjs.github.io/mobx/)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..797c5a8be
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,487 @@
+---
+title: Introduction
+sidebar_label: Introduction
+hide_title: true
+---
+
+
+
+# MobX
+
+_Simple, scalable state management_
+
+[](https://travis-ci.org/mobxjs/mobx)
+[](https://coveralls.io/github/mobxjs/mobx?branch=master)
+[](https://gitter.im/mobxjs/mobx?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[](https://hashnode.com/n/mobx)
+[](#backers)
+[](#sponsors)
+[](https://github.com/prettier/prettier)
+
+
+
+MobX is proudly sponsored by Mendix, Coinbase, Facebook Open Source, Canva, Algolia, Guilded, Auction Frontier, Mantro and TalentPlot for 100\$/month or more! And beyond that by many [individual backers](#backers) and through [one time contributions](https://github.com/mobxjs/mobx/blob/master/sponsors.md).
+
+**🥇Gold sponsors (\$250+ pm):**
+
+
+
+**🥈Silver sponsors (\$100+ pm):**
+
+
+
+
+
+
+
+**🥉Bronze sponsors:**
+
+
+
+
+
+# Installation
+
+- Installation: `npm install mobx --save`. React bindings: `npm install mobx-react --save`. To enable ESNext decorators (optional), see below.
+- CDN:
+
+* https://unpkg.com/mobx/lib/mobx.umd.js
+* https://cdnjs.com/libraries/mobx
+
+# Browser support
+
+- MobX >=5 runs on any browser with [ES6 proxy support](https://kangax.github.io/compat-table/es6/#test-Proxy). It will throw an error on startup on older environments such as IE11, Node.js <6 or React Native Android on old JavaScriptCore [how-to-upgrade](https://github.com/react-community/jsc-android-buildscripts#how-to-use-it-with-my-react-native-app).
+- MobX 4 runs on any ES5 browser and will be actively maintained. The MobX 4 and 5 api's are the same and semantically can achieve the same, but MobX 4 has some [limitations](#mobx-4-vs-mobx-5).
+
+_Tip: the main entry point of the MobX 5 package ships with ES5 code for backward compatibility with all build tools. But since MobX 5 runs only on modern browsers anyway, consider using the faster and smaller ES6 build: `lib/mobx.es6.js`. For example by setting up a webpack alias: `resolve: { alias: { mobx: __dirname + "/node_modules/mobx/lib/mobx.es6.js" }}`_
+
+## Translations
+
+- [中文](http://cn.mobx.js.org)
+
+## Getting started
+
+- egghead.io course
+- [Ten minute, interactive MobX + React tutorial](https://mobxjs.github.io/mobx/getting-started.html)
+- [The MobX book](https://books.google.nl/books?id=ALFmDwAAQBAJ&pg=PP1&lpg=PP1&dq=michel+weststrate+mobx+quick+start+guide:+supercharge+the+client+state+in+your+react+apps+with+mobx&source=bl&ots=D460fxti0F&sig=ivDGTxsPNwlOjLHrpKF1nweZFl8&hl=nl&sa=X&ved=2ahUKEwiwl8XO--ncAhWPmbQKHWOYBqIQ6AEwAnoECAkQAQ#v=onepage&q=michel%20weststrate%20mobx%20quick%20start%20guide%3A%20supercharge%20the%20client%20state%20in%20your%20react%20apps%20with%20mobx&f=false) by Pavan Podila and Michel Weststrate (which despite its name is in-depth!)
+- [Official MobX 4 documentation and API overview](https://mobxjs.github.io/mobx/refguide/api.html) ([MobX 3](https://github.com/mobxjs/mobx/blob/54557dc319b04e92e31cb87427bef194ec1c549c/docs/refguide/api.md), [MobX 2](https://github.com/mobxjs/mobx/blob/7c9e7c86e0c6ead141bb0539d33143d0e1f576dd/docs/refguide/api.md))
+- Videos:
+ - [ReactNext 2016: Real World MobX](https://www.youtube.com/watch?v=Aws40KOx90U) - 40m [slides](https://docs.google.com/presentation/d/1DrI6Hc2xIPTLBkfNH8YczOcPXQTOaCIcDESdyVfG_bE/edit?usp=sharing)
+ - [Practical React with MobX](https://www.youtube.com/watch?v=XGwuM_u7UeQ). In depth introduction and explanation to MobX and React by Matt Ruby on OpenSourceNorth (ES5 only) - 42m.
+ - LearnCode.academy MobX tutorial [Part I: MobX + React is AWESOME (7m)](https://www.youtube.com/watch?v=_q50BXqkAfI) [Part II: Computed Values and Nested/Referenced Observables (12m.)](https://www.youtube.com/watch?v=nYvNqKrl69s)
+ - [Screencast: intro to MobX](https://www.youtube.com/watch?v=K8dr8BMU7-8) - 8m
+ - [Talk: State Management Is Easy, React Amsterdam 2016 conf](https://www.youtube.com/watch?v=ApmSsu3qnf0&feature=youtu.be) ([slides](https://speakerdeck.com/mweststrate/state-management-is-easy-introduction-to-mobx))
+- [Boilerplates and related projects](http://mobxjs.github.io/mobx/faq/boilerplates.html)
+- More tutorials, blogs, videos, and other helpful resources can be found on the [MobX awesome list](https://github.com/mobxjs/awesome-mobx#awesome-mobx)
+
+## Introduction
+
+MobX is a battle tested library that makes state management simple and scalable by transparently applying functional reactive programming (TFRP).
+The philosophy behind MobX is very simple:
+
+_Anything that can be derived from the application state, should be derived. Automatically._
+
+which includes the UI, data serialization, server communication, etc.
+
+
+
+React and MobX together are a powerful combination. React renders the application state by providing mechanisms to translate it into a tree of renderable components. MobX provides the mechanism to store and update the application state that React then uses.
+
+Both React and MobX provide an optimal and unique solutions to common problems in application development. React provides mechanisms to optimally render UI by using a virtual DOM that reduces the number of costly DOM mutations. MobX provides mechanisms to optimally synchronize application state with your React components by using a reactive virtual dependency state graph that is only updated when strictly needed and is never stale.
+
+## Core concepts
+
+MobX has only a few core concepts. The following snippets can be tried online using [codesandbox example](https://codesandbox.io/s/v3v0my2370).
+
+### Observable state
+
+Egghead.io lesson 1: observable & observer
+
+MobX adds observable capabilities to existing data structures like objects, arrays and class instances.
+This can simply be done by annotating your class properties with the [@observable](http://mobxjs.github.io/mobx/refguide/observable-decorator.html) decorator (ES.Next).
+
+```javascript
+import { observable } from "mobx"
+
+class Todo {
+ id = Math.random()
+ @observable title = ""
+ @observable finished = false
+}
+```
+
+Using `observable` is like turning a property of an object into a spreadsheet cell.
+But unlike spreadsheets, these values can be not only primitive values, but also references, objects and arrays.
+
+If your environment doesn't support decorator syntax, don't worry.
+You can read [here](http://mobxjs.github.io/mobx/best/decorators.html) about how to set them up.
+Or you can skip them altogether, as MobX can be used fine without decorator _syntax_, by leveraging the _decorate_ utility.
+Many MobX users do prefer the decorator syntax though, as it is slightly more concise.
+
+```javascript
+import { decorate, observable } from "mobx"
+
+class Todo {
+ id = Math.random()
+ title = ""
+ finished = false
+}
+decorate(Todo, {
+ title: observable,
+ finished: observable
+})
+```
+
+### Computed values
+
+Egghead.io lesson 3: computed values
+
+With MobX you can define values that will be derived automatically when relevant data is modified.
+By using the [`@computed`](http://mobxjs.github.io/mobx/refguide/computed-decorator.html) decorator or by using getter / setter functions when using `(extend)Observable` (Of course, you can use `decorate` here again as alternative to the `@` syntax).
+
+```javascript
+class TodoList {
+ @observable todos = []
+ @computed get unfinishedTodoCount() {
+ return this.todos.filter(todo => !todo.finished).length
+ }
+}
+```
+
+MobX will ensure that `unfinishedTodoCount` is updated automatically when a todo is added or when one of the `finished` properties is modified.
+Computations like these resemble formulas in spreadsheet programs like MS Excel. They update automatically and only when required.
+
+### Reactions
+
+Egghead.io lesson 9: custom reactions
+
+Reactions are similar to a computed value, but instead of producing a new value, a reaction produces a side effect for things like printing to the console, making network requests, incrementally updating the React component tree to patch the DOM, etc.
+In short, reactions bridge [reactive](https://en.wikipedia.org/wiki/Reactive_programming) and [imperative](https://en.wikipedia.org/wiki/Imperative_programming) programming.
+
+#### React components
+
+Egghead.io lesson 1: observable & observer
+
+If you are using React, you can turn your (stateless function) components into reactive components by simply adding the [`observer`](http://mobxjs.github.io/mobx/refguide/observer-component.html) function / decorator from the `mobx-react` package onto them.
+
+```javascript
+import React, { Component } from "react"
+import ReactDOM from "react-dom"
+import { observer } from "mobx-react"
+
+@observer
+class TodoListView extends Component {
+ render() {
+ return (
+
+))
+
+const store = new TodoList()
+ReactDOM.render(, document.getElementById("mount"))
+```
+
+`observer` turns React (function) components into derivations of the data they render.
+When using MobX there are no smart or dumb components.
+All components render smartly but are defined in a dumb manner. MobX will simply make sure the components are always re-rendered whenever needed, but also no more than that. So the `onClick` handler in the above example will force the proper `TodoView` to render, and it will cause the `TodoListView` to render if the number of unfinished tasks has changed.
+However, if you would remove the `Tasks left` line (or put it into a separate component), the `TodoListView` will no longer re-render when ticking a box. You can verify this yourself by changing the [JSFiddle](https://jsfiddle.net/mweststrate/wv3yopo0/).
+
+#### Custom reactions
+
+Custom reactions can simply be created using the [`autorun`](http://mobxjs.github.io/mobx/refguide/autorun.html),
+[`reaction`](http://mobxjs.github.io/mobx/refguide/reaction.html) or [`when`](http://mobxjs.github.io/mobx/refguide/when.html) functions to fit your specific situations.
+
+For example the following `autorun` prints a log message each time the amount of `unfinishedTodoCount` changes:
+
+```javascript
+autorun(() => {
+ console.log("Tasks left: " + todos.unfinishedTodoCount)
+})
+```
+
+### What will MobX react to?
+
+Why does a new message get printed each time the `unfinishedTodoCount` is changed? The answer is this rule of thumb:
+
+_MobX reacts to any existing observable property that is read during the execution of a tracked function._
+
+For an in-depth explanation about how MobX determines to which observables needs to be reacted, check [understanding what MobX reacts to](https://github.com/mobxjs/mobx/blob/gh-pages/docs/best/react.md).
+
+### Actions
+
+Egghead.io lesson 5: actions
+
+Unlike many flux frameworks, MobX is unopinionated about how user events should be handled.
+
+- This can be done in a Flux like manner.
+- Or by processing events using RxJS.
+- Or by simply handling events in the most straightforward way possible, as demonstrated in the above `onClick` handler.
+
+In the end it all boils down to: Somehow the state should be updated.
+
+After updating the state `MobX` will take care of the rest in an efficient, glitch-free manner. So simple statements, like below, are enough to automatically update the user interface.
+
+There is no technical need for firing events, calling a dispatcher or what more. A React component in the end is nothing more than a fancy representation of your state. A derivation that will be managed by MobX.
+
+```javascript
+store.todos.push(new Todo("Get Coffee"), new Todo("Write simpler code"))
+store.todos[0].finished = true
+```
+
+Nonetheless, MobX has an optional built-in concept of [`actions`](https://mobxjs.github.io/mobx/refguide/action.html).
+Read this section as well if you want to know more about writing asynchronous actions. It's easy!
+Use them to your advantage; they will help you to structure your code better and make wise decisions about when and where state should be modified.
+
+## MobX: Simple and scalable
+
+MobX is one of the least obtrusive libraries you can use for state management. That makes the `MobX` approach not just simple, but very scalable as well:
+
+### Using classes and real references
+
+With MobX you don't need to normalize your data. This makes the library very suitable for very complex domain models (At Mendix for example ~500 different domain classes in a single application).
+
+### Referential integrity is guaranteed
+
+Since data doesn't need to be normalized, and MobX automatically tracks the relations between state and derivations, you get referential integrity for free. Rendering something that is accessed through three levels of indirection?
+
+No problem, MobX will track them and re-render whenever one of the references changes. As a result staleness bugs are a thing of the past. As a programmer you might forget that changing some data might influence a seemingly unrelated component in a corner case. MobX won't forget.
+
+### Simpler actions are easier to maintain
+
+As demonstrated above, modifying state when using MobX is very straightforward. You simply write down your intentions. MobX will take care of the rest.
+
+### Fine grained observability is efficient
+
+MobX builds a graph of all the derivations in your application to find the least number of re-computations that is needed to prevent staleness. "Derive everything" might sound expensive, MobX builds a virtual derivation graph to minimize the number of recomputations needed to keep derivations in sync with the state.
+
+In fact, when testing MobX at Mendix we found out that using this library to track the relations in our code is often a lot more efficient than pushing changes through our application by using handwritten events or "smart" selector based container components.
+
+The simple reason is that MobX will establish far more fine grained 'listeners' on your data than you would do as a programmer.
+
+Secondly MobX sees the causality between derivations so it can order them in such a way that no derivation has to run twice or introduces a glitch.
+
+How that works? See this [in-depth explanation of MobX](https://medium.com/@mweststrate/becoming-fully-reactive-an-in-depth-explanation-of-mobservable-55995262a254).
+
+### Easy interoperability
+
+MobX works with plain javascript structures. Due to its unobtrusiveness it works with most javascript libraries out of the box, without needing MobX specific library flavors.
+
+So you can simply keep using your existing router, data fetching, and utility libraries like `react-router`, `director`, `superagent`, `lodash` etc.
+
+For the same reason you can use it out of the box both server and client side, in isomorphic applications and with react-native.
+
+The result of this is that you often need to learn less new concepts when using MobX in comparison to other state management solutions.
+
+---
+
+## Credits
+
+MobX is inspired by reactive programming principles as found in spreadsheets. It is inspired by MVVM frameworks like in MeteorJS tracker, knockout and Vue.js. But MobX brings Transparent Functional Reactive Programming to the next level and provides a stand alone implementation. It implements TFRP in a glitch-free, synchronous, predictable and efficient manner.
+
+A ton of credits for [Mendix](https://github.com/mendix), for providing the flexibility and support to maintain MobX and the chance to proof the philosophy of MobX in a real, complex, performance critical applications.
+
+And finally kudos for all the people that believed in, tried, validated and even [sponsored](https://github.com/mobxjs/mobx/blob/master/sponsors.md) MobX.
+
+## Further resources and documentation
+
+- [The MobX book](https://books.google.nl/books?id=ALFmDwAAQBAJ&pg=PP1&lpg=PP1&dq=michel+weststrate+mobx+quick+start+guide:+supercharge+the+client+state+in+your+react+apps+with+mobx&source=bl&ots=D460fxti0F&sig=ivDGTxsPNwlOjLHrpKF1nweZFl8&hl=nl&sa=X&ved=2ahUKEwiwl8XO--ncAhWPmbQKHWOYBqIQ6AEwAnoECAkQAQ#v=onepage&q=michel%20weststrate%20mobx%20quick%20start%20guide%3A%20supercharge%20the%20client%20state%20in%20your%20react%20apps%20with%20mobx&f=false) by Pavan Podila and Michel Weststrate (which despite its name is in-depth!)
+- [MobX homepage](http://mobxjs.github.io/mobx/faq/blogs.html)
+- [API overview](http://mobxjs.github.io/mobx/refguide/api.html)
+- [Tutorials, Blogs & Videos](http://mobxjs.github.io/mobx/faq/blogs.html)
+- [Boilerplates](http://mobxjs.github.io/mobx/faq/boilerplates.html)
+- [Related projects](http://mobxjs.github.io/mobx/faq/related.html)
+
+## What others are saying...
+
+> Guise, #mobx isn't pubsub, or your grandpa's observer pattern. Nay, it is a carefully orchestrated observable dimensional portal fueled by the power cosmic. It doesn't do change detection, it's actually a level 20 psionic with soul knife, slashing your viewmodel into submission.
+
+> After using #mobx for lone projects for a few weeks, it feels awesome to introduce it to the team. Time: 1/2, Fun: 2X
+
+> Working with #mobx is basically a continuous loop of me going “this is way too simple, it definitely won’t work” only to be proven wrong
+
+> Try react-mobx with es6 and you will love it so much that you will hug someone.
+
+> I have built big apps with MobX already and comparing to the one before that which was using Redux, it is simpler to read and much easier to reason about.
+
+> The #mobx is the way I always want things to be! It's really surprising simple and fast! Totally awesome! Don't miss it!
+
+## Contributing
+
+- Feel free to send small pull requests. Please discuss new features or big changes in a GitHub issue first.
+- Use `npm test` to run the basic test suite, `npm run coverage` for the test suite with coverage and `npm run test:performance` for the performance tests.
+- Please note that if you want to backport a feature / fix to MobX 4 a second PR needs to be opened to the mobx4-master branch.
+
+# MobX 4 vs MobX 5
+
+The difference between MobX 4 and MobX 5 is that the latter uses Proxies to do property tracking. As a consequence MobX 5 only runs on Proxy supporting browsers, in contrast to MobX 4 that runs on any ES 5 environment.
+
+The most noteable limitations of MobX 4:
+
+- Observable arrays are not real arrays, so they won't pass the `Array.isArray()` check. The practical consequence is that you often need to `.slice()` the array first (to get a real array shallow copy) before passing to third party libraries.
+- Adding properties to existing observable objects after creation is not automatically picked up. Either use observable maps instead, or use the the build in [utility functions](https://mobx.js.org/refguide/object-api.html) to read / write / iterate objects that you want to dynamically add properties to.
+
+For more details see the [caveats page](https://mobx.js.org/best/pitfalls.html).
+
+## Flow support
+
+MobX ships with [flow typings](https://github.com/mobxjs/mobx/blob/master/flow-typed/mobx.js). Flow will automatically include them when you import mobx modules. Although you **do not** need to import the types explicitly, you can still do it like this: `import type { ... } from 'mobx'`.
+
+To use the [flow typings](https://github.com/mobxjs/mobx/blob/master/flow-typed/mobx.js) shipped with MobX:
+
+- In `.flowconfig`, you **cannot** ignore `node_modules`.
+- In `.flowconfig`, you **cannot** import it explicitly in the `[libs]` section.
+- You **do not** need to install library definition using [flow-typed](https://github.com/flowtype/flow-typed).
+
+## Donating
+
+Was MobX key in making your project a success?
+Join our [open collective](https://opencollective.com/mobx#)!
+
+### Backers
+
+Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/mobx#backer)]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+One time donations through paypal are welcome as well and are recorded in the [sponsors](sponsors.md) list.
+
+[](https://mobxjs.github.io/mobx/donate.html)
+
+### Sponsors
+
+Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/mobx#sponsor)]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/assets/action-state-view.png b/docs/assets/action-state-view.png
new file mode 100644
index 000000000..3db0b78b7
Binary files /dev/null and b/docs/assets/action-state-view.png differ
diff --git a/docs/algolia.jpg b/docs/assets/algolia.jpg
similarity index 100%
rename from docs/algolia.jpg
rename to docs/assets/algolia.jpg
diff --git a/docs/auctionfrontier.jpeg b/docs/assets/auctionfrontier.jpeg
similarity index 100%
rename from docs/auctionfrontier.jpeg
rename to docs/assets/auctionfrontier.jpeg
diff --git a/docs/assets/blokt.jpg b/docs/assets/blokt.jpg
new file mode 100644
index 000000000..cd61d242c
Binary files /dev/null and b/docs/assets/blokt.jpg differ
diff --git a/docs/book.jpg b/docs/assets/book.jpg
similarity index 100%
rename from docs/book.jpg
rename to docs/assets/book.jpg
diff --git a/docs/canva.png b/docs/assets/canva.png
similarity index 100%
rename from docs/canva.png
rename to docs/assets/canva.png
diff --git a/docs/assets/codefirst.png b/docs/assets/codefirst.png
new file mode 100644
index 000000000..0d8561af6
Binary files /dev/null and b/docs/assets/codefirst.png differ
diff --git a/docs/coinbase.jpeg b/docs/assets/coinbase.jpeg
similarity index 100%
rename from docs/coinbase.jpeg
rename to docs/assets/coinbase.jpeg
diff --git a/docs/assets/concept.png b/docs/assets/concept.png
new file mode 100644
index 000000000..cd6894448
Binary files /dev/null and b/docs/assets/concept.png differ
diff --git a/docs/assets/devtools-noDisplayName.png b/docs/assets/devtools-noDisplayName.png
new file mode 100644
index 000000000..417316a02
Binary files /dev/null and b/docs/assets/devtools-noDisplayName.png differ
diff --git a/docs/assets/devtools-withDisplayName.png b/docs/assets/devtools-withDisplayName.png
new file mode 100644
index 000000000..98434dcfb
Binary files /dev/null and b/docs/assets/devtools-withDisplayName.png differ
diff --git a/docs/assets/devtools.gif b/docs/assets/devtools.gif
new file mode 100644
index 000000000..cf49646f3
Binary files /dev/null and b/docs/assets/devtools.gif differ
diff --git a/docs/assets/faire.jpg b/docs/assets/faire.jpg
new file mode 100644
index 000000000..45af35aca
Binary files /dev/null and b/docs/assets/faire.jpg differ
diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png
new file mode 100644
index 000000000..63da62bc9
Binary files /dev/null and b/docs/assets/favicon.png differ
diff --git a/docs/fbos.jpeg b/docs/assets/fbos.jpeg
similarity index 100%
rename from docs/fbos.jpeg
rename to docs/assets/fbos.jpeg
diff --git a/docs/flow.png b/docs/assets/flow.png
similarity index 100%
rename from docs/flow.png
rename to docs/assets/flow.png
diff --git a/docs/guilded.jpg b/docs/assets/guilded.jpg
similarity index 100%
rename from docs/guilded.jpg
rename to docs/assets/guilded.jpg
diff --git a/docs/mantro.png b/docs/assets/mantro.png
similarity index 100%
rename from docs/mantro.png
rename to docs/assets/mantro.png
diff --git a/docs/mendix-logo.png b/docs/assets/mendix-logo.png
similarity index 100%
rename from docs/mendix-logo.png
rename to docs/assets/mendix-logo.png
diff --git a/docs/assets/mobservable.png b/docs/assets/mobservable.png
new file mode 100644
index 000000000..386c308ce
Binary files /dev/null and b/docs/assets/mobservable.png differ
diff --git a/docs/assets/mobservable.svg b/docs/assets/mobservable.svg
new file mode 100644
index 000000000..4802b1278
--- /dev/null
+++ b/docs/assets/mobservable.svg
@@ -0,0 +1,118 @@
+
+
+
+
diff --git a/docs/mobx.png b/docs/assets/mobx.png
similarity index 100%
rename from docs/mobx.png
rename to docs/assets/mobx.png
diff --git a/docs/assets/observed-refs.png b/docs/assets/observed-refs.png
new file mode 100644
index 000000000..c02ffe563
Binary files /dev/null and b/docs/assets/observed-refs.png differ
diff --git a/docs/assets/overview.svg b/docs/assets/overview.svg
new file mode 100644
index 000000000..0774d28ab
--- /dev/null
+++ b/docs/assets/overview.svg
@@ -0,0 +1,405 @@
+
+
+
+
diff --git a/docs/assets/overview_bw.svg b/docs/assets/overview_bw.svg
new file mode 100644
index 000000000..a5e60f624
--- /dev/null
+++ b/docs/assets/overview_bw.svg
@@ -0,0 +1,406 @@
+
+
+
+
diff --git a/docs/talentplot.png b/docs/assets/talentplot.png
similarity index 100%
rename from docs/talentplot.png
rename to docs/assets/talentplot.png
diff --git a/docs/assets/trace-tips2.png b/docs/assets/trace-tips2.png
new file mode 100644
index 000000000..56f4c17d2
Binary files /dev/null and b/docs/assets/trace-tips2.png differ
diff --git a/docs/assets/trace.gif b/docs/assets/trace.gif
new file mode 100644
index 000000000..35f171861
Binary files /dev/null and b/docs/assets/trace.gif differ
diff --git a/docs/best/actions.md b/docs/best/actions.md
new file mode 100644
index 000000000..8645b9cec
--- /dev/null
+++ b/docs/best/actions.md
@@ -0,0 +1,212 @@
+---
+sidebar_label: async actions & flows
+title: Writing asynchronous actions
+hide_title: true
+---
+
+
+# Writing asynchronous actions
+
+
+The `action` wrapper / decorator only affects the currently running function, not functions that are scheduled (but not invoked) by the current function!
+This means that if you have a `setTimeout`, promise`.then` or `async` construction, and in that callback some more state is changed, those callbacks should be wrapped in `action` as well! There are several ways to create asynchronous actions. No approach is strictly better than the other, but this section just list different approaches you can take to writing asynchronous code.
+Let's start with a basic example:
+
+### Promises
+
+```javascript
+mobx.configure({ enforceActions: "observed" }) // don't allow state modifications outside actions
+
+class Store {
+ @observable githubProjects = []
+ @observable state = "pending" // "pending" / "done" / "error"
+
+ @action
+ fetchProjects() {
+ this.githubProjects = []
+ this.state = "pending"
+ fetchGithubProjectsSomehow().then(
+ projects => {
+ const filteredProjects = somePreprocessing(projects)
+ this.githubProjects = filteredProjects
+ this.state = "done"
+ },
+ error => {
+ this.state = "error"
+ }
+ )
+ }
+}
+```
+
+The above example would throw exceptions, as the callbacks passed to the `fetchGithubProjectsSomehow` promise are not part of the `fetchProjects` action, as actions only apply to the current stack.
+
+A first simple fix is to extract the callbacks to actions. (Note that binding using `action.bound` is important here to get a correct `this`!):
+
+```javascript
+mobx.configure({ enforceActions: "observed" })
+
+class Store {
+ @observable githubProjects = []
+ @observable state = "pending" // "pending" / "done" / "error"
+
+ @action
+ fetchProjects() {
+ this.githubProjects = []
+ this.state = "pending"
+ fetchGithubProjectsSomehow().then(this.fetchProjectsSuccess, this.fetchProjectsError)
+ }
+
+ @action.bound
+ fetchProjectsSuccess(projects) {
+ const filteredProjects = somePreprocessing(projects)
+ this.githubProjects = filteredProjects
+ this.state = "done"
+ }
+
+ @action.bound
+ fetchProjectsError(error) {
+ this.state = "error"
+ }
+}
+```
+
+Although this is clean and explicit, it might get a bit verbose with complex async flows. Alternative, you can wrap the promise callbacks with the `action` keyword. It is recommended, but not mandatory, to give them a name as well:
+
+```javascript
+mobx.configure({ enforceActions: "observed" })
+
+class Store {
+ @observable githubProjects = []
+ @observable state = "pending" // "pending" / "done" / "error"
+
+ @action
+ fetchProjects() {
+ this.githubProjects = []
+ this.state = "pending"
+ fetchGithubProjectsSomehow().then(
+ // inline created action
+ action("fetchSuccess", projects => {
+ const filteredProjects = somePreprocessing(projects)
+ this.githubProjects = filteredProjects
+ this.state = "done"
+ }),
+ // inline created action
+ action("fetchError", error => {
+ this.state = "error"
+ })
+ )
+ }
+}
+```
+
+### The `runInAction` utility
+
+A downside of inline actions is that TypeScript does not apply type inference on them, so you would have type all your callbacks.
+Instead of creating an action for the entire callback, you can also run only the state modifying part of the callback in an action.
+The advantage of this pattern is that it encourages you to not litter the place with `action`, but rather put all the state modifications as much as possible at the end of the whole process:
+
+```javascript
+mobx.configure({ enforceActions: "observed" })
+
+class Store {
+ @observable githubProjects = []
+ @observable state = "pending" // "pending" / "done" / "error"
+
+ @action
+ fetchProjects() {
+ this.githubProjects = []
+ this.state = "pending"
+ fetchGithubProjectsSomehow().then(
+ projects => {
+ const filteredProjects = somePreprocessing(projects)
+ // put the 'final' modification in an anonymous action
+ runInAction(() => {
+ this.githubProjects = filteredProjects
+ this.state = "done"
+ })
+ },
+ error => {
+ // the alternative ending of this process:...
+ runInAction(() => {
+ this.state = "error"
+ })
+ }
+ )
+ }
+}
+```
+
+Note that `runInAction`'s can also be given a name as first argument. `runInAction(f)` is in fact just sugar for `action(f)()`
+
+### async / await
+
+Async / await based functions can initially seem confusing when starting with actions.
+Because lexically they appear to synchronous functions, it gives the impression that `@action` applies to the entire function.
+Which is of course not the case, as async / await is just syntactic sugar around a promise based process.
+As a result, `@action` only applies to the code block until the first `await`.
+And after each `await` a new asynchronous function is started, so after each `await`, state modifying code should be wrapped as action.
+This is where `runInAction` comes in handy again:
+
+```javascript
+mobx.configure({ enforceActions: "observed" })
+
+class Store {
+ @observable githubProjects = []
+ @observable state = "pending" // "pending" / "done" / "error"
+
+ @action
+ async fetchProjects() {
+ this.githubProjects = []
+ this.state = "pending"
+ try {
+ const projects = await fetchGithubProjectsSomehow()
+ const filteredProjects = somePreprocessing(projects)
+ // after await, modifying state again, needs an actions:
+ runInAction(() => {
+ this.state = "done"
+ this.githubProjects = filteredProjects
+ })
+ } catch (error) {
+ runInAction(() => {
+ this.state = "error"
+ })
+ }
+ }
+}
+```
+
+### flows
+
+However, a nicer approach is to use the built-in concept of `flow`s. They use generators. Which might look scary in the beginning, but it works the same as `async` / `await`. Just use `function *` instead of `async` and `yield` instead of `await`.
+The advantage of `flow` is that it is syntactically very close to async / await (with different keywords), and no manually action wrapping is needed for async parts, resulting in very clean code.
+
+`flow` can be used only as function and not as decorator.
+`flow` integrates neatly with MobX development tools, so that it is easy to trace the process of the async function.
+
+```javascript
+mobx.configure({ enforceActions: "observed" })
+
+class Store {
+ @observable githubProjects = []
+ @observable state = "pending"
+
+ fetchProjects = flow(function * () { // <- note the star, this a generator function!
+ this.githubProjects = []
+ this.state = "pending"
+ try {
+ const projects = yield fetchGithubProjectsSomehow() // yield instead of await
+ const filteredProjects = somePreprocessing(projects)
+ // the asynchronous blocks will automatically be wrapped in actions and can modify state
+ this.state = "done"
+ this.githubProjects = filteredProjects
+ } catch (error) {
+ this.state = "error"
+ }
+ })
+}
+```
+
+#### Flows can be cancelled
+
+Flows are cancellable, that means that you can call `cancel()` on the returned promise. This will stop the generator immediately, but any finally clause will still be processed. The returned promise itself will reject with `FLOW_CANCELLED`.
diff --git a/docs/best/decorators.md b/docs/best/decorators.md
new file mode 100644
index 000000000..28188ee7d
--- /dev/null
+++ b/docs/best/decorators.md
@@ -0,0 +1,192 @@
+---
+sidebar_label: How to (not) use decorator syntax
+title: How to (not) use decorators
+hide_title: true
+---
+
+
+# How to (not) use decorators
+
+
+Using ES.next decorators in MobX is optional. This section explains how to use them, or how to avoid them.
+
+Advantages of using decorator syntax:
+
+* Minimizes boilerplate, declarative.
+* Easy to use and read. A majority of the MobX users use them.
+
+Disadvantages of using decorator syntax:
+
+* Stage-2 ES.next feature
+* Requires a little setup and transpilation, only supported with Babel / Typescript transpilation so far
+
+You can approach using decorators in two ways in MobX
+
+1. Enable the currently experimental decorator syntax in your compiler (read on)
+2. Don't enable decorator syntax, but leverage the MobX built-in utility `decorate` to apply decorators to your classes / objects.
+
+Using decorator syntax:
+
+```javascript
+import { observable, computed, action } from "mobx";
+
+class Timer {
+ @observable start = Date.now();
+ @observable current = Date.now();
+
+ @computed
+ get elapsedTime() {
+ return this.current - this.start + "milliseconds";
+ }
+
+ @action
+ tick() {
+ this.current = Date.now();
+ }
+}
+```
+
+Using the `decorate` utility:
+
+```javascript
+import { observable, computed, action, decorate } from "mobx";
+
+class Timer {
+ start = Date.now();
+ current = Date.now();
+
+ get elapsedTime() {
+ return this.current - this.start + "milliseconds";
+ }
+
+ tick() {
+ this.current = Date.now();
+ }
+}
+decorate(Timer, {
+ start: observable,
+ current: observable,
+ elapsedTime: computed,
+ tick: action
+});
+```
+
+For applying multiple decorators on a single property, you can pass an array of decorators. The decorators application order is from right to left.
+
+```javascript
+import { decorate, observable } from "mobx"
+import { serializable, primitive } from "serializr"
+import persist from "mobx-persist";
+
+class Todo {
+ id = Math.random();
+ title = "";
+ finished = false;
+}
+decorate(Todo, {
+ title: [serializable(primitive), persist("object"), observable],
+ finished: [serializable(primitive), observable]
+})
+```
+Note: Not all decorators can be composed together, and this functionality is just best-effort. Some decorators affect the instance directly and can 'hide' the effect of other decorators that only change the prototype.
+
+---
+
+The `observer` function from `mobx-react` is both a decorator and a function, that means that all these syntax variants will work:
+
+```javascript
+@observer
+class Timer extends React.Component {
+ /* ... */
+}
+
+const Timer = observer(class Timer extends React.Component {
+ /* ... */
+})
+
+const Timer = observer((props) => (
+ /* rendering */
+))
+```
+
+## Enabling decorator syntax
+
+If you want to use decorators follow the following steps.
+
+**TypeScript**
+
+Enable the compiler option `"experimentalDecorators": true` in your `tsconfig.json`.
+
+**Babel 6: using `babel-preset-mobx`**
+
+A more convenient way to setup Babel for usage with mobx is to use the [`mobx`](https://github.com/zwhitchcox/babel-preset-mobx) preset, that incorporates decorators and several other plugins typically used with mobx:
+
+```
+npm install --save-dev babel-preset-mobx
+```
+
+.babelrc:
+
+```json
+{
+ "presets": ["mobx"]
+}
+```
+
+**Babel 6: manually enabling decorators**
+
+To enable support for decorators without using the mobx preset, follow the following steps.
+Install support for decorators: `npm i --save-dev babel-plugin-transform-decorators-legacy`. And enable it in your `.babelrc` file:
+
+```json
+{
+ "presets": ["es2015", "stage-1"],
+ "plugins": ["transform-decorators-legacy"]
+}
+```
+
+Note that the order of plugins is important: `transform-decorators-legacy` should be listed _first_.
+Having issues with the babel setup? Check this [issue](https://github.com/mobxjs/mobx/issues/105) first.
+
+**Babel 7**
+
+Install support for decorators: `npm i --save-dev @babel/plugin-proposal-class-properties @babel/plugin-proposal-decorators`. And enable it in your `.babelrc` file:
+
+```json
+{
+ "plugins": [
+ ["@babel/plugin-proposal-decorators", { "legacy": true}],
+ ["@babel/plugin-proposal-class-properties", { "loose": true}]
+ ]
+}
+```
+
+Note that the `legacy` mode is important (as is putting the decorators proposal first). Non-legacy mode is [WIP](https://github.com/mobxjs/mobx/pull/1732).
+
+## Decorator syntax and Create React App (v1)
+
+* Decorators are not supported out of the box in `create-react-app@1.*`. To fix this, you can either use the `decorate` utility, eject, or use the [react-app-rewired](https://github.com/timarney/react-app-rewired/tree/master/packages/react-app-rewire-mobx) package.
+
+## Decorator syntax and Create React App (v2)
+
+* Decorators are only supported out of the box when using TypeScript in `create-react-app@^2.1.1`. In older versions or when using vanilla JavaScript use either the `decorate` utility, eject, or the [customize-cra](https://github.com/arackaf/customize-cra) package.
+
+---
+
+## Disclamer: Limitations of decorator syntax:
+
+_The current transpiler implementations of decorator syntax are quite limited and don't behave exactly the same.
+Also, many compositional patterns are currently not possible with decorators, until the stage-2 proposal has been implemented by all transpilers.
+For this reason the scope of decorator syntax support in MobX is currently scoped to make sure that the supported features
+behave consistently accross all environments_
+
+The following patterns are not officially supported by the MobX community:
+
+* Redefining decorated class members in inheritance trees
+* Decorating static class members
+* Combining decorators provided by MobX with other decorators
+* Hot module reloading (HMR) / React-hot-loader might not work as expected
+
+Decorated properties might not be visible yet on class instances as _own_ property until the first read / write to that property occurred.
+
+(N.B.: not supported doesn't mean it doesn't work, it means that if it doesn't work, reported issues will not be processed until the official spec has been moved forward)
diff --git a/docs/best/devtools.md b/docs/best/devtools.md
new file mode 100644
index 000000000..473daa59c
--- /dev/null
+++ b/docs/best/devtools.md
@@ -0,0 +1,43 @@
+---
+sidebar_label: MobX + React DevTools
+title: MobX + React DevTools
+hide_title: true
+---
+
+# MobX + React DevTools
+
+
+
+ egghead.io lesson 2: devtools
+
+
+
+
+ Hosted on egghead.io
+
+
+
+MobX ships with DevTools that can be used to track the rendering behavior and data dependencies of your app.
+
+
+
+## Usage:
+
+Install:
+
+`npm install mobx-react-devtools`
+
+To enable devtools, import and render the devtools somewhere in your codebase.
+
+```JS
+import DevTools from 'mobx-react-devtools'
+
+const App = () => (
+
+ ...
+
+
+)
+```
+
+For more details check the [mobx-react-devtools](https://github.com/mobxjs/mobx-react-devtools) repository.
diff --git a/docs/best/pitfalls.md b/docs/best/pitfalls.md
new file mode 100644
index 000000000..3343c49d6
--- /dev/null
+++ b/docs/best/pitfalls.md
@@ -0,0 +1,292 @@
+---
+sidebar_label: Common Pitfalls & Best Practices
+title: Common pitfalls & best practices
+hide_title: true
+---
+
+# Common pitfalls & best practices
+
+
+Stuck with MobX? This section contains a list of common issues people new to MobX might run into.
+
+#### Importing from wrong location
+
+Because MobX ships with typescript typings out of the box, some import autocompleting tools (at least in VSCode) have the habit of auto completing with a wrong import, like
+
+```javascript
+// wrong
+import { observable } from "mobx/lib/mobx"
+```
+
+This is incorrect but will not always immediately lead to runtime errors. So be aware. The only correct way of importing anything from the `mobx` package is:
+
+```javascript
+// correct
+import { observable } from "mobx"
+```
+
+#### Issues with decorators?
+
+For setup tips and limitations on decorators, check the [decorators](decorators.md) page
+
+#### `Array.isArray(observable([1,2,3])) === false`
+
+_This limitation applies to MobX 4 and lower only_
+
+In ES5 there is no way to reliably inherit from arrays, and hence observable arrays inherit from objects.
+This means that regularly libraries are not able to recognize observable arrays as normal arrays (like lodash, or built-in operations like `Array.concat`).
+This can simply be fixed by passing calling `observable.toJS()` or `observable.slice()` before passing the array to another library.
+As long as the external library has no intent to modify the array, this will further work completely as expected.
+You can use `isObservableArray(observable)` to check whether something is an observable array.
+
+#### `object.someNewProp = value` is not picked up
+
+_This limitation applies to MobX 4 and lower_
+
+_In MobX 5 this limitation applies to class instances and other objects that were **not** created using `observable()` / `observable.object()`._
+
+MobX observable _objects_ do not detect or react to property assignments that weren't declared observable before.
+So MobX observable objects act as records with predefined keys.
+You can use `extendObservable(target, props)` to introduce new observable properties to an object.
+However object iterators like `for .. in` or `Object.keys()` won't react to this automatically.
+If you need a dynamically keyed object in MobX 4 and lower, for example to store users by id, create observable _maps_ using [`observable.map`](../refguide/map.md) or use the utility methods as exposed by the [Object API](../refguide/object-api.md).
+For more info see [what will MobX react to?](react.md).
+
+### Use `@observer` on all components that render `@observable`s.
+
+`@observer` only enhances the component you are decorating, not the components used inside it.
+So usually all your components should be decorated. Don't worry, this is not inefficient, in contrast, more `observer` components make rendering more efficient.
+
+### Don't copy observables properties and store them locally
+
+Observer components only track data that is accessed _during_ the render method. A common mistake is that data plucked of from an observable property and stored will for that reason not be tracked:
+
+```javascript
+class User {
+ @observable name
+}
+
+class Profile extends React.Component {
+ name
+
+ componentWillMount() {
+ // Wrong
+ // This dereferences user.name and just copies the value once! Future updates will not be tracked, as lifecycle hooks are not reactive
+ // assignments like these create redundant data
+ this.name = this.props.user.name
+ }
+
+ render() {
+ return
{this.name}
+ }
+}
+```
+
+The correct approach is either by not storing the values of observables locally (obviously, the above example is simple but contrived), or by defining them as computed property:
+
+```javascript
+class User {
+ @observable name
+}
+
+class Profile extends React.Component {
+ @computed get name() {
+ // correct; computed property will track the `user.name` property
+ return this.props.user.name
+ }
+
+ render() {
+ return
{this.name}
+ }
+}
+```
+
+### Render callbacks are *not* part of the render method
+
+Because `observer` only applies to exactly the `render` function of the current component; passing a render callback or component to a child component doesn't become reactive automatically.
+For more details, see the [what will Mobx react to](https://github.com/mobxjs/mobx/blob/gh-pages/docs/best/react.md#mobx-only-tracks-data-accessed-for-observer-components-if-they-are-directly-accessed-by-render) guide.
+
+### Dereference values as late as possible
+
+MobX can do a lot, but it cannot make primitive values observable (although it can wrap them in an object see [boxed observables](../refguide/boxed.md)).
+So it is not the _values_ that are observable, but the _properties_ of an object. This means that `@observer` actually reacts to the fact that you dereference a value.
+So in our above example, the `Timer` component would **not** react if it was initialized as follows:
+
+```javascript
+ReactDOM.render(, document.body)
+```
+
+In this snippet just the current value of `secondsPassed` is passed to the `Timer`, which is the immutable value `0` (all primitives are immutable in JS).
+That number won't change anymore in the future, so `Timer` will never update. It is the property `secondsPassed` that will change in the future,
+so we need to access it *in* the component. Or in other words: always try to pass the owning object of an observable property.
+For more info see [what will MobX react to?](react.md).
+
+#### Computed values run more often than expected
+
+If a computed property is *not* in use by some reaction (`autorun`, `observer` etc), computed expressions will be evaluated lazily; each time their value is requested (so they just act as normal property).
+Computed values will only track their dependencies if they are observed.
+This allows MobX to automatically suspend computations that are not actively in use.
+See this [blog](https://medium.com/@mweststrate/becoming-fully-reactive-an-in-depth-explanation-of-mobservable-55995262a254) or [issue #356](https://github.com/mobxjs/mobx/issues/356) for an explanation.
+So if you fiddle arounds, computed properties might not seem efficient. But when applied in a project that uses `observer`, `autorun` etc, they become very efficient.
+
+MobX `computed`s will automatically be kept alive during transactions as well, see PRs: [#452](https://github.com/mobxjs/mobx/pull/452) and [#489](https://github.com/mobxjs/mobx/pull/489)
+
+To force computed values to stay alive one can use the `keepAlive: true` option, but note that this can potentially create memory leaks.
+
+#### Always dispose reactions
+
+All forms of `autorun`, `observe` and `intercept` will only be garbage collected if all objects they observe are garbage collected themselves.
+So it is recommend to use the disposer function that is returned from these methods to stop them when you no longer need them.
+Usually for `observe` and `intercept` it is not strictly necessary to dispose them if when targed `this`.
+For reactions like `autorun` it is more tricky, as they might observe many different observables, and as long as one of them is still in scope,
+the reaction will remain in scope which means that all other observables it uses are also kept alive to support future recomputions.
+So make sure to always dispose your reactions when you no longer need them!
+
+Example:
+
+```javascript
+const VAT = observable(1.20)
+
+class OrderLIne {
+ @observable price = 10;
+ @observable amount = 1;
+ constructor() {
+ // this autorun will be GC-ed together with the current orderline instance
+ this.handler = autorun(() => {
+ doSomethingWith(this.price * this.amount)
+ })
+ // this autorun won't be GC-ed together with the current orderline instance
+ // since VAT keeps a reference to notify this autorun,
+ // which in turn keeps 'this' in scope
+ this.handler = autorun(() => {
+ doSomethingWith(this.price * this.amount * VAT.get())
+ })
+ // So, to avoid subtle memory issues, always call..
+ this.handler()
+ // When the reaction is no longer needed!
+ }
+}
+
+```
+
+#### I have a weird exception when using `@observable` in a React component.
+
+The following exception: `Uncaught TypeError: Cannot assign to read only property '__mobxLazyInitializers' of object` occurs when using a `react-hot-loader` that does not support decorators.
+Either use `extendObservable` in `componentWillMount` instead of `@observable`, or upgrade to `react-hot-loader` `"^3.0.0-beta.2"` or higher.
+
+#### The display name of react components is not set
+
+If you use `export const MyComponent = observer(props =>
hi
)`, no display name will be visible in the devtools.
+The following approaches can be used to fix this:
+
+```javascript
+// 1 (set displayName explicitly)
+export const MyComponent = observer(props =>
hi
)
+myComponent.displayName = "MyComponent"
+
+// 2 (MobX infers component name from function name)
+export const MyComponent = observer(function MyComponent(props) { return
hi
})
+
+// 3 (transpiler will infer component name from variable name)
+const _MyComponent = props =>
+export default observer(MyComponent)
+```
+
+See also: http://mobxjs.github.io/mobx/best/stateless-HMR.html or [#141](https://github.com/mobxjs/mobx/issues/141#issuecomment-228457886).
+
+#### The propType of an observable array is object
+
+Observable arrays are actually objects, so they comply to `propTypes.object` instead of `array`.
+`mobx-react` provides its explicit `PropTypes` for observable data structures.
+
+#### Rendering ListViews in React Native
+
+`ListView.DataSource` in React Native expects real arrays. Observable arrays are actually objects, make sure to `.slice()` them first before passing to list views. Furthermore, `ListView.DataSource` itself can be moved to the store and have it automatically updated with a `@computed`, this step can also be done on the component level.
+
+```javascript
+class ListStore {
+ @observable list = [
+ 'Hello World!',
+ 'Hello React Native!',
+ 'Hello MobX!'
+ ];
+
+ ds = new ListView.DataSource({ rowHasChanged: (r1, r2) => r1 !== r2 });
+
+ @computed get dataSource() {
+ return this.ds.cloneWithRows(this.list.slice());
+ }
+}
+
+const listStore = new ListStore();
+
+@observer class List extends Component {
+ render() {
+ return (
+ {row}}
+ enableEmptySections={true}
+ />
+ );
+ }
+}
+```
+
+For more info see [#476](https://github.com/mobxjs/mobx/issues/476)
+
+#### Declaring propTypes might cause unnecessary renders in dev mode
+
+See: https://github.com/mobxjs/mobx-react/issues/56
+
+#### Don't decorate (some) React lifecycle methods as `action.bound` on `Observer` React components
+
+As mentioned above, all React components which used observable data should be marked as `@observer` Additionally, if you are going to be modifying any observable data in a function in your React component, that function should be marked as `@action`. Additionally, if you want `this` to refer to the instance of your component class, you should use `@action.bound`. Consider the following class:
+
+```js
+class ExampleComponent extends React.Component {
+ @observable disposer // <--- this value is disposed in addActed
+
+ @action.bound
+ addActed() {
+ this.dispose()
+ }
+
+ @action.bound
+ componentDidMount() {
+ this.disposer = this.observe(....) //<-- details don't matter
+ }
+}
+```
+
+If you call `addActed()` on a mounted `ExampleComponent`, the disposer is called.
+
+On the other hand, consider the following:
+
+```js
+class ExampleComponent extends React.Component {
+ @observable disposer // <--- this value is disposed in addActed
+
+ @action.bound
+ componentWillUnmount() {
+ this.dispose()
+ }
+
+ @action.bound
+ componentDidMount() {
+ this.disposer = this.observe(....) //<-- details don't matter
+ }
+}
+```
+
+In this case, your `disposer` will never be called! The reason is that the mixin for making the `ExampleComponent` an `observer`, the modifies the `componentWillUnmount` function which changes `this` to an unexpected `React.Component` instance (don't know which one). To work around this, declare`componentWillUnmount()` as follows:
+
+```js
+componentWillUnmount() {
+ runInAction(() => this.dispose())
+}
+```
diff --git a/docs/best/react-performance.md b/docs/best/react-performance.md
new file mode 100644
index 000000000..7312534d2
--- /dev/null
+++ b/docs/best/react-performance.md
@@ -0,0 +1,151 @@
+---
+sidebar_label: Optimizing React components
+title: Optimizing rendering React components
+hide_title: true
+---
+
+# Optimizing rendering React components
+
+
+MobX is very fast, [often even faster than Redux](https://twitter.com/mweststrate/status/718444275239882753). But here are some tips to get most out of React and MobX. Note that most tips apply to React in general and are not specific for MobX.
+
+## Use many small components
+
+`@observer` components will track all values they use and re-render if any of them changes.
+So the smaller your components are, the smaller the change they have to re-render; it means that more parts of your user interface have the possibility to render independently of each other.
+
+## Render lists in dedicated components
+
+This is especially true when rendering big collections.
+React is notoriously bad at rendering large collections as the reconciler has to evaluate the components produced by a collection on each collection change.
+It is therefore recommended to have components that just map over a collection and render it, and render nothing else:
+
+Bad:
+
+```javascript
+@observer class MyComponent extends Component {
+ render() {
+ const {todos, user} = this.props;
+ return (
+ {user.name}
+
+ {todos.map(todo => )}
+
+
)
+ }
+}
+```
+
+In the above listing React will unnecessarily need to reconcile all TodoView components when the `user.name` changes. They won't re-render, but the reconcile process is expensive in itself.
+
+Good:
+
+```javascript
+@observer class MyComponent extends Component {
+ render() {
+ const {todos, user} = this.props;
+ return (
)
+ }
+}
+```
+
+## Don't use array indexes as keys
+
+Don't use array indexes or any value that might change in the future as key. Generate ids for your objects if needed.
+See also this [blog](https://medium.com/@robinpokorny/index-as-a-key-is-an-anti-pattern-e0349aece318).
+
+## Dereference values late
+
+When using `mobx-react` it is recommended to dereference values as late as possible.
+This is because MobX will re-render components that dereference observable values automatically.
+If this happens deeper in your component tree, less components have to re-render.
+
+Fast:
+
+``
+
+Slower:
+
+``.
+
+There is nothing wrong to the latter, but a change in the `name` property will, in the first case, trigger only the `DisplayName` to re-render, while in the latter, the owner of the component has to re-render. If rendering the owning component is fast enough, that approach will work well.
+
+You may notice that in order to gain the best possible performance, you'd have to create lots of small observer components where each would be customized to render some different part of data, for example:
+
+`const PersonNameDisplayer = observer((props) => )`
+
+`const CarNameDisplayer = observer((props) => )`
+
+`const ManufacturerNameDisplayer = observer((props) => )`
+
+This is a valid option, but may become tedious if you have lots of data of different shape. An alternative is using a function that returns the data that you want your `*Displayer` to render:
+
+`const GenericNameDisplayer = observer((props) => )`
+
+Then, you may use the component like this:
+
+```javascript
+render() {
+ const { person, car } = this.props;
+ return (
+ <>
+ person.name} />
+
+
+
+ );
+}
+
+getManufacturerNameTracked = () => this.props.car.manufacturer.name;
+
+...
+class Car {
+ @observable model
+ getModelTracked = () => this.model
+}
+```
+
+This approach will allow `GenericNameDisplayer` to be reused throughout your application to render any name. Now, what remains to be solved is the placement of those functions: the sample shows three possibilities - you may create the function directly in the render method (which is not considered a good practice), you may place the function in the component (as with `getManufacturerNameTracked`), or you may place the function directly on the object that contains the data (as with `getModelTracked`).
+
+## Bind functions early
+
+This tip applies to React in general and libraries using `PureRenderMixin` especially, try to avoid creating new closures in render methods.
+
+See also these resources:
+* [Autobinding with property initializers](https://facebook.github.io/react/blog/2015/01/27/react-v0.13.0-beta-1.html#autobinding)
+* [ESLint rule for no-bind](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-no-bind.md)
+
+
+Bad:
+
+```javascript
+render() {
+ return { alert('hi') }} />
+}
+```
+
+Good:
+
+```javascript
+render() {
+ return
+}
+
+handleClick = () => {
+ alert('hi')
+}
+```
+
+The bad example will always yield the `shouldComponent` of `PureRenderMixin` used in `MyWidget` to always yield false as you pass a new function each time the parent is re-rendered.
diff --git a/docs/best/react.md b/docs/best/react.md
new file mode 100644
index 000000000..a4eb6d288
--- /dev/null
+++ b/docs/best/react.md
@@ -0,0 +1,469 @@
+---
+title: What does MobX react to?
+sidebar_label: Understanding what MobX reacts to
+hide_title: true
+---
+
+# What does MobX react to?
+
+
+MobX usually reacts to exactly the things you expect it to.
+Which means that in 90% of your use cases mobx "just works".
+However, at some point you will encounter a case where it might not do what you expected.
+At that point it is invaluable to understand how MobX determines what to react to.
+
+> MobX reacts to any _existing_ **observable** _property_ that is read during the execution of a tracked function.
+
+* _"reading"_ is dereferencing an object's property, which can be done through "dotting into" it (eg. `user.name`) or using the bracket notation (eg. `user['name']`).
+* _"trackable functions"_ are the expression of `computed`, the `render()` method of an observer component, and the functions that are passed as the first param to `when`, `reaction` and `autorun`.
+* _"during"_ means that only those observables that are being read while the function is executing are tracked. It doesn't matter whether these values are used directly or indirectly by the tracked function.
+
+In other words, MobX will not react to:
+ * Values that are obtained from observables, but outside a tracked function
+ * Observables that are read in an asynchronously invoked code block
+
+## MobX tracks property access, not values
+
+To elaborate on the above rules with an example, suppose that you have the following observable data structure (`observable` applies itself recursively by default, so all fields in this example are observable):
+
+```javascript
+let message = observable({
+ title: "Foo",
+ author: {
+ name: "Michel"
+ },
+ likes: [
+ "John", "Sara"
+ ]
+})
+```
+
+In memory that looks as follows. The green boxes indicate _observable_ properties. Note that the _values_ themselves are not observable!
+
+
+
+Now what MobX basically does is recording which _arrows_ you use in your function. After that, it will re-run whenever one of these _arrows_ changes; when they start to refer to something else.
+
+## Examples
+
+Let's show that with a bunch of examples (based on the `message` variable defined above):
+
+#### Correct: dereference inside the tracked function
+
+```javascript
+autorun(() => {
+ console.log(message.title)
+})
+message.title = "Bar"
+```
+
+This will react as expected, the `.title` property was dereferenced by the autorun, and changed afterwards, so this change is detected.
+
+You can verify what MobX will track by calling [`trace()`](../reguide/trace) inside the tracked function. In the case of the above function it will output the following:
+
+```javascript
+const disposer = autorun(() => {
+ console.log(message.title)
+ trace()
+})
+
+// Outputs:
+// [mobx.trace] 'Autorun@2' tracing enabled
+
+message.title = "Hello"
+// [mobx.trace] 'Autorun@2' is invalidated due to a change in: 'ObservableObject@1.title'
+```
+
+It is also possible to get the internal dependency (or observer) tree by using the designated utilities for that:
+
+```javascript
+getDependencyTree(disposer) // prints the dependency tree of the reaction coupled to the disposer
+// { name: 'Autorun@4',
+// dependencies: [ { name: 'ObservableObject@1.title' } ] }
+```
+
+#### Incorrect: changing a non-observable reference
+
+```javascript
+autorun(() => {
+ console.log(message.title)
+})
+message = observable({ title: "Bar" })
+```
+
+This will **not** react. `message` was changed, but `message` is not an observable, just a variable which _refers to_ an observable,
+but the variable (reference) itself is not observable.
+
+
+#### Incorrect: dereference outside a tracked function
+
+```javascript
+var title = message.title;
+autorun(() => {
+ console.log(title)
+})
+message.title = "Bar"
+```
+
+This will **not** react. `message.title` was dereferenced outside the `autorun`, and just contains the value of `message.title` at the moment of dereferencing (the string `"Foo"`).
+`title` is not an observable so `autorun` will never react.
+
+#### Correct: dereference inside the tracked function
+
+```javascript
+autorun(() => {
+ console.log(message.author.name)
+})
+message.author.name = "Sara";
+message.author = { name: "John" };
+```
+
+This will react to both changes. Both `author` and `author.name` are dotted into, allowing MobX to track these references.
+
+#### Incorrect: store a local reference to an observable object without tracking
+
+```javascript
+const author = message.author;
+autorun(() => {
+ console.log(author.name)
+})
+message.author.name = "Sara";
+message.author = { name: "John" };
+```
+
+The first change will be picked up, `message.author` and `author` are the same object, and the `.name` property is dereferenced in the autorun.
+However the second change will **not** be picked up, the `message.author` relation is not tracked by the `autorun`. Autorun is still using the "old" `author`.
+
+#### Common pitfall: console.log
+
+```javascript
+const message = observable({ title: "hello" })
+
+autorun(() => {
+ console.log(message)
+})
+
+// Won't trigger a re-run
+message.title = "Hello world"
+```
+
+In the above example, the updated message title won't be printed, because it is not used inside the autorun.
+The autorun only depends on `message`, which is not an observable, but a constant. In other words, as far as MobX is concerned, `title` is not used in- and hence not relevant for the `autorun`
+
+The fact that `console.log` will print the message title is misleading here; `console.log` is an asynchronous api that only will format its parameters later in time, for which reason the autorun won't be tracking what data the console.log is accessing. For that reason make sure to always pass immutable data or defensive copies to `console.log`.
+
+The following solutions however, will all react to `message.title`:
+
+```javascript
+autorun(() => {
+ console.log(message.title) // clearly, the `.title` observable is used
+})
+
+autorun(() => {
+ console.log(mobx.toJS(message)) // toJS creates a deep clone, and thus will read the message
+})
+
+autorun(() => {
+ console.log({...message}) // creates a shallow clone, also using `.title` in the process
+})
+
+autorun(() => {
+ console.log(JSON.stringify(message)) // also reads the entire structure
+})
+```
+
+#### Correct: access array properties in tracked function
+
+
+```javascript
+autorun(() => {
+ console.log(message.likes.length);
+})
+message.likes.push("Jennifer");
+```
+
+This will react as expected. `.length` counts towards a property.
+Note that this will react to *any* change in the array.
+Arrays are not tracked per index / property (like observable objects and maps) but as a whole.
+
+#### Incorrect: access out-of-bounds indices in tracked function
+
+```javascript
+autorun(() => {
+ console.log(message.likes[0]);
+})
+message.likes.push("Jennifer");
+```
+
+This will react with the above sample data, array indexers count as property access. But **only** if the provided `index < length`.
+MobX will not track not-yet-existing indices or object properties (except when using maps).
+So always guard your array index based access with a `.length` check.
+
+#### Correct: access array functions in tracked function
+
+```javascript
+autorun(() => {
+ console.log(message.likes.join(", "));
+})
+message.likes.push("Jennifer");
+```
+
+This will react as expected. All array functions that do not mutate the array are tracked automatically.
+
+---
+
+```javascript
+autorun(() => {
+ console.log(message.likes.join(", "));
+})
+message.likes[2] = "Jennifer";
+```
+
+This will react as expected. All array index assignments are detected, but only if `index <= length`.
+
+#### Incorrect: "use" an observable but without accessing any of its properties
+
+```javascript
+autorun(() => {
+ message.likes;
+})
+message.likes.push("Jennifer");
+```
+
+This will **not** react. Simply because the `likes` array itself is not being used by the `autorun`, only the reference to the array.
+So in contrast, `messages.likes = ["Jennifer"]` would be picked up; that statement does not modify the array, but the `likes` property itself.
+
+#### Using non-observable object properties
+
+
+```javascript
+autorun(() => {
+ console.log(message.postDate)
+})
+message.postDate = new Date()
+```
+
+_MobX 4_
+
+This will **not** react. MobX can only track observable properties, and 'postDate' has not been defined as observable property above.
+However, it is possible to use the `get` and `set` methods as exposed by MobX to work around this:
+
+```javascript
+autorun(() => {
+ console.log(get(message, "postDate"))
+})
+set(message, "postDate", new Date())
+```
+
+_MobX 5_
+
+In MobX 5 this **will** react, as MobX 5 can track not-yet existing properties.
+Note that this is only done for objects created with `observable` or `observable.object`.
+New properties on class instances will not be made observable automatically.
+
+#### [MobX 4 and lower] Incorrect: using not yet existing observable object properties
+
+```javascript
+autorun(() => {
+ console.log(message.postDate)
+})
+extendObservable(message, {
+ postDate: new Date()
+})
+```
+
+This will **not** react. MobX will not react to observable properties that did not exist when tracking started.
+If the two statements are swapped, or if any other observable causes the `autorun` to re-run, the `autorun` will start tracking the `postDate` as well.
+
+
+#### Correct: using not yet existing map entries
+
+```javascript
+const twitterUrls = observable.map({
+ "John": "twitter.com/johnny"
+})
+
+autorun(() => {
+ console.log(twitterUrls.get("Sara"))
+})
+twitterUrls.set("Sara", "twitter.com/horsejs")
+```
+
+This **will** react. Observable maps support observing entries that may not exist.
+Note that this will initially print `undefined`.
+You can check for the existence of an entry first by using `twitterUrls.has("Sara")`.
+So for dynamically keyed collections, always use observable maps.
+
+#### Correct: using MobX utilities to read / write to objects
+
+Since MobX 4 it is also possible to use observable objects as dynamic collection, if they are read / updated by using the mobx apis, so that mobx can keep track of the property changes. The following will react as well:
+
+
+```javascript
+import { get, set, observable } from "mobx"
+
+const twitterUrls = observable.object({
+ "John": "twitter.com/johnny"
+})
+
+autorun(() => {
+ console.log(get(twitterUrls, "Sara")) // get can track not yet existing properties
+})
+set(twitterUrls, { "Sara" : "twitter.com/horsejs"})
+```
+
+See the [object manipulation api](https://mobx.js.org/refguide/api.html#direct-observable-manipulation) for more details
+
+## MobX only tracks synchronously accessed data
+
+```javascript
+function upperCaseAuthorName(author) {
+ const baseName = author.name;
+ return baseName.toUpperCase();
+}
+autorun(() => {
+ console.log(upperCaseAuthorName(message.author))
+})
+message.author.name = "Chesterton"
+```
+This will react. Even though `author.name` is not dereferenced by the thunk passed to `autorun` itself,
+MobX will still track the dereferencing that happens in `upperCaseAuthorName`,
+because it happens _during_ the execution of the autorun.
+
+----
+
+```javascript
+autorun(() => {
+ setTimeout(
+ () => console.log(message.likes.join(", ")),
+ 10
+ )
+})
+message.likes.push("Jennifer");
+```
+
+This will **not** react, during the execution of the `autorun` no observables where accessed, only during the `setTimeout`.
+In general this is quite obvious and rarely causes issues.
+
+## MobX only tracks data accessed for `observer` components if they are directly accessed by `render`
+
+A common mistake made with `observer` is that it doesn't track data that syntactically seems parent of the `observer` component,
+but in practice is actually rendered out by a different component. This often happens when render callbacks of components are passed in first class to another component.
+
+Take for example the following contrived example:
+
+```javascript
+const MyComponent = observer(({ message }) =>
+
{message.title}
}
+ />
+)
+
+message.title = "Bar"
+```
+
+At first glance everything might seem ok here, except that the `
` is actually not rendered by `MyComponent` (which has a tracked rendering), but by `SomeContainer`.
+So to make sure that the title of `SomeContainer` correctly reacts to a new `message.title`, `SomeContainer` should be an `observer` as well.
+
+If `SomeContainer` comes from an external lib, this is often not under your own control. In that case you can address this by either wrapping the `div` in its own stateless `observer` based component, or by leveraging the `` component:
+
+```javascript
+const MyComponent = observer(({ message }) =>
+ }
+ />
+)
+
+const TitleRenderer = observer(({ message }) =>
+
{message.title}
}
+)
+
+message.title = "Bar"
+```
+
+Alternatively, to avoid creating additional components, it is also possible to use the mobx-react built-in `Observer` component, which takes no arguments, and a single render function as children:
+
+```javascript
+const MyComponent = ({ message }) =>
+
+
+ {() =>
{message.title}
}
+
+ }
+ />
+
+message.title = "Bar"
+```
+
+## Avoid caching observables in local fields
+
+A common mistake is to store local variables that dereference observables, and then expect components to react. For example:
+
+```javascript
+@observer class MyComponent extends React.component {
+ author;
+ constructor(props) {
+ super(props)
+ this.author = props.message.author;
+ }
+
+ render() {
+ return
{this.author.name}
+ }
+}
+```
+
+This component will react to changes in the `author`'s name, but it won't react to changing the `.author` of the `message` itself! Because that dereferencing happened outside `render()`,
+which is the only tracked function of an `observer` component.
+Note that even marking the `author` component field as `@observable` field does not solve this; that field is still assigned only once.
+This can simply be solved by doing the dereferencing inside `render()`, or by introducing a computed property on the component instance:
+
+```javascript
+@observer class MyComponent extends React.component {
+ @computed get author() {
+ return this.props.message.author
+ }
+// ...
+```
+
+## How multiple components will render
+
+Suppose that the following components are used to render our above `message` object.
+
+```javascript
+const Message = observer(({ message }) =>
+
+)
+```
+
+| change | re-rendering component |
+| --- | --- |
+| `message.title = "Bar"` | `Message` |
+| `message.author.name = "Susan"` | `Author` (`.author` is dereferenced in `Message`, but didn't change)* |
+| `message.author = { name: "Susan"}` | `Message`, `Author` |
+| `message.likes[0] = "Michel"` | `Likes` |
+
+Notes:
+1. \* If the `Author` component was invoked like: ``. Then `Message` would be the dereferencing component and react to changes to `message.author.name`. Nonetheless `` would rerender as well, because it receives a new value. So performance wise it is best to dereference as late as possible.
+2. \** If likes were objects instead of strings, and if they were rendered by their own `Like` component, the `Likes` component would not rerender for changes happening inside a specific like.
+
+## TL;DR
+
+> MobX reacts to any _existing_ **observable** _property_ that is read during the execution of a tracked function.
diff --git a/docs/best/stateless-HMR.md b/docs/best/stateless-HMR.md
new file mode 100644
index 000000000..2d4560c1f
--- /dev/null
+++ b/docs/best/stateless-HMR.md
@@ -0,0 +1,80 @@
+---
+title: Hot Module Reloading with Stateless Components
+sidebar_label: Hot Module Reloading with Stateless Components
+hide_title: true
+---
+
+# Hot Module Reloading with Stateless Components
+
+
+One thing that can be a challenge when getting started with MobX (and React in general) is understanding why Hot Module Reloading (HMR) sometimes breaks. When you initially get it working, it seems like magic (and it kind of is), however there's at least one rough edge with regard to HMR and React: stateless components. Since stateless components don't explicitly identify themselves as React components, HMR doesn't quite know what to do with them, and so you'll often see warnings in your console like this:
+
+```
+[HMR] The following modules couldn't be hot updated: (Full reload needed)
+This is usually because the modules which have changed (and their parents) do not know how to hot reload themselves. See http://webpack.github.io/docs/hot-module-replacement-with-webpack.html for more details.
+[HMR] - ./src/ToDoItem.jsx
+```
+
+This is especially apparent when you start working with MobX since observables make it really easy to create a lot of stateless components. Here are some tips for how to build your stateless components and still get all the advantages of HMR:
+
+## Use function declarations instead of arrow functions
+
+Function declarations still do the exact same thing as arrow functions, but they have the key advantage of actually having names inside of the React DevTools.
+
+For instance, here's a stateless component built with an arrow function:
+
+```javascript
+const ToDoItem = observer(props =>
{props.item}
);
+
+export default ToDoItem;
+
+```
+
+And here's how that will appear in the React DevTools:
+
+
+
+On the other hand, using a function declaration will allow you to build the same stateless component AND see it in the DevTools:
+
+```javascript
+function ToDoItem(props) {
+ return
{props.item}
+}
+
+export default observer(ToDoItem);
+
+```
+
+And now the component shows up correctly in the DevTools:
+
+
+
+## Make sure your top-level component is a stateful observer
+
+By "stateful observer", all I really mean is a component created with `React.Component` or `React.createClass` and which uses the `@observer` decorator, like so:
+
+```javascript
+import { observer } from 'mobx-react';
+
+@observer
+class App extends React.Component {
+ constructor(props) {
+ super(props);
+ this.store = props.store;
+ }
+
+ render() {
+ return (
+
+
Todos:
+ {
+ this.store.todos.map((t, idx) => )
+ }
+
+ );
+ }
+}
+
+```
+
+In this case, `ToDoItem` is stateless, but will still work with HMR because the root-level of the UI tree is a stateful observer. As a result, whenever we change **any** stateless component, it will be hot-reloaded because the observers will trigger computations in the root-level component as well. And since the root-level component is a good old-fashioned React component, it'll trigger the HMR for all of its children and voila! All the magic of stateless components, observables, and hot module reloading working together beautifully.
diff --git a/docs/best/store.md b/docs/best/store.md
new file mode 100644
index 000000000..17254c342
--- /dev/null
+++ b/docs/best/store.md
@@ -0,0 +1,317 @@
+---
+sidebar_label: Defining data stores
+title: Best Practices for building large scale maintainable projects
+hide_title: true
+---
+
+# Best Practices for building large scale maintainable projects
+
+
+This section contains some best practices we discovered at Mendix while working with MobX.
+This section is opinionated and you are in no way forced to apply these practices.
+There are many ways of working with MobX and React, and this is just one of them.
+
+This section focuses on an unobtrusive way of working with MobX, which works well in existing code bases, or with classic MVC patterns. An alternative, more opinionated way of organizing stores is using [mobx-state-tree](https://github.com/mobxjs/mobx-state-tree), which ships with cool features as structurally shared snapshots, action middlewares, JSON patch support etc out of the box.
+
+# Stores
+
+Stores can be found in any Flux architecture and can be compared a bit with controllers in the MVC pattern.
+The main responsibility of stores is to move _logic_ and _state_ out of your components into a standalone testable unit that can be used in both frontend and backend JavaScript.
+
+## Stores for the user interface state
+
+Most applications benefit from having at least two stores.
+One for the _UI state_ and one or more for the _domain state_.
+The advantage of separating those two is you can reuse and test _domain state_ universally, and you might very well reuse it in other applications.
+The _ui-state-store_ however is often very specific for your application.
+But usually very simple as well.
+This store typically doesn't have much logic in it, but will store a plethora of loosely coupled pieces of information about the UI.
+This is ideal as most applications will change the UI state often during the development process.
+
+Things you will typically find in UI stores:
+* Session information
+* Information about how far your application has loaded
+* Information that will not be stored in the backend
+* Information that affects the UI globally
+ * Window dimensions
+ * Accessibility information
+ * Current language
+ * Currently active theme
+* User interface state as soon as it affects multiple, further unrelated components:
+ * Current selection
+ * Visibility of toolbars, etc.
+ * State of a wizard
+ * State of a global overlay
+
+It might very well be that these pieces of information start as internal state of a specific component (for example the visibility of a toolbar).
+But after a while you discover that you need this information somewhere else in your application.
+Instead of pushing state in such a case upwards in the component tree, like you would do in plain React apps, you just move that state to the _ui-state-store_.
+
+For isomorphic applications you might also want to provide a stub implementation of this store with sane defaults so that all components render as expected.
+You might distribute the _ui-state-store_ through your application by passing it as a property through your component tree or using `Provider` and `inject` from the `mobx-react` package.
+
+Example of a store (using ES6 syntax):
+
+```javascript
+import {observable, computed, asStructure} from 'mobx';
+import jquery from 'jquery';
+
+export class UiState {
+ @observable language = "en_US";
+ @observable pendingRequestCount = 0;
+
+ // .struct makes sure observer won't be signaled unless the
+ // dimensions object changed in a deepEqual manner
+ @observable.struct windowDimensions = {
+ width: jquery(window).width(),
+ height: jquery(window).height()
+ };
+
+ constructor() {
+ jquery.resize(() => {
+ this.windowDimensions = getWindowDimensions();
+ });
+ }
+
+ @computed get appIsInSync() {
+ return this.pendingRequestCount === 0
+ }
+}
+```
+
+## Domain Stores
+
+Your application will contain one or multiple _domain_ stores.
+These stores store the data your application is all about.
+Todo items, users, books, movies, orders, you name it.
+Your application will most probably have at least one domain store.
+
+A single domain store should be responsible for a single concept in your application.
+However a single concept might take the form of multiple subtypes and it is often a (cyclic) tree structure.
+For example: one domain store for your products, and one for your orders and orderlines.
+As a rule of thumb: if the nature of the relationship between two items is containment, they should typically be in the same store.
+So a store just manages _domain objects_.
+
+These are the responsibilities of a store:
+* Instantiate domain objects. Make sure domain objects know the store they belong to.
+* Make sure there is only one instance of each of your domain objects.
+The same user, order or todo should not be stored twice in memory.
+This way you can safely use references and also be sure you are looking at the latest instance, without ever having to resolve a reference.
+This is fast, straightforward and convenient when debugging.
+* Provide backend integration. Store data when needed.
+* Update existing instances if updates are received from the backend.
+* Provide a stand-alone, universal, testable component of your application.
+* To make sure your store is testable and can be run server-side, you probably will move doing actual websocket / http requests to a separate object so that you can abstract over your communication layer.
+* There should be only one instance of a store.
+
+### Domain objects
+
+Each domain object should be expressed using its own class (or constructor function).
+It is recommended to store your data in _denormalized_ form.
+There is no need to treat your client-side application state as some kind of database.
+Real references, cyclic data structures and instance methods are powerful concepts in JavaScript.
+Domain objects are allowed to refer directly to domain objects from other stores.
+Remember: we want to keep our actions and views as simple as possible and needing to manage references and doing garbage collection yourself might be a step backward.
+Unlike many Flux architectures, with MobX there is no need to normalize your data, and this makes it a lot simpler to build the _essentially_ complex parts of your application:
+your business rules, actions and user interface.
+
+Domain objects can delegate all their logic to the store they belong to if that suits your application well.
+It is possible to express your domain objects as plain objects, but classes have some important advantages over plain objects:
+* They can have methods.
+This makes your domain concepts easier to use stand-alone and reduces the amount of contextual awareness that is needed in your application.
+Just pass objects around.
+You don't have to pass stores around, or have to figure out which actions can be applied to an object if they are just available as instance methods.
+Especially in large applications this is important.
+* They offer fine grained control over the visibility of attributes and methods.
+* Objects created using a constructor function can freely mix observable properties and functions, and non-observable properties and methods.
+* They are easily recognizable and can strictly be type-checked.
+
+
+### Example domain store
+
+```javascript
+import {observable, autorun} from 'mobx';
+import uuid from 'node-uuid';
+
+export class TodoStore {
+ authorStore;
+ transportLayer;
+ @observable todos = [];
+ @observable isLoading = true;
+
+ constructor(transportLayer, authorStore) {
+ this.authorStore = authorStore; // Store that can resolve authors for us
+ this.transportLayer = transportLayer; // Thing that can make server requests for us
+ this.transportLayer.onReceiveTodoUpdate(updatedTodo => this.updateTodoFromServer(updatedTodo));
+ this.loadTodos();
+ }
+
+ /**
+ * Fetches all todos from the server
+ */
+ loadTodos() {
+ this.isLoading = true;
+ this.transportLayer.fetchTodos().then(fetchedTodos => {
+ fetchedTodos.forEach(json => this.updateTodoFromServer(json));
+ this.isLoading = false;
+ });
+ }
+
+ /**
+ * Update a todo with information from the server. Guarantees a todo
+ * only exists once. Might either construct a new todo, update an existing one,
+ * or remove a todo if it has been deleted on the server.
+ */
+ updateTodoFromServer(json) {
+ var todo = this.todos.find(todo => todo.id === json.id);
+ if (!todo) {
+ todo = new Todo(this, json.id);
+ this.todos.push(todo);
+ }
+ if (json.isDeleted) {
+ this.removeTodo(todo);
+ } else {
+ todo.updateFromJson(json);
+ }
+ }
+
+ /**
+ * Creates a fresh todo on the client and server
+ */
+ createTodo() {
+ var todo = new Todo(this);
+ this.todos.push(todo);
+ return todo;
+ }
+
+ /**
+ * A todo was somehow deleted, clean it from the client memory
+ */
+ removeTodo(todo) {
+ this.todos.splice(this.todos.indexOf(todo), 1);
+ todo.dispose();
+ }
+}
+
+export class Todo {
+
+ /**
+ * unique id of this todo, immutable.
+ */
+ id = null;
+
+ @observable completed = false;
+ @observable task = "";
+
+ /**
+ * reference to an Author object (from the authorStore)
+ */
+ @observable author = null;
+
+ store = null;
+
+ /**
+ * Indicates whether changes in this object
+ * should be submitted to the server
+ */
+ autoSave = true;
+
+ /**
+ * Disposer for the side effect that automatically
+ * stores this Todo, see @dispose.
+ */
+ saveHandler = null;
+
+ constructor(store, id=uuid.v4()) {
+ this.store = store;
+ this.id = id;
+
+ this.saveHandler = reaction(
+ // observe everything that is used in the JSON:
+ () => this.asJson,
+ // if autoSave is on, send json to server
+ (json) => {
+ if (this.autoSave) {
+ this.store.transportLayer.saveTodo(json);
+ }
+ }
+ );
+ }
+
+ /**
+ * Remove this todo from the client and server
+ */
+ delete() {
+ this.store.transportLayer.deleteTodo(this.id);
+ this.store.removeTodo(this);
+ }
+
+ @computed get asJson() {
+ return {
+ id: this.id,
+ completed: this.completed,
+ task: this.task,
+ authorId: this.author ? this.author.id : null
+ };
+ }
+
+ /**
+ * Update this todo with information from the server
+ */
+ updateFromJson(json) {
+ // make sure our changes aren't sent back to the server
+ this.autoSave = false;
+ this.completed = json.completed;
+ this.task = json.task;
+ this.author = this.store.authorStore.resolveAuthor(json.authorId);
+ this.autoSave = true;
+ }
+
+ dispose() {
+ // clean up the observer
+ this.saveHandler();
+ }
+}
+```
+
+# Combining multiple stores
+
+An often asked question is how to combine multiple stores without using singletons. How will they know about each other?
+
+An effective pattern is to create a `RootStore` that instantiates all stores, and share references. The advantage of this pattern is:
+
+1. Simple to set up.
+2. Supports strong typing well.
+3. Makes complex unit tests easy as you just have to instantiate a root store.
+
+Example:
+
+```javascript
+class RootStore {
+ constructor() {
+ this.userStore = new UserStore(this)
+ this.todoStore = new TodoStore(this)
+ }
+}
+
+class UserStore {
+ constructor(rootStore) {
+ this.rootStore = rootStore
+ }
+
+ getTodos(user) {
+ // access todoStore through the root store
+ return this.rootStore.todoStore.todos.filter(todo => todo.author === user)
+ }
+}
+
+class TodoStore {
+ @observable todos = []
+
+ constructor(rootStore) {
+ this.rootStore = rootStore
+ }
+}
+```
+
+When using React, this root store is typically inserted into the component tree by using ``
diff --git a/docs/best/trace.md b/docs/best/trace.md
new file mode 100644
index 000000000..ba859baa7
--- /dev/null
+++ b/docs/best/trace.md
@@ -0,0 +1,61 @@
+---
+sidebar_label: Using trace for debugging
+title: Using `trace` for debugging
+hide_title: true
+---
+
+# Using `trace` for debugging
+
+
+Trace is a small utility that helps to find out why your computed values, reactions or components are re-evaluating.
+
+It can be used by simply importing `import { trace } from "mobx"`, and then put it inside a reaction or computed value.
+It will print why it is re-evaluating the current derivation.
+
+Optionally it is possible to automatically enter the debugger by passing `true` as last argument.
+This way the exact mutation that causes the reaction to re-run is still in stack, usually ~8 stack frames up. See the image below.
+
+In debugger mode, the debug information will also reveal the full derivation tree that is affecting the current computation / reaction.
+
+
+
+
+
+## Live examples
+
+Simple codesandbox trace example: https://codesandbox.io/s/nr58ylyn4m
+
+Here's a deployed example for exploring the stack: https://csb-nr58ylyn4m-hontnuliaa.now.sh/
+Be sure to play with chrome debugger's blackbox feature!
+
+## Usage examples
+
+There are different ways of calling `trace()`, some examples:
+
+```javascript
+import { observer } from "mobx-react"
+import { trace } from "mobx"
+
+@observer
+class MyComponent extends React.Component {
+ render() {
+ trace(true) // enter the debugger whenever an observable value causes this component to re-run
+ return
{this.props.user.name}
+ }
+}
+```
+
+Enable trace by using the `reaction` argument of an reaction / autorun:
+
+```javascript
+mobx.autorun("loggerzz", r => {
+ r.trace()
+ console.log(user.fullname)
+})
+```
+
+Pass in the property name of a computed property:
+
+```javascript
+trace(user, "fullname")
+```
diff --git a/docs/book.json b/docs/book.json
new file mode 100644
index 000000000..5e070e05a
--- /dev/null
+++ b/docs/book.json
@@ -0,0 +1,21 @@
+{
+ "plugins":["github", "ga", "disqus", "edit-link", "anchors", "codefund"],
+ "pluginsConfig": {
+ "github": {
+ "url": "https://github.com/mobxjs/mobx"
+ },
+ "edit-link": {
+ "base": "https://github.com/mobxjs/mobx/tree/gh-pages/docs",
+ "label": "Edit This Page"
+ },
+ "ga": {
+ "token": "UA-65632006-1"
+ },
+ "disqus": {
+ "shortName": "mobservable"
+ }
+ },
+ "styles": {
+ "website": "styles/website.css"
+ }
+}
diff --git a/docs/faq/faq.md b/docs/faq/faq.md
new file mode 100644
index 000000000..d1f2d28c2
--- /dev/null
+++ b/docs/faq/faq.md
@@ -0,0 +1,63 @@
+---
+sidebar_label: Frequently Asked Questions
+title: FAQ
+hide_title: true
+---
+
+## FAQ
+
+
+##### Which browsers are supported?
+
+MobX runs on any ES5 environment. That means that Node.js, Rhino and all browsers except for IE8 are supported. See [caniuse.com](http://caniuse.com/#feat=es5)
+
+##### Can MobX be combined with RxJS?
+Yes, you can use [toStream and fromStream from mobx-utils](https://github.com/mobxjs/mobx-utils#tostream) to use RXJS and other TC 39 compatible observables with mobx.
+
+##### When to use RxJS instead of MobX?
+For anything that involves explictly working with the concept of time,
+or when you need to reason about the historical values / events of an observable (and not just the latest), RxJs is recommended as it provides more low-level primitives.
+Whenever you want to react to _state_ instead of _events_, MobX offers an easier and more high-level approach.
+In practice, combining RxJS and MobX might result in really powerful constructions.
+Use for example RxJS to process and throttle user events and as a result of that update the state.
+If the state has been made observable by MobX, it will then take care of updating the UI and other derivations accordingly.
+
+##### Is React Native supported?
+
+Yes, `mobx` and `mobx-react` will work on React Native. The latter through importing `"mobx-react/native"`.
+The devtools don't support React Native. Note that if you indend to use your observer components with hot reloading, decorators in the components may not always work. If that is the case, use the functions instead (eg. `action(fn)` instead of `@action` or `observer(component)` instead of `@observer`).
+
+##### How does MobX compare to other Reactive frameworks?
+
+See this [issue](https://github.com/mobxjs/mobx/issues/18) for some considerations.
+
+##### Is MobX a framework?
+
+MobX is *not* a framework. It does not tell you how to structure your code, where to store state or how to process events. Yet it might free you from frameworks that poses all kinds of restrictions on your code in the name of performance.
+
+##### Can I combine MobX with Flux?
+
+Flux implementations that do not work on the assumption that the data in their stores is immutable should work well with MobX.
+However, the need for Flux is reduced when using MobX.
+MobX already optimizes rendering, and it works with most kinds of data, including cycles and classes.
+So other programming paradigms like classic MVC can now be easily applied in applications that combine ReactJS with MobX.
+
+##### Can I use MobX together with framework X?
+
+Probably.
+MobX is framework agnostic and can be applied in any modern JS environment.
+It just ships with a small function to transform ReactJS components into reactive view functions for convenience.
+MobX works just as well server side, and is already combined with jQuery (see this [Fiddle](http://jsfiddle.net/mweststrate/vxn7qgdw)) and [Deku](https://gist.github.com/mattmccray/d8740ea97013c7505a9b).
+
+##### Can I record states and re-hydrate them?
+
+Yes, see [createTransformer](http://mobxjs.github.io/mobx/refguide/create-transformer.html) for some examples.
+
+##### Can you tell me how it works?
+
+Sure, join the reactiflux channel or checkout the code. Or, submit an issue to motivate me to make some nice drawings :).
+And look at this [Medium article](https://medium.com/@mweststrate/becoming-fully-reactive-an-in-depth-explanation-of-mobservable-55995262a254).
+
+##### Where can I find more MobX resources?
+
+We've compiled a large list of helpful resources of all types in the [official awesome list](https://github.com/mobxjs/awesome-mobx#awesome-mobx). If you feel it's missing something, please open an [issue](https://github.com/mobxjs/awesome-mobx/issues/new) or [pull request](https://github.com/mobxjs/awesome-mobx/compare) to describe what you're looking for or share your added links :).
diff --git a/docs/intro/concepts.md b/docs/intro/concepts.md
new file mode 100644
index 000000000..7b7861a07
--- /dev/null
+++ b/docs/intro/concepts.md
@@ -0,0 +1,98 @@
+---
+title: Concepts & Principles
+sidebar_label: Concepts & Principles
+hide_title: true
+---
+
+# Concepts & Principles
+
+
+## Concepts
+
+MobX distinguishes the following concepts in your application. You saw them in the previous gist, but let's dive into them in a bit more detail.
+
+### 1. State
+
+_State_ is the data that drives your application.
+Usually there is _domain specific state_ like a list of todo items and there is _view state_ such as the currently selected element.
+Remember, state is like spreadsheets cells that hold a value.
+
+### 2. Derivations
+
+_Anything_ that can be derived from the _state_ without any further interaction is a derivation.
+Derivations exist in many forms:
+
+* The _user interface_.
+* _Derived data_, such as the number of todos left.
+* _Backend integrations_ like sending changes to the server.
+
+MobX distinguishes two kind of derivations:
+* *Computed values*. These are values that can always be derived from the current observable state using a pure function.
+* *Reactions*. Reactions are side effects that need to happen automatically if the state changes. These are needed as a bridge between imperative and reactive programming. Or to make it more clear, they are ultimately needed to achieve I/O.
+
+People starting with MobX tend to use reactions too often.
+The golden rule is: if you want to create a value based on the current state, use `computed`.
+
+Back to the spreadsheet analogy, formulas are derivations that *compute* a value. But for you as a user to be able to see it on the screen a *reaction* is needed that repaints part of the GUI.
+
+### 3. Actions
+
+An _action_ is any piece of code that changes the _state_. User events, backend data pushes, scheduled events, etc.
+An action is like a user that enters a new value in a spreadsheet cell.
+
+Actions can be defined explicitly in MobX to help you to structure code more clearly.
+If MobX is used in [*strict mode*](../refguide/api##-enforceactions-), MobX will enforce that no state can be modified outside actions.
+
+## Principles
+
+MobX supports a uni-directional data flow where _actions_ change the _state_, which in turn updates all affected _views_.
+
+
+
+All _Derivations_ are updated **automatically** and **atomically** when the _state_ changes. As a result it is never possible to observe intermediate values.
+
+All _Derivations_ are updated **synchronously** by default. This means that, for example, _actions_ can safely inspect a computed value directly after altering the _state_.
+
+_Computed values_ are updated **lazily**. Any computed value that is not actively in use will not be updated until it is needed for a side effect (I/O).
+If a view is no longer in use it will be garbage collected automatically.
+
+All _Computed values_ should be **pure**. They are not supposed to change _state_.
+
+## Illustration
+
+The following listing illustrates the above concepts and principles:
+
+```javascript
+import {observable, autorun} from 'mobx';
+
+var todoStore = observable({
+ /* some observable state */
+ todos: [],
+
+ /* a derived value */
+ get completedCount() {
+ return this.todos.filter(todo => todo.completed).length;
+ }
+});
+
+/* a function that observes the state */
+autorun(function() {
+ console.log("Completed %d of %d items",
+ todoStore.completedCount,
+ todoStore.todos.length
+ );
+});
+
+/* ..and some actions that modify the state */
+todoStore.todos[0] = {
+ title: "Take a walk",
+ completed: false
+};
+// -> synchronously prints 'Completed 0 of 1 items'
+
+todoStore.todos[0].completed = true;
+// -> synchronously prints 'Completed 1 of 1 items'
+
+```
+
+In the [10 minute introduction to MobX and React](https://mobxjs.github.io/mobx/getting-started.html) you can dive deeper into this example and build a user interface using [React](https://facebook.github.io/react/) around it.
diff --git a/docs/intro/overview.md b/docs/intro/overview.md
new file mode 100644
index 000000000..6805ef3ad
--- /dev/null
+++ b/docs/intro/overview.md
@@ -0,0 +1,96 @@
+---
+title: The gist of MobX
+sidebar_label: The gist of MobX
+hide_title: true
+---
+
+# The gist of MobX
+
+
+
+ egghead.io lesson 1: observable & observer
+
+
+
+
+ Hosted on egghead.io
+
+
+
+So far it all might sound a bit fancy, but making an app reactive using MobX boils down to just these three steps:
+
+## 1. Define your state and make it observable
+
+Store state in any data structure you like; objects, array, classes.
+Cyclic data structures, references, it doesn't matter.
+Just make sure that all properties that you want to change over time are marked by `mobx` to make them observable.
+
+```javascript
+import {observable} from 'mobx';
+
+var appState = observable({
+ timer: 0
+});
+```
+
+## 2. Create a view that responds to changes in the State
+
+We didn't make our `appState` observable for nothing;
+you can now create views that automatically update whenever relevant data in the `appState` changes.
+MobX will find the minimal way to update your views.
+This single fact saves you tons of boilerplate and is [wickedly efficient](https://mendix.com/tech-blog/making-react-reactive-pursuit-high-performing-easily-maintainable-react-apps/).
+
+Generally speaking any function can become a reactive view that observes its data, and MobX can be applied in any ES5 conformant JavaScript environment.
+But here is an (ES6) example of a view in the form of a React component.
+
+```javascript
+import {observer} from 'mobx-react';
+
+@observer
+class TimerView extends React.Component {
+ render() {
+ return (
+
+ );
+ }
+
+ onReset() {
+ this.props.appState.resetTimer();
+ }
+};
+
+ReactDOM.render(, document.body);
+```
+
+(For the implementation of `resetTimer` function see the next section)
+
+## 3. Modify the State
+
+The third thing to do is to modify the state.
+That is what your app is all about after all.
+Unlike many other frameworks, MobX doesn't dictate how you do this.
+There are best practices, but the key thing to remember is:
+***MobX helps you do things in a simple straightforward way***.
+
+The following code will alter your data every second, and the UI will update automatically when needed.
+No explicit relations are defined in either the controller functions that _change_ the state or in the views that should _update_.
+Decorating your _state_ and _views_ with `observable` is enough for MobX to detect all relationships.
+Here are two examples of changing the state:
+
+```javascript
+appState.resetTimer = action(function reset() {
+ appState.timer = 0;
+});
+
+setInterval(action(function tick() {
+ appState.timer += 1;
+}), 1000);
+```
+
+The `action` wrapper is only needed when using MobX in strict mode (by default off).
+It is recommended to use action though as it will help you to better structure applications and expresses the intention of a function to modify state.
+Also it automatically applies transactions for optimal performance.
+
+Feel free to try this example on [JSFiddle](http://jsfiddle.net/mweststrate/wgbe4guu/) or by cloning the [MobX boilerplate project](https://github.com/mobxjs/mobx-react-boilerplate)
diff --git a/docs/refguide/action.md b/docs/refguide/action.md
new file mode 100644
index 000000000..fb08c450f
--- /dev/null
+++ b/docs/refguide/action.md
@@ -0,0 +1,80 @@
+---
+title: action
+sidebar_label: action
+hide_title: true
+---
+
+# action
+
+
+
+ egghead.io lesson 5: actions
+
+
+
+
+ Hosted on egghead.io
+
+
+Usage:
+* `action(fn)`
+* `action(name, fn)`
+* `@action classMethod() {}`
+* `@action(name) classMethod () {}`
+* `@action boundClassMethod = (args) => { body }`
+* `@action(name) boundClassMethod = (args) => { body }`
+* `@action.bound classMethod() {}`
+
+Any application has actions. Actions are anything that modify the state.
+With MobX you can make it explicit in your code where your actions live by marking them.
+Actions help you to structure your code better.
+
+It takes a function and returns a function with the same signature, but wrapped with `transaction`, `untracked`, and `allowStateChanges`.
+Especially the fact that `transaction` is applied automatically yields great performance benefits;
+actions will batch mutations and only notify computed values and reactions after the (outer most) action has finished.
+This makes sure intermediate or incomplete values produced during an action are not visible to the rest of the application until the action has finished.
+
+It is advised to use `(@)action` on any function that modifies observables or has side effects.
+`action` also provides useful debugging information in combination with the devtools.
+
+Using the `@action` decorator with setters (i.e. `@action set propertyName`) is not supported; however, setters of [computed properties are automatically actions](https://github.com/mobxjs/mobx/blob/gh-pages/docs/refguide/computed-decorator.md#setters-for-computed-values).
+
+Note: using `action` is mandatory when MobX is configured to require actions to make state changes, see [`enforceActions`](https://github.com/mobxjs/mobx/blob/gh-pages/docs/refguide/api.md#configure).
+
+## When to use actions?
+
+Actions should only, and always, be used on functions that _modify_ state.
+Functions that just perform look-ups, filters etc should _not_ be marked as actions; to allow MobX to track their invocations.
+
+
+["enforce actions"](https://github.com/mobxjs/mobx/blob/gh-pages/docs/refguide/api.md#configure) enforces that all state modifications are done by an action. This is a useful best practice in larger, long term code bases.
+
+## Bound actions
+
+The `action` decorator / function follows the normal rules for binding in javascript.
+However, `action.bound` can be used to automatically bind actions to the targeted object.
+Note that unlike `action`, `(@)action.bound` does not take a name parameter, so the name will always be based on the property name to which the action is bound.
+
+Example:
+
+```javascript
+class Ticker {
+ @observable tick = 0
+
+ @action.bound
+ increment() {
+ this.tick++ // 'this' will always be correct
+ }
+}
+
+const ticker = new Ticker()
+setInterval(ticker.increment, 1000)
+```
+
+_Note: don't use *action.bound* with arrow functions; arrow functions are already bound and cannot be rebound._
+
+
+## `runInAction(name?, thunk)`
+
+`runInAction` is a simple utility that takes an code block and executes in an (anonymous) action. This is useful to create and execute actions on the fly, for example inside an asynchronous process. `runInAction(f)` is sugar for `action(f)()`
+
diff --git a/docs/refguide/api.md b/docs/refguide/api.md
new file mode 100644
index 000000000..5d4c30477
--- /dev/null
+++ b/docs/refguide/api.md
@@ -0,0 +1,752 @@
+---
+title: MobX Api Reference
+sidebar_label: API overview
+hide_title: true
+---
+
+# MobX Api Reference
+
+
+**Applies to MobX 4 and higher**
+
+- Using Mobx 3? Use this [migration guide](https://github.com/mobxjs/mobx/wiki/Migrating-from-mobx-3-to-mobx-4) to switch gears.
+- [MobX 3 documentation](https://github.com/mobxjs/mobx/blob/54557dc319b04e92e31cb87427bef194ec1c549c/docs/refguide/api.md)
+- For MobX 2, the old documentation is still available on [github](https://github.com/mobxjs/mobx/blob/7c9e7c86e0c6ead141bb0539d33143d0e1f576dd/docs/refguide/api.md).
+
+# Core API
+
+_These are the most important MobX API's._
+
+> Understanding `observable`, `computed`, `reaction` and `action` is enough
+ to master MobX and use it in your applications!
+
+## Creating observables
+
+
+### `observable(value)`
+Usage:
+* `observable(value)`
+* `@observable classProperty = value`
+
+Observable values can be JS primitives, references, plain objects, class instances, arrays and maps.
+
+**Note:** `observable(value)` is a convenience API that will succeed only if it can be made into
+ an observable data structure (_Array_, _Map_, or _observable-object_). For all other values, no conversion will be performed.
+
+You can also directly create the desired observable type, see below.
+
+The following conversion rules are applied, but can be fine-tuned by using [*decorators*](#decorators). See below.
+
+1. If *value* is an instance of an [ES6 Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map): a new [Observable Map](map.md) will be returned. Observable maps are very useful if you don't want to react just to the change of a specific entry, but also to the addition or removal of entries.
+1. If *value* is an array, a new [Observable Array](array.md) will be returned.
+1. If *value* is an object *without* prototype or its prototype is `Object.prototype`, the object will be cloned and all its current properties will be made observable. See [Observable Object](object.md)
+1. If *value* is an object *with* a prototype, a JavaScript primitive or function, there will be no change made to the value. If you do need a [Boxed Observable](boxed.md), you can do one of the following:
+ - Call `observable.box(value)` explicitly
+ - Use `@observable` in the class definition
+ - Call [`decorate()`](#decorate)
+ - Use `extendObservable()` to introduce properties on a class definition
+
+MobX will not make objects with a prototype automatically observable; as that is the responsibility of its constructor function. Use `extendObservable` in the constructor, or `@observable` in its class definition instead.
+
+These rules might seem complicated at first sight, but you will notice that in practice they are very intuitive to work with.
+
+**Some notes:**
+
+* To use the `@observable` decorator, make sure that [decorators are enabled](http://mobxjs.github.io/mobx/refguide/observable-decorator.html) in your transpiler (babel or typescript).
+* By default making a data structure observable is *infective*; that means that `observable` is applied automatically to any value that is contained by the data structure, or will be contained by the data structure in the future. This behavior can be changed by using [*decorators*](#decorators).
+* _[MobX 4 and below]_ To create dynamically keyed objects, always use maps! Only initially existing properties on an object will be made observable, although new ones can be added using `extendObservable`.
+
+[«`observable`»](observable.md) — [«`@observable`»](observable-decorator.md)
+
+### `@observable property = value`
+
+`observable` can also be used as property decorator. It requires [decorators to be enabled](../best/decorators.md) and is syntactic
+sugar for `extendObservable(this, { property: value })`.
+
+[«`details`»](observable-decorator.md)
+
+### `observable.box(value, options?)`
+Creates an observable _box_ that stores an observable reference to a value. Use `get()` to get the current value of the box, and `set()` to update it.
+This is the foundation on which all other observables are built, but in practice you will use it rarely.
+
+Normal boxes will automatically try to turn any new value into an observable if it isn't already. Use the `{deep: false}` option to disable this behavior.
+
+[«`details`»](boxed.md)
+
+### `observable.object(value, decorators?, options?)`
+
+Creates a clone of the provided object and makes all its properties observable.
+By default any values in those properties will be made observable as well, but when using the `{deep: false}` options, only the properties will be made into observable
+references, leaving the values untouched. (This holds also for any values assigned in the future).
+
+The second argument in `observable.object()` can be used to fine tune the observability with [`decorators`](#decorators).
+
+[«`details`»](object.md)
+
+### `observable.array(value, options?)`
+
+Creates a new observable array based on the provided value.
+
+Use the `{deep: false}` option if the values in the array should not be turned into observables.
+
+[«`details`»](array.md)
+
+### `observable.map(value, options?)`
+
+Creates a new observable map based on the provided value. Use the `{deep: false}` option if the values in the map should not be turned into observables.
+
+Use `map` whenever you want to create a dynamically keyed collections and the addition / removal of keys needs to be observed.
+Since this uses the full-blown _ES6 Map_ internally, you are free to use any type for the key and _not limited_ to string keys.
+
+[«`details`»](map.md)
+
+### `observable.set(value, options?)`
+
+Creates a new observable map based on the provided value. Use the `{deep: false}` option if the values in the map should not be turned into observables.
+
+Use `set` whenever you want to create a dynamic set where the addition / removal of values needs to be observed, and where values can appear only once in the collection.
+Note that your browser needs to support ES6 sets, or polyfill them, to make sets work.
+
+The api is further the same as the [ES6 set api](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)
+
+### `extendObservable`
+
+Usage: `extendObservable(target, properties, decorators?, options?)`.
+
+For each key/value pair in each `properties` a (new) observable property will be introduced on the target object.
+This can be used in constructor functions to introduce observable properties without using decorators.
+If a value of the `properties` is a getter function, a *computed* property will be introduced.
+
+Use `extendObservable(target, properties, decorators?, {deep: false})` if the new properties should not be infective (that is; newly assigned values should not be turned into observables automatically).
+Note that `extendObservable` enhances existing objects, unlike `observable.object` which creates a new object.
+
+[«details»](extend-observable.md)
+
+### Decorators
+
+Use decorators to fine tune the observability of properties defined via `observable`, `extendObservable` and `observable.object`. They can also control the auto-conversion rules for specific properties.
+
+The following decorators are available:
+
+* **`observable.deep`**: This is the default decorator, used by any observable. It converts any assigned, non-primitive value into an observable if it isn't one yet.
+* **`observable.ref`**: Disables automatic observable conversion, just creates an observable reference instead.
+* **`observable.shallow`**: Can only be used in combination with collections. Turns any assigned collection into a collection, which is shallowly observable (instead of deep). In other words; the values inside the collection won't become observables automatically.
+* **`computed`**: Creates a derived property, see [`computed`](computed-decorator.md)
+* **`action`**: Creates an action, see [`action`](action.md)
+* **`action.bound`**: Creates a bound action, see [`action`](action.md)
+
+You can apply these decorators using the _@decorator_ syntax:
+
+```javascript
+import {observable, action} from 'mobx';
+
+class TaskStore {
+ @observable.shallow tasks = []
+ @action addTask(task) { /* ... */ }
+}
+```
+
+Or by passing in property decorators via `observable.object` / `observable.extendObservable` or [`decorate()`](#decorate).
+Note that decorators always 'stick' to the property. So they will remain in effect even if a new value is assigned.
+
+```javascript
+import {observable, action} from 'mobx';
+
+const taskStore = observable({
+ tasks: [],
+ addTask(task) { /* ... */ }
+}, {
+ tasks: observable.shallow,
+ addTask: action
+})
+```
+
+[«details»](modifiers.md)
+
+### `decorate`
+Usage: `decorate(object, decorators)`
+This is a convenience method to apply observability [decorators](#decorators) to the properties of a plain object or class instance. The second argument is an object with properties set to certain decorators.
+
+Use this if you cannot use the _@decorator_ syntax or need more control over setting observability.
+
+```js
+class TodoList {
+ todos = {}
+ get unfinishedTodoCount() {
+ return values(this.todos).filter(todo => !todo.finished).length
+ }
+ addTodo() {
+ const t = new Todo()
+ t.title = 'Test_' + Math.random()
+ set(this.todos, t.id, t)
+ }
+}
+
+decorate(TodoList, {
+ todos: observable,
+ unfinishedTodoCount: computed,
+ addTodo: action.bound
+})
+```
+
+For applying multiple decorators on a single property, you can pass an array of decorators. The decorators application order is from right to left.
+```javascript
+import { decorate, observable } from 'mobx'
+import { serializable, primitive } from 'serializr'
+import persist from 'mobx-persist'
+
+class Todo {
+ id = Math.random();
+ title = '';
+ finished = false;
+}
+
+decorate(Todo, {
+ title: [serializable(primitive), persist('object'), observable],
+ finished: [serializable(primitive), observable]
+})
+```
+Note: Not all decorators can be composed together, and this functionality is just best-effort. Some decorators affect the instance directly and can 'hide' the effect of other decorators that only change the prototype.
+
+
+## Computed values
+
+Usage:
+* `computed(() => expression)`
+* `computed(() => expression, (newValue) => void)`
+* `computed(() => expression, options)`
+* `@computed get classProperty() { return expression; }`
+* `@computed({equals: compareFn}) get classProperty() { return expression; }`
+* `@computed.struct get classProperty() { return expression; }`
+
+Creates a computed property. The `expression` should not have side effects but return a value.
+The expression will automatically be re-evaluated if any observables it uses changes, but only if it is in use by some *reaction*.
+
+There are various `options` that can be used to control the behavior of `computed`. These include:
+
+* **`equals: (value, value) => boolean`** Comparison method can be used to override the default detection on when something is changed. Built-in comparers are: `comparer.identity`, `comparer.default`, `comparer.structural`.
+* **`name: string`** Provide a debug name to this computed property
+* **`requiresReaction: boolean`** Wait for a change in value of the tracked observables, before recomputing the derived property
+* **`get: () => value)`** Override the getter for the computed property.
+* **`set: (value) => void`** Override the setter for the computed property
+* **`keepAlive: boolean`** Set to true to automatically keep computed values alive, rather then suspending then when there are no observers.
+
+[«details»](computed-decorator.md)
+
+## Actions
+
+Any application has actions. Actions are anything that modify the state.
+
+With MobX you can make it explicit in your code where your actions live by marking them.
+Actions helps you to structure your code better.
+It is advised to use them on any function that modifies observables or has side effects.
+`action` also provides useful debugging information in combination with the devtools.
+Note: using `action` is mandatory when *strict mode* is enabled, see `enforceActions`.
+[«details»](action.md)
+
+Usage:
+* `action(fn)`
+* `action(name, fn)`
+* `@action classMethod`
+* `@action(name) classMethod`
+* `@action boundClassMethod = (args) => { body }`
+* `@action.bound boundClassMethod(args) { body }`
+
+For one-time-actions `runInAction(name?, fn)` can be used, which is sugar for `action(name, fn)()`.
+
+### Flow
+
+Usage: `flow(function* (args) { })`
+
+`flow()` takes a generator function as its only input
+
+When dealing with _async actions_, the code that executes in the callback is not wrapped by `action`. This means the observable state that you are mutating, will fail the [`enforceActions`](#configure) check. An easy way to retain the action semantics is by wrapping the async function with flow. This will ensure to wrap all your callbacks in `action()`.
+
+Note that the async function must be a _generator_ and you must only _yield_ to promises inside. `flow` gives you back a promise that you can `cancel()` if you want.
+
+```js
+import { configure } from 'mobx';
+
+// don't allow state modifications outside actions
+configure({enforceActions: "always"});
+
+class Store {
+ @observable githubProjects = [];
+ @observable state = "pending"; // "pending" / "done" / "error"
+
+
+ fetchProjects = flow(function* fetchProjects() { // <- note the star, this a generator function!
+ this.githubProjects = [];
+ this.state = "pending";
+ try {
+ const projects = yield fetchGithubProjectsSomehow(); // yield instead of await
+ const filteredProjects = somePreprocessing(projects);
+
+ // the asynchronous blocks will automatically be wrapped actions
+ this.state = "done";
+ this.githubProjects = filteredProjects;
+ } catch (error) {
+ this.state = "error";
+ }
+ })
+}
+```
+
+_Tip: it is recommended to give the generator function a name, this is the name that will show up in dev tools and such_
+
+**Flows can be cancelled**
+
+Flows are canceallable, that means that you can call `cancel()` on the returned promise. This will stop the generator immediately, but any `finally` clause will still be processed.
+The returned promise itself will reject with `FLOW_CANCELLED`
+
+**Flows support async iterators**
+
+Flows support async iterators, that means you can use async generators:
+
+```javascript
+async function* someNumbers() {
+ yield Promise.resolve(1)
+ yield Promise.resolve(2)
+ yield Promise.resolve(3)
+}
+
+const count = mobx.flow(async function*() {
+ // use for await to loop async iterators
+ for await (const number of someNumbers()) {
+ total += number
+ }
+ return total
+})
+
+const res = await count() // 6
+```
+
+## Reactions & Derivations
+
+*Computed values* are **values** that react automatically to state changes.
+*Reactions* are **side effects** that react automatically to state changes.
+Reactions _can_ be used to ensure that a certain side effect (mainly I/O) is automatically executed when relevant state changes, like logging, network requests etc.
+The most commonly used reaction is the `observer` decorator for React components (see below).
+
+### `observer`
+Can be used as higher order component around a React component.
+The component will then automatically re-render if any of the observables used in the `render` function of the component has changed.
+Note that `observer` is provided by the `"mobx-react"` package and not by `"mobx"` itself.
+
+[«details»](observer-component.md)
+
+Usage:
+* `observer(React.createClass({ ... }))`
+* `observer((props, context) => ReactElement)`
+* `observer(class MyComponent extends React.Component { ... })`
+* `@observer class MyComponent extends React.Component { ... }`
+
+
+### `autorun`
+Usage: `autorun(() => { sideEffect }, options)`. Autorun runs the provided `sideEffect` and tracks which observable state is accessed while running the side effect.
+Whenever one of the used observables is changed in the future, the same sideEffect will be run again.
+Returns a disposer function to cancel the side effect.
+
+[«details»](autorun.md)
+
+**options**
+- **`name?: string`**: A name for easier identification and debugging
+- **`delay?: number`**: the sideEffect will be delayed and debounced with the given `delay`. Defaults to `0`.
+- **`onError?: (error) => void`**: error handler that will be triggered if the autorun function throws an exception
+- **`scheduler?: (callback) => void`**: Set a custom scheduler to determine how re-running the autorun function should be scheduled
+- **`requiresObservable?: boolean`** Enables [`reactionRequiresObservable`](#reactionrequiresobservable-boolean) locally for the autorun
+
+
+### `when`
+Usage: `when(() => condition, () => { sideEffect }, options)`.
+The condition expression will react automatically to any observables it uses.
+As soon as the expression returns true the sideEffect function will be invoked, but only once.
+
+**Note:** the _effect-function_ (second argument) is actually optional. If no effect-function is provided, it will return a cancelable promise (i.e. having a `cancel()` method on the promise)
+
+`when` returns a disposer to prematurely cancel the whole thing.
+
+If no effect function is passed to `when`, it will return a promise that can be awaited until the condition settles.
+
+[«details»](when.md).
+
+**options**
+- **`name?: string`**: A name for easier identification and debugging
+- **`onError?: (error) => void`**: error handler that will be triggered if the _predicate-function_ or the _effect-function_ throws an exception
+- **`timeout: number`** a timeout in milliseconds, after which the `onError` handler will be triggered to signal the condition not being met within a certain time
+- **`requiresObservable?: boolean`** Enables [`reactionRequiresObservable`](#reactionrequiresobservable-boolean) locally for the when
+
+### `reaction`
+Usage: `reaction(() => data, data => { sideEffect }, options)`.
+A variation on `autorun` that gives more fine-grained control on which observables that will be tracked.
+It takes two function, the first one is tracked and returns data that is used as input for the second one, the side effect.
+Unlike `autorun` the side effect won't be run initially, and any observables that are accessed while executing the side effect will not be tracked.
+The side effect can be debounced, just like `autorunAsync`.
+
+[«details»](reaction.md)
+
+**options**
+- **`fireImmediately?: boolean`**: Wait for a change before firing the _effect function_. Defaults to `false`.
+- **`delay?: number`**: the sideEffect will be delayed and debounced with the given `delay`. Defaults to `0`.
+- **`equals`**: Custom equality function to determine whether the expr function differed from it's previous result, and hence should fire effect. Accepts the same options as the equals option of `computed`.
+- Also accepts all of the options from [`autorun`](#autorun)
+- **`requiresObservable?: boolean`** Enables [`reactionRequiresObservable`](#reactionrequiresobservable-boolean) locally for the reaction
+
+### `onReactionError`
+
+Usage: `onReactionError(handler: (error: any, derivation) => void)`
+
+This method attaches a global error listener, which is invoked for every error that is thrown from a _reaction_.
+This can be used for monitoring or test purposes.
+
+------
+
+# Utilities
+
+_Here are some utilities that might make working with observable objects or computed values more convenient.
+More, less trivial utilities can be found in the * [mobx-utils](https://github.com/mobxjs/mobx-utils) package._
+
+### `Provider` (`mobx-react` package)
+
+Can be used to pass stores to child components using React's context mechanism. See the [`mobx-react` docs](https://github.com/mobxjs/mobx-react#provider-experimental).
+
+### `inject` (`mobx-react` package)
+
+Higher order component and counterpart of `Provider`. Can be used to pick stores from React's context and pass it as props to the target component. Usage:
+* `inject("store1", "store2")(observer(MyComponent))`
+* `@inject("store1", "store2") @observer MyComponent`
+* `@inject((stores, props, context) => props) @observer MyComponent`
+* `@observer(["store1", "store2"]) MyComponent` is a shorthand for the the `@inject() @observer` combo.
+
+### `toJS`
+Usage: `toJS(observableDataStructure, options?)`. Converts observable data structures back to plain javascript objects, ignoring computed values.
+
+The `options` include:
+
+- **`detectCycles: boolean`**: Checks for cyclical references in the observable data-structure. Defaults to `true`.
+- **`exportMapsAsObjects: boolean`**: Treats ES6 Maps as regular objects for export. Defaults to `true`
+
+[«details»](tojson.md).
+
+### `isObservable` and `isObservableProp`
+Usage: `isObservable(thing)` or `isObservableProp(thing, property?)`. Returns true if the given thing, or the `property` of the given thing is observable.
+Works for all observables, computed values and disposer functions of reactions.
+
+[«details»](is-observable)
+
+### `isObservableObject|Array|Map` and `isBoxedObservable`
+Usage: `isObservableObject(thing)`, `isObservableArray(thing)`, `isObservableMap(thing)`, `isBoxedObservable(thing)`. Returns `true` if.., well, do the math.
+
+### `isArrayLike`
+Usage: `isArrayLike(thing)`. Returns `true` if the given thing is either a true JS-array or an observable (MobX-)array.
+This is intended as convenience/shorthand.
+Note that observable arrays can be `.slice()`d to turn them into true JS-arrays.
+
+### `isAction`
+Usage: `isAction(func)`. Returns true if the given function is wrapped / decorated with `action`.
+
+### `isComputed` and `isComputedProp`
+Usage: `isComputed(thing)` or `isComputedProp(thing, property?)`. Returns true if the given thing is a boxed computed value, or if the designated property is a computed value.
+
+### `intercept`
+Usage: `intercept(object, property?, interceptor)`.
+Api that can be used to intercept changes before they are applied to an observable api. Useful for validation, normalization or cancellation.
+
+[«details»](observe.md)
+
+### `observe`
+Usage: `observe(object, property?, listener, fireImmediately = false)`
+Low-level api that can be used to observe a single observable value.
+
+[«details»](observe.md)
+
+### `onBecomeObserved` and `onBecomeUnobserved`
+Usage: `onBecomeObserved(observable, property?, listener: () => void): (() => void)` and
+`onBecomeUnobserved(observable, property?, listener: () => void): (() => void)`
+
+These functions are hooks into the observability system of MobX and get notified when observables _start_ / _stop_ becoming observed. It can be used to execute some lazy operations or perform network fetches.
+
+The return value is a _diposer-function_ that will detach the _listener_.
+
+```javascript
+
+export class City {
+ @observable location
+ @observable temperature
+ interval
+
+ constructor(location) {
+ this.location = location
+ // only start data fetching if temperature is actually used!
+ onBecomeObserved(this, 'temperature', this.resume)
+ onBecomeUnobserved(this, 'temperature', this.suspend)
+ }
+
+ resume = () => {
+ log(`Resuming ${this.location}`)
+ this.interval = setInterval(() => this.fetchTemperature(), 5000)
+ }
+
+ suspend = () => {
+ log(`Suspending ${this.location}`)
+ this.temperature = undefined
+ clearInterval(this.interval)
+ }
+
+ fetchTemperature = flow(function*() {
+ // data fetching logic
+ })
+}
+```
+
+### `configure`
+Usage: `configure(options)`.
+Sets global behavior settings on the active MobX instance.
+Use this to change how MobX behaves as a whole.
+
+```javascript
+import { configure } from "mobx";
+
+configure({
+ // ...
+});
+```
+
+#### `arrayBuffer: number`
+Increases the default created size of observable arrays to `arrayBuffer`, if the maximum size isn't yet there.
+
+Observable arrays lazily create getters on members of `ObservableArray.prototype` starting at `0`.
+This will create the members from `0` to `arrayBuffer` if they don't yet exist.
+Use `arrayBuffer` if you know you'll have a common minimum array size and don't want to risk first creating those getters in hot code paths.
+See also `observable`.
+
+#### `computedRequiresReaction: boolean`
+Forbids the access of any unobserved computed value.
+Use this if you want to check whether you are using computed properties without a reactive context.
+
+```javascript
+configure({ computedRequiresReaction: true });
+```
+
+#### `observableRequiresReaction: boolean`
+Warns about any unobserved observable access.
+Use this if you want to check whether you are using observables without a reactive context (eg not inside an autorun, action, or react component without observer wrapping).
+
+```javascript
+configure({ observableRequiresReaction: true });
+```
+
+#### `reactionRequiresObservable: boolean`
+Warns when a reaction (eg `autorun`) is created without any observable access.
+Use this to check whether you are unneededly wrapping react components with `observer`, or to find possible related bugs.
+
+```javascript
+configure({ reactionRequiresObservable: true });
+```
+
+#### `computedConfigurable: boolean`
+Allows overwriting computed values. This is useful for testing purposes *only*. Don't enable this
+ on production as it can cause memory-leaks.
+
+```javascript
+configure({ computedConfigurable: true });
+```
+
+#### `disableErrorBoundaries: boolean`
+By default, MobX will catch and rethrow exceptions happening in your code to make sure that a reaction in one exception does not prevent the scheduled execution of other, possibly unrelated, reactions. This means exceptions are not propagated back to the original causing code and therefore you won't be able to catch them using try/catch.
+
+There may be times when you want to catch those errors, for example when unit testing your reactions. You can disable this behaviour using `disableErrorBoundaries`.
+
+```javascript
+configure({ disableErrorBoundaries: true });
+```
+
+Please note that MobX won't recover from errors when using this configuration. For that reason, you may need to use `_resetGlobalState` after each exception. Example:
+
+```js
+configure({ disableErrorBoundaries: true })
+
+test('Throw if age is negative', () => {
+ expect(() => {
+ const age = observable.box(10)
+ autorun(() => { if (age.get() < 0) throw new Error('Age should not be negative') })
+ age.set(-1)
+ }).toThrow()
+ _resetGlobalState() // Needed after each exception
+})
+```
+
+> Prior to MobX 4, `_resetGlobalState` was `extras.resetGlobalState`.
+
+
+#### `enforceActions`
+
+Also known as "strict mode".
+In strict mode, it is not allowed to change any state outside of an [`action`](action.md).
+Accepted values:
+
+* `"never"` (default): State can be modified from anywhere
+* `"observed"`: All state that is observed _somewhere_ needs to be changed through actions. This is the recommended strictness mode in non-trivial applications.
+* `"always"`: State always needs be updated (which in practice also includes creation) in actions.
+
+#### `isolateGlobalState: boolean`
+
+Isolates the global state of MobX, when there are multiple instances of MobX in the same environment.
+This is useful when you have an encapsulated library that is using MobX, living in the same page as the app that is using MobX.
+The reactivity inside the library will remain self-contained when you call `configure({isolateGlobalState: true})` inside the library.
+
+Without this options, if multiple MobX instances are active, the internal state will be shared. The benefit is that observables from both instances work together, the downside is that the MobX versions have to match.
+
+```javascript
+configure({ isolateGlobalState: true });
+```
+
+#### `reactionScheduler: (f: () => void) => void`
+Sets a new function that executes all MobX reactions.
+By default `reactionScheduler` just runs the `f` reaction without any other behavior.
+This can be useful for basic debugging, or slowing down reactions to visualize application updates.
+
+```javascript
+configure({
+ reactionScheduler: (f): void => {
+ console.log("Running an event after a delay:", f);
+ setTimeout(f, 100);
+ }
+});
+```
+
+## Direct Observable manipulation
+There is now an utility API that enables manipulating observable maps, objects and arrays with the same API. These api's are fully reactive, which means that even new property declarations can be detected by mobx if `set` is used to add them, and `values` or `keys` to iterate them.
+ * **`values(thing)`** returns all values in the collection as array
+ * **`keys(thing)`** returns all keys in the collection as array
+ * **`entries(thing)`** returns a [key, value] pair for all entries in the collection as array
+ * **`set(thing, key, value)`** or **`set(thing, { key: value })`** Updates the given collection with the provided key / value pair(s).
+ * **`remove(thing, key)`** removes the specified child from the collection. For arrays splicing is used.
+ * **`has(thing, key)`** returns true if the collection has the specified _observable_ property.
+ * **`get(thing, key)`** returns the child under the specified key.
+
+
+
+# Development utilities
+
+_The following api's might come in handy if you want to build cool tools on top of MobX or if you want to inspect the internal state of MobX_
+
+### `"mobx-react-devtools"` package
+The mobx-react-devtools is a powerful package that helps you to investigate the performance and dependencies of your react components.
+Also has a powerful logger utility based on `spy`.
+
+[«details»](../best/devtools.md)
+
+### `trace`
+Usage:
+* `trace(enterDebugger?)`
+* `trace(Reaction object / ComputedValue object / disposer function, enterDebugger?)`
+* `trace(object, computedValuePropertyName, enterDebugger?)`
+
+`trace` is a small utility that you can use inside a computed value or reaction.
+If it is enabled, it will start logging when the value is being invalidated, and why.
+If `enterDebugger` is set to true, and developer tools are enabled, the javascript engine
+will break on the point where it is triggered.
+
+[«trace»](../best/trace.md)
+
+### `spy`
+Usage: `spy(listener)`.
+Registers a global spy listener that listens to all events that happen in MobX.
+It is similar to attaching an `observe` listener to *all* observables at once, but also notifies about running (trans/re)actions and computations.
+Used for example by the `mobx-react-devtools`.
+
+[«details»](spy.md)
+
+### `getAtom`
+Usage: `getAtom(thing, property?)`.
+Returns the backing *Atom* of a given observable object, property, reaction etc.
+
+### `getDebugName`
+Usage: `getDebugName(thing, property?)`
+Returns a (generated) friendly debug name of an observable object, property, reaction etc. Used by for example the `mobx-react-devtools`.
+
+### `getDependencyTree`
+Usage: `getDependencyTree(thing, property?)`.
+Returns a tree structure with all observables the given reaction / computation currently depends upon.
+
+### `getObserverTree`
+Usage: `getObserverTree(thing, property?)`.
+Returns a tree structure with all reactions / computations that are observing the given observable.
+
+### `"mobx-react"` development hooks
+The `mobx-react` package exposes the following additional api's that are used by the `mobx-react-devtools`:
+* `trackComponents()`: enables the tracking of `observer` based React components
+* `renderReporter.on(callback)`: callback will be invoked on each rendering of an `observer` enabled React component, with timing information etc
+* `componentByNodeRegistery`: ES6 WeakMap that maps from DOMNode to a `observer` based React component instance
+
+# Internal functions
+
+_The following methods are all used internally by MobX, and might come in handy in rare cases. But usually MobX offers more declarative alternatives to tackle the same problem. They might come in handy though if you try to extend MobX_
+
+### `transaction`
+
+_Transaction is a low-level api, it is recommended to use actions instead_
+
+`transaction(worker: () => void)` can be used to batch a bunch of updates without notifying any observers until the end of the transaction.
+`transaction` takes a single, parameterless `worker` function as argument and runs it.
+No observers are notified until this function has completed.
+`transaction` returns any value that was returned by the `worker` function.
+Note that `transaction` runs completely synchronously.
+Transactions can be nested. Only after completing the outermost `transaction` pending reactions will be run.
+
+```javascript
+import {observable, transaction, autorun} from "mobx";
+
+const numbers = observable([]);
+
+autorun(() => console.log(numbers.length, "numbers!"));
+// Prints: '0 numbers!'
+
+transaction(() => {
+ transaction(() => {
+ numbers.push(1);
+ numbers.push(2);
+ });
+ numbers.push(3);
+});
+// Prints: '3 numbers!'
+```
+
+
+### `untracked`
+
+Untracked allows you to run a piece of code without establishing observers.
+Like `transaction`, `untracked` is automatically applied by `(@)action`, so usually it makes more sense to use actions than to use `untracked` directly.
+Example:
+
+```javascript
+
+const person = observable({
+ firstName: "Michel",
+ lastName: "Weststrate"
+});
+
+autorun(() => {
+ console.log(
+ person.lastName,
+ ",",
+ // this untracked block will return the person's firstName without establishing a dependency
+ untracked(() => person.firstName)
+ );
+});
+// prints: Weststrate, Michel
+
+person.firstName = "G.K.";
+// doesn't print!
+
+person.lastName = "Chesterton";
+// prints: Chesterton, G.K.
+```
+
+### `createAtom`
+Utility function that can be used to create your own observable data structures and hook them up to MobX.
+Used internally by all observable data types.
+
+[«details»](extending.md)
+
diff --git a/docs/refguide/array.md b/docs/refguide/array.md
new file mode 100644
index 000000000..4ed3f6622
--- /dev/null
+++ b/docs/refguide/array.md
@@ -0,0 +1,71 @@
+---
+title: Observable Arrays
+sidebar_label: arrays
+hide_title: true
+---
+
+## Observable Arrays
+
+
+Similar to objects, arrays can be made observable using `observable.array(values?)` or by passing an array to `observable`.
+This works recursively as well, so all (future) values of the array will also be observable.
+
+```javascript
+import {observable, autorun} from "mobx";
+
+var todos = observable([
+ { title: "Spoil tea", completed: true },
+ { title: "Make coffee", completed: false }
+]);
+
+autorun(() => {
+ console.log("Remaining:", todos
+ .filter(todo => !todo.completed)
+ .map(todo => todo.title)
+ .join(", ")
+ );
+});
+// Prints: 'Remaining: Make coffee'
+
+todos[0].completed = false;
+// Prints: 'Remaining: Spoil tea, Make coffee'
+
+todos[2] = { title: 'Take a nap', completed: false };
+// Prints: 'Remaining: Spoil tea, Make coffee, Take a nap'
+
+todos.shift();
+// Prints: 'Remaining: Make coffee, Take a nap'
+```
+
+
+
+Besides all built-in functions, the following goodies are available as well on observable arrays:
+
+* `intercept(interceptor)`. Can be used to intercept any change before it is applied to the array. See [observe & intercept](observe.md)
+* `observe(listener, fireImmediately? = false)` Listen to changes in this array. The callback will receive arguments that express an array splice or array change, conforming to [ES7 proposal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/observe). It returns a disposer function to stop the listener.
+* `clear()` Remove all current entries from the array.
+* `replace(newItems)` Replaces all existing entries in the array with new ones.
+* `find(predicate: (item, index, array) => boolean, thisArg?)` Basically the same as the ES7 `Array.find` proposal.
+* `findIndex(predicate: (item, index, array) => boolean, thisArg?)` Basically the same as the ES7 `Array.findIndex` proposal.
+* `remove(value)` Remove a single item by value from the array. Returns `true` if the item was found and removed.
+* _[MobX 4 and lower]_ `peek()` Returns an array with all the values which can safely be passed to other libraries, similar to `slice()`.
+
+Unlike the built-in implementation of the functions `sort` and `reverse`, observableArray.sort and reverse will not change the array in-place, but only will return a sorted / reversed copy. From MobX 5 and higher this will show a warning. It is recommended to use `array.slice().sort()` instead.
+
+## `observable.array(values, { deep: false })`
+
+Any values assigned to an observable array will be default passed through [`observable`](observable.md) to make them observable.
+Create a shallow array to disable this behavior and store a values as-is. See also [modifiers](modifiers.md) for more details on this mechanism.
+
+## `observable.array(values, { name: "my array" })`
+
+The `name` option can be used to give the array a friendly debug name, to be used in for example `spy` or the MobX dev tools.
+
+## Array limitations in MobX 4 and below
+
+Due to limitations of native arrays in ES5 `observable.array` will create a faux-array (array-like object) instead of a real array.
+In practice, these arrays work just as fine as native arrays and all native methods are supported, including index assignments, up-to and including the length of the array.
+
+Bear in mind however that `Array.isArray(observable([]))` will yield `false`, which some native array manipulation methods require and which some external libraries may also require.
+E.g. `[].concat(observable([]))` will not work as expected since the native array concat method expects the test to return `true`.
+So whenever you need to pass an observable array to an external library or use the observable array as an argument to native array manipulation methods, you should _create a shallow copy by using `array.slice()`_, which will cause `Array.isArray(observable([]).slice())` to yield `true`.
diff --git a/docs/refguide/autorun.md b/docs/refguide/autorun.md
new file mode 100644
index 000000000..09f32c331
--- /dev/null
+++ b/docs/refguide/autorun.md
@@ -0,0 +1,101 @@
+---
+title: autorun
+sidebar_label: autorun
+hide_title: true
+---
+
+# Autorun
+
+
+
+ egghead.io lesson 9: custom reactions
+
+
+
+
+ Hosted on egghead.io
+
+
+`mobx.autorun` can be used in those cases where you want to create a reactive function that will never have observers itself.
+This is usually the case when you need to bridge from reactive to imperative code, for example for logging, persistence, or UI-updating code.
+When `autorun` is used, the provided function will always be triggered once immediately and then again each time one of its dependencies changes.
+In contrast, `computed(function)` creates functions that only re-evaluate if it has
+observers on its own, otherwise its value is considered to be irrelevant.
+As a rule of thumb: use `autorun` if you have a function that should run automatically but that doesn't result in a new value.
+Use `computed` for everything else. Autoruns are about initiating _effects_, not about producing new values.
+If a string is passed as first argument to `autorun`, it will be used as debug name.
+
+The return value from autorun is a disposer function, which can be used to dispose of the autorun when you no longer need it. The reaction itself will also be passed as the only argument to the function given to autorun, which allows you to manipulate it from within the autorun function. This means there are two ways you can dispose of the reaction when you no longer need it:
+```javascript
+const disposer = autorun( reaction => { /* do some stuff */ } );
+disposer();
+
+// or
+
+autorun( reaction => {
+ /* do some stuff */
+ reaction.dispose();
+} );
+```
+
+Just like the [`@observer` decorator/function](./observer-component.md), `autorun` will only observe data that is used during the execution of the provided function.
+
+```javascript
+var numbers = observable([1,2,3]);
+var sum = computed(() => numbers.reduce((a, b) => a + b, 0));
+
+var disposer = autorun(() => console.log(sum.get()));
+// prints '6'
+numbers.push(4);
+// prints '10'
+
+disposer();
+numbers.push(5);
+// won't print anything, nor is `sum` re-evaluated
+```
+
+## Options
+
+Autorun accepts as the second argument an options object with the following optional options:
+
+* `delay`: Number in milliseconds that can be used to debounce the effect function. If zero (the default), no debouncing will happen.
+* `name`: String that is used as name for this reaction in for example [`spy`](spy.md) events.
+* `onError`: function that will handle the errors of this reaction, rather then propagating them.
+* `scheduler`: Set a custom scheduler to determine how re-running the autorun function should be scheduled. It takes a function that should be invoked at some point in the future, for example: `{ scheduler: run => { setTimeout(run, 1000) }}`
+
+## The `delay` option
+
+```javascript
+autorun(() => {
+ // Assuming that profile.asJson returns an observable Json representation of profile,
+ // send it to the server each time it is changed, but await at least 300 milliseconds before sending it.
+ // When sent, the latest value of profile.asJson will be used.
+ sendProfileToServer(profile.asJson);
+}, { delay: 300 });
+```
+
+## The `onError` option
+
+Exceptions thrown in autorun and all other types reactions are caught and logged to the console, but not propagated back to the original causing code.
+This is to make sure that a reaction in one exception does not prevent the scheduled execution of other, possibly unrelated, reactions.
+This also allows reactions to recover from exceptions; throwing an exception does not break the tracking done by MobX,
+so as subsequent run of a reaction might complete normally again if the cause for the exception is removed.
+
+It is possible to override the default logging behavior of Reactions by providing the `onError` option
+Example:
+
+```javascript
+const age = observable.box(10)
+
+const dispose = autorun(() => {
+ if (age.get() < 0)
+ throw new Error("Age should not be negative")
+ console.log("Age", age.get())
+}, {
+ onError(e) {
+ window.alert("Please enter a valid age")
+ }
+})
+```
+
+A global onError handler can be set as well, use `onReactionError(handler)`. This can be useful in tests or for client side error monitoring.
diff --git a/docs/refguide/boxed.md b/docs/refguide/boxed.md
new file mode 100644
index 000000000..ce4de4b79
--- /dev/null
+++ b/docs/refguide/boxed.md
@@ -0,0 +1,54 @@
+---
+title: Boxed Values
+sidebar_label: boxed values
+hide_title: true
+---
+
+## Primitive values and references
+
+
+All primitive values in JavaScript are immutable and hence per definition not observable.
+Usually that is fine, as MobX usually can just make the _property_ that contains the value observable.
+See also [observable objects](object.md).
+In rare cases it can be convenient to have an observable "primitive" that is not owned by an object.
+For these cases it is possible to create an observable box that manages such a primitive.
+
+### `observable.box(value)`
+
+So `observable.box(value)` accepts any value and stores it inside a box.
+The current value can be accessed through `.get()` and updated using `.set(newValue)`.
+
+Furthermore you can register a callback using its `.observe` method to listen to changes on the stored value.
+But since MobX tracks changes to boxes automatically, in most cases it is better to use a reaction like [`mobx.autorun`](autorun.md) instead.
+
+So the signature of object returned by `observable.box(scalar)` is:
+* `.get()` Returns the current value.
+* `.set(value)` Replaces the currently stored value. Notifies all observers.
+* `intercept(interceptor)`. Can be used to intercept changes before they are applied. See [observe & intercept](observe.md)
+* `.observe(callback: (change) => void, fireImmediately = false): disposerFunction`. Registers an observer function that will fire each time the stored value is replaced. Returns a function to cancel the observer. See [observe & intercept](observe.md). The `change` parameter is an object containing both the `newValue` and `oldValue` of the observable.
+
+### `observable.box(value, { deep: false })`
+
+Creates a box based on the [`ref`](modifiers.md) decorator. This means that any (future) value of box wouldn't be converted into an observable automatically.
+
+### Example
+
+```javascript
+import {observable} from "mobx";
+
+const cityName = observable.box("Vienna");
+
+console.log(cityName.get());
+// prints 'Vienna'
+
+cityName.observe(function(change) {
+ console.log(change.oldValue, "->", change.newValue);
+});
+
+cityName.set("Amsterdam");
+// prints 'Vienna -> Amsterdam'
+```
+
+## `observable.box(value, { name: "my array" })`
+
+The `name` option can be used to give the box a friendly debug name, to be used in for example `spy` or the MobX dev tools.
diff --git a/docs/refguide/computed-decorator.md b/docs/refguide/computed-decorator.md
new file mode 100644
index 000000000..04658709a
--- /dev/null
+++ b/docs/refguide/computed-decorator.md
@@ -0,0 +1,231 @@
+---
+title: (@)computed
+sidebar_label: (@)computed
+hide_title: true
+---
+
+# (@)computed
+
+
+
+ egghead.io lesson 3: computed values
+
+
+
+
+ Hosted on egghead.io
+
+
+Computed values are values that can be derived from the existing state or other computed values.
+Conceptually, they are very similar to formulas in spreadsheets.
+Computed values can't be underestimated, as they help you to make your actual modifiable state as small as possible.
+Besides that they are highly optimized, so use them wherever possible.
+
+Don't confuse `computed` with `autorun`. They are both reactively invoked expressions,
+but use `@computed` if you want to reactively produce a *value* that can be used by other observers and
+`autorun` if you don't want to produce a new value but rather want to achieve an *effect*.
+For example imperative side effects like logging, making network requests etc.
+
+Computed values are automatically derived from your state if any value that affects them changes.
+Computed values can be optimized away in many cases by MobX as they are assumed to be pure.
+For example, a computed property won't re-run if none of the data used in the previous computation changed.
+Nor will a computed property re-run if is not in use by some other computed property or reaction.
+In such cases it will be suspended.
+
+This automatic suspension is very convenient. If a computed value is no longer observed, for example the UI in which it was used no longer exists, MobX can automatically garbage collect it. This differs from `autorun`'s values where you must dispose of them yourself.
+It sometimes confuses people new to MobX, that if you create a computed property but don't use it anywhere in a reaction, it will not cache its value and recompute more often than seems necessary.
+However, in real life situations this is by far the best default, and you can always forcefully keep a computed value awake if you need to, by using either [`observe`](observe.md) or [`keepAlive`](https://github.com/mobxjs/mobx-utils#keepalive).
+
+Note that `computed` properties are not enumerable. Nor can they be overwritten in an inheritance chain.
+
+## `@computed`
+
+If you have [decorators enabled](../best/decorators.md) you can use the `@computed` decorator on any getter of a class property to declaratively create computed properties.
+
+```javascript
+import {observable, computed} from "mobx";
+
+class OrderLine {
+ @observable price = 0;
+ @observable amount = 1;
+
+ constructor(price) {
+ this.price = price;
+ }
+
+ @computed get total() {
+ return this.price * this.amount;
+ }
+}
+```
+
+Otherwise, use `decorate` to introduce them:
+
+```javascript
+import {decorate, observable, computed} from "mobx";
+
+class OrderLine {
+ price = 0;
+ amount = 1;
+
+ constructor(price) {
+ this.price = price;
+ }
+
+ get total() {
+ return this.price * this.amount;
+ }
+}
+decorate(OrderLine, {
+ price: observable,
+ amount: observable,
+ total: computed
+})
+```
+
+Both `observable.object` and `extendObservable` will automatically infer getter properties to be computed properties, so the following suffices:
+
+```javascript
+const orderLine = observable.object({
+ price: 0,
+ amount: 1,
+ get total() {
+ return this.price * this.amount
+ }
+})
+```
+
+
+## Setters for computed values
+
+It is possible to define a setter for computed values as well. Note that these setters cannot be used to alter the value of the computed property directly,
+but they can be used as 'inverse' of the derivation. For example:
+
+```javascript
+const orderLine = observable.object({
+ price: 0,
+ amount: 1,
+ get total() {
+ return this.price * this.amount
+ },
+ set total(total) {
+ this.price = total / this.amount // infer price from total
+ }
+})
+```
+
+And similarly
+
+```javascript
+class Foo {
+ @observable length = 2;
+ @computed get squared() {
+ return this.length * this.length;
+ }
+ set squared(value) { //this is automatically an action, no annotation necessary
+ this.length = Math.sqrt(value);
+ }
+}
+```
+
+_Note: always define the setter *after* the getter, some TypeScript versions are known to declare two properties with the same name otherwise._
+
+## `computed(expression)` as function
+
+`computed` can also be invoked directly as function.
+Just like `observable.box(primitive value)` creates a stand-alone observable.
+Use `.get()` on the returned object to get the current value of the computation, or `.observe(callback)` to observe its changes.
+This form of `computed` is not used very often, but in some cases where you need to pass a "boxed" computed value around it might prove useful.
+
+Example:
+
+```javascript
+import {observable, computed} from "mobx";
+var name = observable.box("John");
+
+var upperCaseName = computed(() =>
+ name.get().toUpperCase()
+);
+
+var disposer = upperCaseName.observe(change => console.log(change.newValue));
+
+name.set("Dave");
+// prints: 'DAVE'
+```
+
+## Options for `computed`
+
+When using `computed` as modifier or as box, it accepts a second options argument with the following optional arguments:
+
+* `name`: String, the debug name used in spy and the MobX devtools
+* `context`: The `this` that should be used in the provided expression
+* `set`: The setter function to be used. Without setter it is not possible to assign new values to a computed value. If the second argument passed to `computed` is a function, this is assumed to be a setter.
+* `equals`: By default `comparer.default`. This acts as a comparison function for comparing the previous value with the next value. If this function considers the previous and next values to be equal, then observers will not be re-evaluated. This is useful when working with structural data, and types from other libraries. For example, a computed [moment](https://momentjs.com/) instance could use `(a, b) => a.isSame(b)`. `comparer.structural` comes in handy if you want to use structural comparison to determine whether the new value is different from the previous value (and as a result notify observers).
+* `requiresReaction`: It is recommended to set this one to `true` on very expensive computed values. If you try to read it's value, but the value is not being tracked by some observer (in which case MobX won't cache the value), it will cause the computed to throw, instead of doing an expensive re-evalution.
+* `keepAlive`: don't suspend this computed value if it is not observed by anybody. _Be aware, this can easily lead to memory leaks as it will result in every observable used by this computed value, keeping the computed value in memory!_
+
+## `@computed.struct` for structural comparison
+
+The `@computed` decorator does not take arguments. If you want to to create a computed property which does structural comparison, use `@computed.struct`.
+
+## Built-in comparers
+
+MobX provides three built-in `comparer`s which should cover most needs:
+- `comparer.identity`: Uses the identity (`===`) operator to determine if two values are the same.
+- `comparer.default`: The same as `comparer.identity`, but also considers `NaN` to be equal to `NaN`.
+- `comparer.structural`: Performs deep structural comparison to determine if two values are the same.
+
+## Computed values run more often than expected
+
+Please check the [`pitfalls`](https://mobx.js.org/best/pitfalls.html#computed-values-run-more-often-than-expected) section if you experience this.
+
+## Note on error handling
+
+If a computed value throws an exception during its computation, this exception will be caught and rethrown any time its value is read.
+It is strongly recommended to always throw `Error`'s, so that the original stack trace is preserved. E.g.: `throw new Error("Uhoh")` instead of `throw "Uhoh"`.
+Throwing exceptions doesn't break tracking, so it is possible for computed values to recover from exceptions.
+
+Example:
+
+```javascript
+const x = observable(3)
+const y = observable(1)
+const divided = computed(() => {
+ if (y.get() === 0)
+ throw new Error("Division by zero")
+ return x.get() / y.get()
+})
+
+divided.get() // returns 3
+
+y.set(0) // OK
+divided.get() // Throws: Division by zero
+divided.get() // Throws: Division by zero
+
+y.set(2)
+divided.get() // Recovered; Returns 1.5
+```
+
+## Computeds with arguments
+
+Sometimes you might want to have a computed value that takes one or more arguments.
+In such cases mobx-util's [`computedFn`](https://github.com/mobxjs/mobx-utils#computedfn) can be used:
+
+```typescript
+// Parameterized computed views:
+// Create computed's and store them in a cache
+import { observable } from "mobx"
+import { computedFn } from "mobx-utils"
+
+class Todos {
+ @observable todos = []
+
+ getAllTodosByUser = computedFn(function getAllTodosByUser(userId) {
+ return this.todos.filter(todo => todo.user === userId))
+ })
+}
+```
+
+Note: don't use arrow functions as the `this` would be incorrect.
+
+For further details, check the mobx-utils [docs](https://github.com/mobxjs/mobx-utils#computedfn)
diff --git a/docs/refguide/create-transformer.md b/docs/refguide/create-transformer.md
new file mode 100644
index 000000000..3aa456f3e
--- /dev/null
+++ b/docs/refguide/create-transformer.md
@@ -0,0 +1,191 @@
+---
+title: createTransformer
+sidebar_label: mobxUtils.createTransformer
+hide_title: true
+---
+
+# createTransformer
+
+
+Provided by the `mobx-utils` package.
+
+`createTransformer(transformation: (value: A) => B, onCleanup?: (result: B, value?: A) => void): (value: A) => B`
+
+`createTransformer` turns a function (that should transform value `A` into another value `B`) into a reactive and memoizing function.
+In other words, if the `transformation` function computes B given a specific A, the same B will be returned for all other future invocations of the transformation with the same A.
+However, if A changes, the transformation will be re-applied so that B is updated accordingly.
+And last but not least, if nobody is using the transformation of a specific A anymore, its entry will be removed from the memoization table.
+
+With `createTransformer` it is very easy to transform a complete data graph into another data graph.
+Transformation functions can be composed so that you can build a tree using lots of small transformations.
+The resulting data graph will never be stale, it will be kept in sync with the source by applying small patches to the result graph.
+This makes it very easy to achieve powerful patterns similar to sideways data loading, map-reduce, tracking state history using immutable data structures etc.
+
+The optional `onCleanup` function can be used to get a notification when a transformation of an object is no longer needed.
+This can be used to dispose resources attached to the result object if needed.
+
+Always use transformations inside a reaction like `@observer` or `autorun`.
+Transformations will, like any other computed value, fall back to lazy evaluation if not observed by something, which sort of defeats their purpose.
+
+This all might still be a bit vague, so here are two examples that explain this whole idea of transforming one data structure into another by using small, reactive functions:
+
+## Tracking mutable state using immutable, shared data structures.
+
+This example is taken from the [Reactive2015 conference demo](https://github.com/mobxjs/mobx-reactive2015-demo):
+
+```javascript
+/*
+ The store that holds our domain: boxes and arrows
+*/
+const store = observable({
+ boxes: [],
+ arrows: [],
+ selection: null
+});
+
+/**
+ Serialize store to json upon each change and push it onto the states list
+*/
+const states = [];
+
+autorun(() => {
+ states.push(serializeState(store));
+});
+
+const serializeState = createTransformer(store => ({
+ boxes: store.boxes.map(serializeBox),
+ arrows: store.arrows.map(serializeArrow),
+ selection: store.selection ? store.selection.id : null
+}));
+
+const serializeBox = createTransformer(box => ({...box}));
+
+const serializeArrow = createTransformer(arrow => ({
+ id: arrow.id,
+ to: arrow.to.id,
+ from: arrow.from.id
+}));
+```
+
+In this example the state is serialized by composing three different transformation functions.
+The autorunner triggers the serialization of the `store` object, which in turn serializes all boxes and arrows.
+Let's take closer look at the life of an imaginary example box#3.
+
+1. The first time box#3 is passed by `map` to `serializeBox`,
+the serializeBox transformation is executed and an entry containing box#3 and its serialized representation is added to the internal memoization table of `serializeBox`.
+2. Imagine that another box is added to the `store.boxes` list.
+This would cause the `serializeState` function to re-compute, resulting in a complete remapping of all the boxes.
+However, all the invocations of `serializeBox` will now return their old values from the memoization tables since their transformation functions didn't (need to) run again.
+3. Secondly, if somebody changes a property of box#3 this will cause the application of the `serializeBox` to box#3 to re-compute, just like any other reactive function in MobX.
+Since the transformation will now produce a new Json object based on box#3, all observers of that specific transformation will be forced to run again as well.
+That's the `serializeState` transformation in this case.
+`serializeState` will now produce a new value in turn and map all the boxes again. But except for box#3, all other boxes will be returned from the memoization table.
+4. Finally, if box#3 is removed from `store.boxes`, `serializeState` will compute again.
+But since it will no longer be using the application of `serializeBox` to box#3,
+that reactive function will go back to non-reactive mode.
+This signals the memoization table that the entry can be removed so that it is ready for GC.
+
+So effectively we have achieved state tracking using immutable, shared datas structures here.
+All boxes and arrows are mapped and reduced into single state tree.
+Each change will result in a new entry in the `states` array, but the different entries will share almost all of their box and arrow representations.
+
+## Transforming a datagraph into another reactive data graph
+
+Instead of returning plain values from a transformation function, it is also possible to return observable objects.
+This can be used to transform an observable data graph into a another observable data graph, which can be used to transform... you get the idea.
+
+Here is a small example that encodes a reactive file explorer that will update its representation upon each change.
+Data graphs that are built this way will in general react a lot faster and will consist of much more straight-forward code,
+compared to derived data graph that are updated using your own code. See the [performance tests](https://github.com/mobxjs/mobx/blob/3ea1f4af20a51a1cb30be3e4a55ec8f964a8c495/test/perf/transform-perf.js#L4) for some examples.
+
+Unlike the previous example, the `transformFolder` will only run once as long as a folder remains visible;
+the `DisplayFolder` objects track the associated `Folder` objects themselves.
+
+In the following example all mutations to the `state` graph will be processed automatically.
+Some examples:
+1. Changing the name of a folder will update its own `path` property and the `path` property of all its descendants.
+2. Collapsing a folder will remove all descendant `DisplayFolders` from the tree.
+3. Expanding a folder will restore them again.
+4. Setting a search filter will remove all nodes that do not match the filter, unless they have a descendant that matches the filter.
+5. Etc.
+
+
+
+```javascript
+var m = require('mobx')
+
+function Folder(parent, name) {
+ this.parent = parent;
+ m.extendObservable(this, {
+ name: name,
+ children: m.observable.shallow([]),
+ });
+}
+
+function DisplayFolder(folder, state) {
+ this.state = state;
+ this.folder = folder;
+ m.extendObservable(this, {
+ collapsed: false,
+ get name() {
+ return this.folder.name;
+ },
+ get isVisible() {
+ return !this.state.filter || this.name.indexOf(this.state.filter) !== -1 || this.children.some(child => child.isVisible);
+ },
+ get children() {
+ if (this.collapsed)
+ return [];
+ return this.folder.children.map(transformFolder).filter(function(child) {
+ return child.isVisible;
+ })
+ },
+ get path() {
+ return this.folder.parent === null ? this.name : transformFolder(this.folder.parent).path + "/" + this.name;
+ })
+ });
+}
+
+var state = m.observable({
+ root: new Folder(null, "root"),
+ filter: null,
+ displayRoot: null
+});
+
+var transformFolder = m.createTransformer(function (folder) {
+ return new DisplayFolder(folder, state);
+});
+
+
+// returns list of strings per folder
+var stringTransformer = m.createTransformer(function (displayFolder) {
+ var path = displayFolder.path;
+ return path + "\n" +
+ displayFolder.children.filter(function(child) {
+ return child.isVisible;
+ }).map(stringTransformer).join('');
+});
+
+function createFolders(parent, recursion) {
+ if (recursion === 0)
+ return;
+ for (var i = 0; i < 3; i++) {
+ var folder = new Folder(parent, i + '');
+ parent.children.push(folder);
+ createFolders(folder, recursion - 1);
+ }
+}
+
+createFolders(state.root, 2); // 3^2
+
+m.autorun(function() {
+ state.displayRoot = transformFolder(state.root);
+ state.text = stringTransformer(state.displayRoot)
+ console.log(state.text)
+});
+
+state.root.name = 'wow'; // change folder name
+state.displayRoot.children[1].collapsed = true; // collapse folder
+state.filter = "2"; // search
+state.filter = null; // unsearch
+```
diff --git a/docs/refguide/expr.md b/docs/refguide/expr.md
new file mode 100644
index 000000000..d354647f1
--- /dev/null
+++ b/docs/refguide/expr.md
@@ -0,0 +1,29 @@
+---
+sidebar_label: mobxUtils.expr
+hide_title: true
+---
+
+# Expr
+
+
+Provided by the `mobx-utils` package.
+
+`expr` can be used to create temporary computed values inside computed values.
+Nesting computed values is useful to create cheap computations in order to prevent expensive computations from needing to run.
+
+In the following example, the expression prevents the `TodoView` component from being re-rendered if the selection changes elsewhere.
+Instead, the component will only re-render when the relevant todo is (de)selected, which happens much less frequently.
+
+```javascript
+const TodoView = observer(({todo, editorState}) => {
+ const isSelected = mobxUtils.expr(() => editorState.selection === todo);
+ return
{todo.title}
;
+});
+```
+
+`expr(func)` is an alias for `computed(func).get()`.
+
+Please note that the function given to `expr` will be evaluated _twice_ in the scenario that the overall expression value changes.
+It will be evaluated the first time when any observables it depends on change.
+It will be evaluated a second time when a change in its value triggers the outer computed or reaction to evaluate, which will
+recreate and reevaluate the expression.
diff --git a/docs/refguide/extend-observable.md b/docs/refguide/extend-observable.md
new file mode 100644
index 000000000..f4b25049b
--- /dev/null
+++ b/docs/refguide/extend-observable.md
@@ -0,0 +1,48 @@
+---
+sidebar_label: extendObservable
+hide_title: true
+---
+
+# extendObservable
+
+
+`extendObservable(target, properties, decorators?, options?)`
+
+ExtendObservable can be used to add observable properties to the existing target objects.
+All key / value pairs in the properties map will result in new observable properties on the target initialized to the given value.
+Any getters in the properties map will be turned into computed properties.
+
+The `decorators` param can be used to override the decorator that will be used for a specific property, similar to `decorate` and `observable.object`.
+
+Use the `deep: false` option to make the new properties _shallow_. That is, prevent auto conversion of their _values_ to observables.
+
+```javascript
+var Person = function(firstName, lastName) {
+ // initialize observable properties on a new instance
+ extendObservable(this, {
+ firstName: firstName,
+ lastName: lastName,
+ get fullName() {
+ return this.firstName + " " + this.lastName
+ },
+ setFirstName(firstName) {
+ this.firstName = firstName
+ }
+ }, {
+ setFirstName: action
+ });
+}
+
+var matthew = new Person("Matthew", "Henry");
+
+// add an observable property to an already observable object
+extendObservable(matthew, {
+ age: 353
+});
+```
+
+Note: `observable.object(object)` is actually an alias for `extendObservable({}, object)`.
+
+Note: `decorate` could be used to introduce observable properties to an object, similar to `extendObservable`. The difference is that `extendObservable` is designed to introduce properties directly on the target instance, where `decorate` introduces them on prototypes; you can either pass it a constructor function (class) directly, or an object that will act as prototype for others.
+
+Note: `extendObservable` can not be used to introduce new properties on observable arrays or objects
diff --git a/docs/refguide/extending.md b/docs/refguide/extending.md
new file mode 100644
index 000000000..558288f51
--- /dev/null
+++ b/docs/refguide/extending.md
@@ -0,0 +1,93 @@
+---
+sidebar_label: createAtom
+hide_title: true
+---
+
+# Creating observable data structures and reactions
+
+
+## Atoms
+
+At some point you might want to have more data structures or other things (like streams) that can be used in reactive computations.
+Achieving that is pretty simple by using the concept of atoms.
+Atoms can be used to signal MobX that some observable data source has been observed or changed.
+And MobX will signal the atom whenever it is used or no longer in use.
+
+_Tip: in many cases you can avoid the need to create your own atoms, by just creating a normal observable, and use
+the `onBecomeObserved` or `onBecomeUnobserved` utility to be notified when MobX starts tracking an observable_
+
+
+The following example demonstrates how you can create an observable `Clock`, which can be used in reactive functions,
+and returns the current date-time.
+This clock will only actually tick if it is observed by someone.
+
+The complete API of the `Atom` class is demonstrated by this example.
+
+```javascript
+import {createAtom, autorun} from "mobx";
+
+class Clock {
+ atom;
+ intervalHandler = null;
+ currentDateTime;
+
+ constructor() {
+ // creates an atom to interact with the MobX core algorithm
+ this.atom = createAtom(
+ // first param: a name for this atom, for debugging purposes
+ "Clock",
+ // second (optional) parameter: callback for when this atom transitions from unobserved to observed.
+ () => this.startTicking(),
+ // third (optional) parameter: callback for when this atom transitions from observed to unobserved
+ // note that the same atom transitions multiple times between these two states
+ () => this.stopTicking()
+ );
+ }
+
+ getTime() {
+ // let MobX know this observable data source has been used
+ // reportObserved will return true if the atom is currently being observed
+ // by some reaction.
+ // reportObserved will also trigger the onBecomeObserved event handler (startTicking) if needed
+ if (this.atom.reportObserved()) {
+ return this.currentDateTime;
+ } else {
+ // apparently getTime was called but not while a reaction is running.
+ // So, nobody depends on this value, hence the onBecomeObserved handler (startTicking) won't be fired
+ // Depending on the nature of your atom
+ // it might behave differently in such circumstances
+ // (like throwing an error, returning a default value etc)
+ return new Date();
+ }
+ }
+
+ tick() {
+ this.currentDateTime = new Date();
+ // let MobX know that this data source has changed
+ this.atom.reportChanged();
+ }
+
+ startTicking() {
+ this.tick(); // initial tick
+ this.intervalHandler = setInterval(
+ () => this.tick(),
+ 1000
+ );
+ }
+
+ stopTicking() {
+ clearInterval(this.intervalHandler);
+ this.intervalHandler = null;
+ }
+}
+
+const clock = new Clock();
+
+const disposer = autorun(() => console.log(clock.getTime()));
+
+// ... prints the time each second
+
+disposer();
+
+// printing stops. If nobody else uses the same `clock` the clock will stop ticking as well.
+```
diff --git a/docs/refguide/map.md b/docs/refguide/map.md
new file mode 100644
index 000000000..c270eb169
--- /dev/null
+++ b/docs/refguide/map.md
@@ -0,0 +1,45 @@
+---
+title: Observable Maps
+sidebar_label: maps
+hide_title: true
+---
+
+# Observable Maps
+
+
+## `observable.map(values, options?)`
+
+`observable.map(values?)` creates a dynamic keyed observable map.
+Observable maps are very useful if you don't want to react just to the change of a specific entry, but also to the addition or removal of entries.
+Optionally takes an object, entries array or string keyed [ES6 map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) with initial values.
+
+Using ES6 Map constructor you can initialize observable map using `observable(new Map())` or for class properties using the decorator `@observable map = new Map()`.
+
+The following methods are exposed according to the [ES6 Map spec](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map):
+
+* `has(key)` Returns whether this map has an entry with the provided key. Note that the presence of a key is an observable fact in itself.
+* `set(key, value)`. Sets the given `key` to `value`. The provided key will be added to the map if it didn't exist yet.
+* `delete(key)`. Deletes the given key and its value from the map.
+* `get(key)`. Returns the value at the given key (or `undefined`).
+* `keys()`. Returns an iterator over all keys present in this map. Insertion order is preserved.
+* `values()`. Returns an iterator all values present in this map. Insertion order is preserved.
+* `entries()`. Returns an iterator (insertion ordered) over array that for each key/value pair in the map contains an array `[key, value]`.
+* `forEach(callback:(value, key, map) => void, thisArg?)`. Invokes the given callback for each key / value pair in the map.
+* `clear()`. Removes all entries from this map.
+* `size`. Returns the amount of entries in this map.
+
+The following functions are not in the ES6 spec but are available in MobX:
+* `toJS()`. Converts the observable map back to an normal Map.
+* `toJSON()`. Returns a shallow plain object representation of this map. (For a deep copy use `mobx.toJS(map)`).
+* `intercept(interceptor)`. Registers an interceptor that will be triggered before any changes are applied to the map. See [observe & intercept](observe.md).
+* `observe(listener, fireImmediately?)`. Registers a listener that fires upon each change in this map, similarly to the events that are emitted for [Object.observe](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/observe). See [observe & intercept](observe.md) for more details.
+* `merge(values)`. Copies all entries from the provided object into this map. `values` can be a plain object, array of entries or string-keyed ES6 Map.
+* `replace(values)`. Replaces the entire contents of this map with the provided values.
+## `observable.map(values, { deep: false })`
+
+Any values assigned to an observable map will be default passed through [`observable`](observable.md) to make them observable.
+Create a shallow map to disable this behavior and store are values as-is. See also [decorators](modifiers.md) for more details on this mechanism.
+
+## `observable.map(values, { name: "my map" })`
+
+The `name` option can be used to give the map a friendly debug name, to be used in for example `spy` or the MobX dev tools.
diff --git a/docs/refguide/mobx-utils.md b/docs/refguide/mobx-utils.md
new file mode 100644
index 000000000..49e993759
--- /dev/null
+++ b/docs/refguide/mobx-utils.md
@@ -0,0 +1,9 @@
+---
+sidebar_label: MobX-utils
+hide_title: true
+---
+
+# MobX-utils
+
+[MobX-utils](https://github.com/mobxjs/mobx-utils) provides utility functions and common patterns for MobX.
+
diff --git a/docs/refguide/modifiers.md b/docs/refguide/modifiers.md
new file mode 100644
index 000000000..eac31323d
--- /dev/null
+++ b/docs/refguide/modifiers.md
@@ -0,0 +1,129 @@
+---
+title: Decorators
+sidebar_label: decorators
+hide_title: true
+---
+
+# Decorators
+
+
+In MobX there is a set of decorators that defines how observable properties will behave.
+
+* `observable`: An alias for `observable.deep`.
+* `observable.deep`: This is the default modifier, used by any observable. It clones and converts any (not yet observable) array, Map or plain object into it's observable counterpart upon assignment to the given property
+* `observable.ref`: Disables automatic observable conversion, just creates an observable reference instead.
+* `observable.shallow`: Can only used in combination with collections. Turns any assigned collection into an observable, but the values of that collection will be treated as-is.
+* `observable.struct`: Like `ref`, but will ignore new values that are structurally equal to the current value
+* `computed`: Creates a derived property, see [`computed`](computed-decorator.md)
+* `computed(options)`: Idem, sets additional options.
+* `computed.struct`: Same as `computed`, but will only notify any of it's observers when the value produced by the view is _structurally_ different from the previous value
+* `action`: Creates an action, see [`action`](action.md)
+* `action(name)`: Creates an action, overrides the name
+* `action.bound`: Creates an action, and binds `this` to the instance
+
+Decorators can be used with the api's `decorate`, `observable.object`, `extendObservable` and `observable` (when creating objects) to specify how object members should behave.
+If no decorators are passed in, the default behavior is to use `observable.deep` for any key / value pair, and `computed` for getters.
+
+```javascript
+import {observable, autorun, action} from "mobx";
+
+var person = observable({
+ name: "John",
+ age: 42,
+ showAge: false,
+
+ get labelText() {
+ return this.showAge ? `${this.name} (age: ${this.age})` : this.name;
+ },
+
+ // action:
+ setAge(age) {
+ this.age = age;
+ }
+}, {
+ setAge: action
+ // the other properties will default to observables / computed
+});
+```
+
+```javascript
+class Person {
+ name = "John"
+ age = 42
+ showAge = false
+
+ get labelText() {
+ return this.showAge ? `${this.name} (age: ${this.age})` : this.name;
+ }
+
+ setAge(age) {
+ this.age = age;
+ }
+}
+// when using decorate, all fields should be specified (a class might have many more non-observable internal fields after all)
+decorate(Person, {
+ name: observable,
+ age: observable,
+ showAge: observable,
+ labelText: computed,
+ setAge: action
+})
+```
+
+## Deep observability
+
+When MobX creates an observable object, (using `observable`, `observable.object`, or `extendObservable`), it introduces observable properties which
+by default use the `deep` modifier. The deep modifier basically recursively calls `observable(newValue)` for any newly assigned value.
+Which in turns uses the `deep` modifier... you get the idea.
+
+This is a very convenient default. Without any additional effort all values assigned to an observable will themselves be made observable too (unless they already are), so no additional
+effort is required to make objects deep observable.
+
+## Reference observability
+
+In some cases however, objects don't need to be converted into observables.
+Typical cases are immutable objects, or objects that are not managed by you but by an external library.
+Examples are JSX elements, DOM elements, native objects like History, window or etc.
+To those kind of objects, you just want to store a reference without turning them into an observable.
+
+For these situations there is the `ref` modifier. It makes sure that an observable property is created, which only tracks the reference but doesn't try to convert its value.
+For example:
+
+```javascript
+class Message {
+ @observable message = "Hello world"
+
+ // fictional example, if author is immutable, we just need to store a reference and shouldn't turn it into a mutable, observable object
+ @observable.ref author = null
+}
+```
+
+Or with just ES5 syntax:
+
+```javascript
+function Message() {
+ extendObservable(this, {
+ message: "Hello world",
+ author: null
+ }, {
+ author: observable.ref
+ })
+}
+```
+
+Note that an observable, boxed reference can be created by using `const box = observable.shallowBox(value)`
+
+## Shallow observability
+
+The `observable.shallow` modifier applies observability 'one-level-deep'. You need those if you want to create a _collection_ of observable references.
+If a new collection is assigned to a property with this modifier, it will be made observable, but its values will be left as is, so unlike `deep`, it won't recurse.
+Example:
+
+```javascript
+class AuthorStore {
+ @observable.shallow authors = []
+}
+```
+In the above example an assignment of a plain array with authors to the `authors` will update the authors with an observable array, containing the original, non-observable authors.
+
+Note that `{ deep: false }` can be passed as option to `observable`, `observable.object`, `observable.array`, `observable.map` and `extendObservable` to create shallow collections.
diff --git a/docs/refguide/object-api.md b/docs/refguide/object-api.md
new file mode 100644
index 000000000..0f294efed
--- /dev/null
+++ b/docs/refguide/object-api.md
@@ -0,0 +1,40 @@
+---
+sidebar_label: Object api
+title: Object api
+hide_title: true
+---
+
+## Direct Observable manipulation
+
+
+There is now an utility API that enables manipulating observable maps, objects and arrays with the same API. These api's are fully reactive, which means that even new property declarations can be detected by mobx if `set` is used to add them, and `values` or `keys` to iterate them.
+
+ * **`values(thing)`** returns all values in the collection as array
+ * **`keys(thing)`** returns all keys in the collection as array
+ * **`entries(thing)`** returns a [key, value] pair for all entries in the collection as array
+
+The following methods are not really necessary when using MobX 5, but can be used to achieve MobX-5-like behavior in MobX 4.
+
+ * **`set(thing, key, value)`** or **`set(thing, { key: value })`** Updates the given collection with the provided key / value pair(s).
+ * **`remove(thing, key)`** removes the specified child from the collection. For arrays splicing is used.
+ * **`has(thing, key)`** returns true if the collection has the specified _observable_ property.
+ * **`get(thing, key)`** returns the child under the specified key.
+
+
+```javascript
+import { get, set, observable, values } from "mobx"
+
+const twitterUrls = observable.object({
+ "John": "twitter.com/johnny"
+})
+
+autorun(() => {
+ console.log(get(twitterUrls, "Sara")) // get can track not yet existing properties
+})
+
+autorun(() => {
+ console.log("All urls: " + values(twitterUrls).join(", "))
+})
+
+set(twitterUrls, { "Sara" : "twitter.com/horsejs"})
+```
diff --git a/docs/refguide/object.md b/docs/refguide/object.md
new file mode 100644
index 000000000..85fdf8bc4
--- /dev/null
+++ b/docs/refguide/object.md
@@ -0,0 +1,56 @@
+---
+title: Observable Objects
+sidebar_label: objects
+hide_title: true
+---
+
+## Observable Objects
+
+
+Usage `observable.object(props, decorators?, options?)`
+
+If a plain JavaScript object is passed to `observable` all properties inside will be copied into a clone and made observable.
+(A plain object is an object that wasn't created using a constructor function / but has `Object` as its prototype, or no prototype at all.)
+`observable` is by default applied recursively, so if one of the encountered values is an object or array, that value will be passed through `observable` as well.
+
+```javascript
+import {observable, autorun, action} from "mobx";
+
+var person = observable({
+ // observable properties:
+ name: "John",
+ age: 42,
+ showAge: false,
+
+ // computed property:
+ get labelText() {
+ return this.showAge ? `${this.name} (age: ${this.age})` : this.name;
+ },
+
+ setAge(age) {
+ this.age = age;
+ }
+}, {
+ setAge: action
+});
+
+// object properties don't expose an 'observe' method,
+// but don't worry, 'mobx.autorun' is even more powerful
+autorun(() => console.log(person.labelText));
+
+person.name = "Dave";
+// prints: 'Dave'
+
+person.setAge(21);
+// etc
+```
+
+Some things to keep in mind when making objects observable:
+
+* _[MobX 4 and lower]_ When passing objects through `observable`, only the properties that exist at the time of making the object observable will be observable. Properties that are added to the object at a later time won't become observable, unless [`set`](object-api.md) or [`extendObservable`](extend-observable.md) is used. See this [blog post](https://medium.com/@trekinbami/observe-changes-in-dynamically-keyed-objects-with-mobx-and-react-24b4f857bae9) for the different options available to work with dynamically keyed objects in MobX 4
+* Only plain objects will be made observable. For non-plain objects it is considered the responsibility of the constructor to initialize the observable properties. Either use the [`@observable`](observable.md) annotation or the [`extendObservable`](extend-observable.md) function.
+* Property getters will be automatically turned into derived properties, just like [`@computed`](computed-decorator) would do.
+* `observable` is applied recursively to a whole object graph automatically. Both on instantiation and to any new values that will be assigned to observable properties in the future. Observable will not recurse into non-plain objects.
+* These defaults are fine in 95% of the cases, but for more fine-grained on how and which properties should be made observable, see the [decorators](modifiers.md) section.
+* Pass `{ deep: false }` as 3rd argument to disable the auto conversion of property values
+* Pass `{ name: "my object" }` to assign a friendly debug name to this object
diff --git a/docs/refguide/observable-decorator.md b/docs/refguide/observable-decorator.md
new file mode 100644
index 000000000..ec7ba1d13
--- /dev/null
+++ b/docs/refguide/observable-decorator.md
@@ -0,0 +1,47 @@
+---
+title: @obsevable
+sidebar_label: @observable
+hide_title: true
+---
+
+# @observable
+
+
+
+ egghead.io lesson 1: observable & observer
+
+
+ Hosted on egghead.io
+
+
+
+Decorator that can be used on ES7- or TypeScript class properties to make them observable.
+The `@observable` can be used on instance fields and property getters.
+This offers fine-grained control on which parts of your object become observable.
+
+```javascript
+import { observable, computed } from "mobx";
+
+class OrderLine {
+ @observable price = 0;
+ @observable amount = 1;
+
+ @computed get total() {
+ return this.price * this.amount;
+ }
+}
+```
+
+If your environment doesn't support decorators or field initializers,
+use `decorate` instead (see [decorators](./modifiers.md) for details).
diff --git a/docs/refguide/observable.md b/docs/refguide/observable.md
new file mode 100644
index 000000000..a8223c6f2
--- /dev/null
+++ b/docs/refguide/observable.md
@@ -0,0 +1,66 @@
+---
+title: observable
+sidebar_label: observable
+hide_title: true
+---
+
+# observable
+
+
+
+ egghead.io lesson 1: observable & observer
+
+
+ Hosted on egghead.io
+
+
+
+
+Usage:
+* `observable(value)`
+* `@observable classProperty = value`
+
+Observable values can be JS primitives, references, plain objects, class instances, arrays and maps.
+The following conversion rules are applied, but can be fine-tuned by using *modifiers*. See below.
+
+1. If *value* is an ES6 `Map`: a new [Observable Map](map.md) will be returned. Observable maps are very useful if you don't want to react just to the change of a specific entry, but also to the addition or removal of entries.
+1. If *value* is an ES6 `Set`: a new Observable Set will be returned.
+1. If *value* is an array, a new [Observable Array](array.md) will be returned.
+1. If *value* is an object *without* prototype, all its current properties will be made observable. See [Observable Object](object.md)
+1. If *value* is an object *with* a prototype, a JavaScript primitive or function, `observable` will throw. Use [Boxed Observable](boxed.md) observables instead if you want to create a stand-alone observable reference to such a value. MobX will not make objects with a prototype automatically observable; as that is considered the responsibility of its constructor function. Use `extendObservable` in the constructor, or `@observable` / `decorate` in its class definition instead.
+
+These rules might seem complicated at first sight, but you will notice that in practice they are very intuitive to work with.
+Some notes:
+* To use the `@observable` decorator, make sure that [decorators are enabled](observable-decorator.md) in your transpiler (babel or typescript).
+* By default, making a data structure observable is *infective*; that means that `observable` is applied automatically to any value that is contained by the data structure, or will be contained by the data structure in the future. This behavior can be changed by using *modifiers*.
+* _[MobX 4 and lower]_ To create **dynamically keyed objects** use an [Observable Map](map.md)! Only initially existing properties on an object will be made observable, although new ones can be added using `extendObservable`.
+
+Some examples:
+
+```javascript
+const map = observable.map({ key: "value"});
+map.set("key", "new value");
+
+const list = observable([1, 2, 4]);
+list[2] = 3;
+
+const person = observable({
+ firstName: "Clive Staples",
+ lastName: "Lewis"
+});
+person.firstName = "C.S.";
+
+const temperature = observable.box(20);
+temperature.set(25);
+```
diff --git a/docs/refguide/observe.md b/docs/refguide/observe.md
new file mode 100644
index 000000000..d790d0928
--- /dev/null
+++ b/docs/refguide/observe.md
@@ -0,0 +1,135 @@
+---
+sidebar_label: intercept & observe
+title: Intercept & Observe
+hide_title: true
+---
+
+# Intercept & Observe
+
+
+`observe` and `intercept` can be used to monitor the changes of a single observable (they ***don't*** track nested observables).
+`intercept` can be used to detect and modify mutations before they are applied to the observable.
+`observe` allows you to intercept changes after they have been made.
+
+## Intercept
+Usage: `intercept(target, propertyName?, interceptor)`
+
+* `target`: the observable to guard
+* `propertyName`: optional parameter to specify a specific property to intercept. Note that `intercept(user.name, interceptor)` is fundamentally different from `intercept(user, "name", interceptor)`. The first tries to add an interceptor to the _current_ `value` inside `user.name` (which might not be an observable at all), the latter intercepts changes to the `name` _property_ of `user`.
+* `interceptor`: callback that will be invoked for *each* change that is made to the observable. Receives a single change object describing the mutation.
+
+The `intercept` should tell MobX what needs to happen with the current change.
+Therefore it should do one of the following things:
+1. Return the received `change` object as-is from the function, in which case the mutation will be applied.
+2. Modify the `change` object and return it, for example to normalize the data. Not all fields are modifiable, see below.
+3. Return `null`, this indicates that the change can be ignored and shouldn't be applied. This is a powerful concept to make your objects for example temporarily immutable.
+4. Throw an exception, for example if some invariant isn't met.
+
+The function returns a `disposer` function that can be used to cancel the interceptor when invoked.
+It is possible to register multiple interceptors to the same observable.
+They will be chained in registration order.
+If one of the interceptors returns `null` or throw an exception, the other interceptors won't be evaluated anymore.
+It is also possible to register an interceptor both on a parent object and on an individual property.
+In that case the parent object interceptors are run before the property interceptors.
+
+```javascript
+const theme = observable({
+ backgroundColor: "#ffffff"
+})
+
+const disposer = intercept(theme, "backgroundColor", change => {
+ if (!change.newValue) {
+ // ignore attempts to unset the background color
+ return null;
+ }
+ if (change.newValue.length === 6) {
+ // correct missing '#' prefix
+ change.newValue = '#' + change.newValue;
+ return change;
+ }
+ if (change.newValue.length === 7) {
+ // this must be a properly formatted color code!
+ return change;
+ }
+ if (change.newValue.length > 10) disposer(); // stop intercepting future changes
+ throw new Error("This doesn't like a color at all: " + change.newValue);
+})
+```
+
+## Observe
+Usage: `observe(target, propertyName?, listener, invokeImmediately?)`
+
+* `target`: the observable to observe
+* `propertyName`: optional parameter to specify a specific property to observe. Note that `observe(user.name, listener)` is fundamentally different from `observe(user, "name", listener)`. The first observes the _current_ `value` inside `user.name` (which might not be an observable at all), the latter observes the `name` _property_ of `user`.
+* `listener`: callback that will be invoked for *each* change that is made to the observable. Receives a single change object describing the mutation, except for boxed observables, which will invoke the ` listener` two parameters: `newValue, oldValue`.
+* `invokeImmediately`: by default false. Set it to true if you want `observe` to invoke `listener` directly with the state of the observable (instead of waiting for the first change). Not supported (yet) by all kinds of observables.
+
+The function returns a `disposer` function that can be used to cancel the observer.
+Note that `transaction` does not affect the working of the `observe` method(s).
+This means that even inside a transaction `observe` will fire its listeners for each mutation.
+Hence `autorun` is usually a more powerful and declarative alternative to `observe`.
+
+_`observe` reacts to *mutations*, when they are being made, while reactions like `autorun` or `reaction` react to *new values* when they become available. In many cases the latter is sufficient_
+
+Example:
+
+```javascript
+import {observable, observe} from 'mobx';
+
+const person = observable({
+ firstName: "Maarten",
+ lastName: "Luther"
+});
+
+const disposer = observe(person, (change) => {
+ console.log(change.type, change.name, "from", change.oldValue, "to", change.object[change.name]);
+});
+
+person.firstName = "Martin";
+// Prints: 'update firstName from Maarten to Martin'
+
+disposer();
+// Ignore any future updates
+
+// observe a single field
+const disposer2 = observe(person, "lastName", (change) => {
+ console.log("LastName changed to ", change.newValue);
+});
+```
+Related blog: [Object.observe is dead. Long live mobx.observe](https://medium.com/@mweststrate/object-observe-is-dead-long-live-mobservable-observe-ad96930140c5)
+
+## Event overview
+
+The callbacks of `intercept` and `observe` will receive an event object which has at least the following properties:
+* `object`: the observable triggering the event
+* `type`: (string) the type of the current event
+
+These are the additional fields that are available per type:
+
+| observable type | event type | property | description | available during intercept | can be modified by intercept |
+| -- | --- | ---| --| --| -- |
+| Object | add | name | name of the property being added | √ | |
+| | | newValue | the new value being assigned | √ | √ |
+| | update\* | name | name of the property being updated | √ | |
+| | | newValue | the new value being assigned | √ | √ |
+| | | oldValue | the value that is replaced | | |
+| Array | splice | index | starting index of the splice. Splices are also fired by `push`, `unshift`, `replace` etc. | √ | |
+| | | removedCount | amount of items being removed | √ | √ |
+| | | added | array with items being added | √ | √ |
+| | | removed | array with items that were removed | | |
+| | | addedCount | amount of items that were added | | |
+| | update | index | index of the single entry that is being updated | √ | |
+| | | newValue | the newValue that is / will be assigned | √ | √ |
+| | | oldValue | the old value that was replaced | | |
+| Map | add | name | the name of the entry that was added | √ | |
+| | | newValue | the new value that is being assigned | √ | √ |
+| | update | name | the name of the entry that is being updated | √ | |
+| | | newValue | the new value that is being assigned | √ | √ |
+| | | oldValue | the value that has been replaced | | |
+| | delete | name | the name of the entry that is being removed | √ | |
+| | | oldValue | the value of the entry that was removed | | |
+| Boxed & computed observables | create | newValue | the value that was assigned during creation. Only available as `spy` event for boxed observables | | |
+| | update | newValue | the new value being assigned | √ | √ |
+| | | oldValue | the previous value of the observable | | |
+
+_\* Note that object `update` events won't fire for updated computated values (as those aren't mutations). But it is possible to observe them by explicitly subscribing to the specific property using `observe(object, 'computedPropertyName', listener)`._
diff --git a/docs/refguide/observer-component.md b/docs/refguide/observer-component.md
new file mode 100644
index 000000000..239d79c4a
--- /dev/null
+++ b/docs/refguide/observer-component.md
@@ -0,0 +1,180 @@
+---
+title: (@)observer
+sidebar_label: (@)observer
+hide_title: true
+---
+
+# @observer
+
+
+
+ egghead.io lesson 1: observable & observer
+
+
+
+
+ Hosted on egghead.io
+
+
+The `observer` function / decorator can be used to turn ReactJS components into reactive components.
+It wraps the component's render function in `mobx.autorun` to make sure that any data that is used during the rendering of a component forces a re-rendering upon change.
+It is available through the separate `mobx-react` package.
+
+```javascript
+import { observer } from "mobx-react"
+
+var timerData = observable({
+ secondsPassed: 0
+})
+
+setInterval(() => {
+ timerData.secondsPassed++
+}, 1000)
+
+@observer
+class Timer extends React.Component {
+ render() {
+ return Seconds passed: {this.props.timerData.secondsPassed}
+ }
+}
+
+ReactDOM.render(, document.body)
+```
+
+Tip: when `observer` needs to be combined with other decorators or higher-order-components, make sure that `observer` is the innermost (first applied) decorator;
+otherwise it might do nothing at all.
+
+Note that using `@observer` as decorator is optional, `observer(class Timer ... { })` achieves exactly the same.
+
+## Gotcha: dereference values _inside_ your components
+
+MobX can do a lot, but it cannot make primitive values observable (although it can wrap them in an object see [boxed observables](boxed.md)).
+So not the _values_ that are observable, but the _properties_ of an object. This means that `@observer` actually reacts to the fact that you dereference a value.
+So in our above example, the `Timer` component would **not** react if it was initialized as follows:
+
+```javascript
+React.render(, document.body)
+```
+
+In this snippet just the current value of `secondsPassed` is passed to the `Timer`, which is the immutable value `0` (all primitives are immutable in JS).
+That number won't change anymore in the future, so `Timer` will never update. It is the property `secondsPassed` that will change in the future,
+so we need to access it _in_ the component. Or in other words: values need to be passed _by reference_ and not by value.
+
+## ES5 support
+
+In ES5 environments, observer components can be simple declared using `observer(React.createClass({ ...`. See also the [syntax guide](../best/decorators.md)
+
+## Stateless function components
+
+The above timer widget could also be written using stateless function components that are passed through `observer`:
+
+```javascript
+import { observer } from "mobx-react"
+
+const Timer = observer(({ timerData }) => (
+ Seconds passed: {timerData.secondsPassed}
+))
+```
+
+## Observable local component state
+
+Just like normal classes, you can introduce observable properties on a component by using the `@observable` decorator.
+This means that you can have local state in components that doesn't need to be managed by React's verbose and imperative `setState` mechanism, but is as powerful.
+The reactive state will be picked up by `render` but will not explicitly invoke other React lifecycle methods except `componentWillUpdate` and `componentDidUpdate`.
+If you need other React lifecycle methods, just use the normal React `state` based APIs.
+
+The example above could also have been written as:
+
+```javascript
+import { observer } from "mobx-react"
+import { observable } from "mobx"
+
+@observer
+class Timer extends React.Component {
+ @observable secondsPassed = 0
+
+ componentWillMount() {
+ setInterval(() => {
+ this.secondsPassed++
+ }, 1000)
+ }
+
+ render() {
+ return Seconds passed: {this.secondsPassed}
+ }
+}
+
+ReactDOM.render(, document.body)
+```
+
+For more advantages of using observable local component state, see [3 reasons why I stopped using `setState`](https://medium.com/@mweststrate/3-reasons-why-i-stopped-using-react-setstate-ab73fc67a42e).
+
+## Observable local state in hook based components
+
+To work with local observable state inside function components, the [`useLocalStore`](https://github.com/mobxjs/mobx-react#uselocalstore-hook) and [`useAsObservableSource`](https://github.com/mobxjs/mobx-react#useasobservablesource-hook) hooks can be used.
+
+## Connect components to provided stores using `inject`
+
+egghead.io lesson 8: inject stores with Provider
+
+_Tip: it is recommended to use `React.createContext` instead_
+
+The `mobx-react` package also provides the `Provider` component that can be used to pass down stores using React's context mechanism.
+To connect to those stores, pass a list of store names to `inject`, which will make the stores available as props.
+
+_ N.B. the syntax to inject stores has changed since mobx-react 4, always use `inject(stores)(component)` or `@inject(stores) class Component...`.
+Passing store names directly to `observer` is deprecated._
+
+Example:
+
+```javascript
+const colors = observable({
+ foreground: '#000',
+ background: '#fff'
+});
+
+const App = () =>
+
+
+ ;
+
+const Button = inject("colors")(observer(({ colors, label, onClick }) =>
+
+));
+
+// later..
+colors.foreground = 'blue';
+// all buttons updated
+```
+
+See for more information the [`mobx-react` docs](https://github.com/mobxjs/mobx-react#provider-and-inject).
+
+## When to apply `observer`?
+
+The simple rule of thumb is: _all components that render observable data_.
+If you don't want to mark a component as observer, for example to reduce the dependencies of a generic component package, make sure you only pass it plain data.
+
+With `@observer` there is no need to distinguish 'smart' components from 'dumb' components for the purpose of rendering.
+It is still a good separation of concerns for where to handle events, make requests etc.
+All components become responsible for updating when their _own_ dependencies change.
+Its overhead is neglectable and it makes sure that whenever you start using observable data the component will respond to it.
+See this [thread](https://www.reddit.com/r/reactjs/comments/4vnxg5/free_eggheadio_course_learn_mobx_react_in_30/d61oh0l) for more details.
+
+## Optimizing components
+
+See the relevant [section](../best/react-performance.md).
+
+## Characteristics of observer components
+
+- Observer only subscribe to the data structures that were actively used during the last render. This means that you cannot under-subscribe or over-subscribe. You can even use data in your rendering that will only be available at later moment in time. This is ideal for asynchronously loading data.
+- You are not required to declare what data a component will use. Instead, dependencies are determined at runtime and tracked in a very fine-grained manner.
+- Usually reactive components have no or little state, as it is often more convenient to encapsulate (view) state in objects that are shared with other component. But you are still free to use state.
+- `@observer` implements `shouldComponentUpdate` in the same way as `PureComponent` so that children are not re-rendered unnecessary.
+- Reactive components sideways load data; parent components won't re-render unnecessarily even when child components will.
+- `@observer` does not depend on React's context system.
+- In mobx-react@4+, the props object and the state object of an observer component are automatically made observable to make it easier to create @computed properties that derive from props inside such a component. If you have a reaction (i.e. `autorun`) inside your `@observer` component that must _not_ be re-evaluated when the specific props it uses don't change, be sure to derefence those specific props for use inside your reaction (i.e. `const myProp = props.myProp`). Otherwise, if you reference `props.myProp` inside the reaction, then a change in _any_ of the props will cause the reaction to be re-evaluated. For a typical use case with React-Router, see [this article](https://alexhisen.gitbooks.io/mobx-recipes/content/observable-based-routing.html).
diff --git a/docs/refguide/reaction.md b/docs/refguide/reaction.md
new file mode 100644
index 000000000..e6bcd1951
--- /dev/null
+++ b/docs/refguide/reaction.md
@@ -0,0 +1,115 @@
+---
+title: reaction
+sidebar_label: reaction
+hide_title: true
+---
+
+# Reaction
+
+
+Usage: `reaction(() => data, (data, reaction) => { sideEffect }, options?)`.
+
+A variation on `autorun` that gives more fine grained control on which observables will be tracked.
+It takes two functions, the first one (the *data* function) is tracked and returns data that is used as input for the second one, the *effect* function.
+Unlike `autorun` the side effect won't be run directly when created, but only after the data expression returns a new value for the first time.
+Any observables that are accessed while executing the side effect will not be tracked.
+
+`reaction` returns a disposer function.
+
+The second function (the *effect* function) passed to `reaction` will receive two arguments when invoked.
+The first argument is the value returned by the *data* function. The second argument is the current reaction,
+which can be used to dispose the `reaction` during execution.
+
+It is important to notice that the side effect will *only* react to data that was *accessed* in the data expression, which might be less than the data that is actually used in the effect.
+Also, the side effect will only be triggered when the data returned by the expression has changed.
+In other words: reaction requires you to produce the things you need in your side effect.
+
+## Options
+
+Reaction accepts a third argument as an options object with the following optional options:
+
+* `fireImmediately`: Boolean that indicates that the effect function should immediately be triggered after the first run of the data function. `false` by default.
+* `delay`: Number in milliseconds that can be used to debounce the effect function. If zero (the default), no debouncing will happen.
+* `equals`: `comparer.default` by default. If specified, this comparer function will be used to compare the previous and next values produced by the *data* function. The *effect* function will only be invoked if this function returns false. If specified, this will override `compareStructural`.
+* `name`: String that is used as name for this reaction in for example [`spy`](spy.md) events.
+* `onError`: function that will handle the errors of this reaction, rather then propagating them.
+* `scheduler`: Set a custom scheduler to determine how re-running the autorun function should be scheduled
+
+## Example
+
+In the following example both `reaction1`, `reaction2` and `autorun1` will react to the addition, removal or replacement of todo's in the `todos` array.
+But only `reaction2` and `autorun` will react to the change of a `title` in one of the todo items, because `title` is used in the data expression of reaction 2, while it isn't in the data expression of reaction 1.
+`autorun` tracks the complete side effect, hence it will always trigger correctly, but is also more suspectible to accidentally accessing unrelevant data.
+See also [what will MobX React to?](../best/react).
+
+```javascript
+const todos = observable([
+ {
+ title: "Make coffee",
+ done: true,
+ },
+ {
+ title: "Find biscuit",
+ done: false
+ }
+]);
+
+// wrong use of reaction: reacts to length changes, but not to title changes!
+const reaction1 = reaction(
+ () => todos.length,
+ length => console.log("reaction 1:", todos.map(todo => todo.title).join(", "))
+);
+
+// correct use of reaction: reacts to length and title changes
+const reaction2 = reaction(
+ () => todos.map(todo => todo.title),
+ titles => console.log("reaction 2:", titles.join(", "))
+);
+
+// autorun reacts to just everything that is used in its function
+const autorun1 = autorun(
+ () => console.log("autorun 1:", todos.map(todo => todo.title).join(", "))
+);
+
+todos.push({ title: "explain reactions", done: false });
+// prints:
+// reaction 1: Make coffee, find biscuit, explain reactions
+// reaction 2: Make coffee, find biscuit, explain reactions
+// autorun 1: Make coffee, find biscuit, explain reactions
+
+todos[0].title = "Make tea"
+// prints:
+// reaction 2: Make tea, find biscuit, explain reactions
+// autorun 1: Make tea, find biscuit, explain reactions
+```
+
+In the following example `reaction3`, will react to the change in the `counter` count.
+When invoked `reaction`, second argument can use as disposer.
+The following example shows a `reaction` that is invoked only once.
+
+```javascript
+const counter = observable({ count: 0 });
+
+// invoke once of and dispose reaction: reacts to observable value.
+const reaction3 = reaction(
+ () => counter.count,
+ (count, reaction) => {
+ console.log("reaction 3: invoked. counter.count = " + count);
+ reaction.dispose();
+ }
+);
+
+counter.count = 1;
+// prints:
+// reaction 3: invoked. counter.count = 1
+
+counter.count = 2;
+// prints:
+// (There are no logging, because of reaction disposed. But, counter continue reaction)
+
+console.log(counter.count);
+// prints:
+// 2
+```
+
+Reaction is roughly speaking sugar for: `computed(expression).observe(action(sideEffect))` or `autorun(() => action(sideEffect)(expression))`
diff --git a/docs/refguide/spy.md b/docs/refguide/spy.md
new file mode 100644
index 000000000..613739876
--- /dev/null
+++ b/docs/refguide/spy.md
@@ -0,0 +1,49 @@
+---
+sidebar_label: spy
+title: Spy
+hide_title: true
+---
+
+# Spy
+
+
+Usage: `spy(listener)`.
+Registers a global spy listener that listens to all events that happen in MobX.
+It is similar to attaching an `observe` listener to *all* observables at once, but also notifies about running (trans/re)actions and computations.
+Used for example by the `mobx-react-devtools`.
+
+Example usage of spying all actions:
+```javascript
+spy((event) => {
+ if (event.type === 'action') {
+ console.log(`${event.name} with args: ${event.arguments}`)
+ }
+})
+```
+
+Spy listeners always receive one object, which usually has at least a `type` field. The following events are emitted by default by spy.
+
+| event | fields | nested |
+| --- | --- |--- |
+| action | name, object (scope), arguments | yes |
+| scheduled-reaction | name | no |
+| reaction | name | yes
+| compute | name | no
+| error | message | no |
+| update (array) | object (the array), index, newValue, oldValue | yes
+| update (map) | object (observable map instance), name, newValue, oldValue | yes
+| update (object) | object (instance), name, newValue, oldValue | yes
+| splice (array) | object (the array), index, added, removed, addedCount, removedCount | yes
+| add (map) | object, name, newValue | yes
+| add (object) | object, name, newValue | yes
+| delete (map) | object, name, oldValue | yes
+| create (boxed observable) | object (ObservableValue instance), newValue | yes |
+
+Note that there are events with the signature `{ spyReportEnd: true, time? }`.
+These events might not have a `type` field, but they are part of an earlier fired event that had `spyReportStart: true`.
+This event indicates the end of an event and this way groups of events with sub-events are created.
+This event might report the total execution time as well.
+
+The spy events for observable values are identical to the events passed to `observe`. See [intercept & observe](observe.md) for an extensive overview.
+
+In production builds, the `spy` API is a no-op as it will be minimized away.
\ No newline at end of file
diff --git a/docs/refguide/tojson.md b/docs/refguide/tojson.md
new file mode 100644
index 000000000..0c9894a4e
--- /dev/null
+++ b/docs/refguide/tojson.md
@@ -0,0 +1,35 @@
+---
+sidebar_label: toJS
+title: toJS
+hide_title: true
+---
+
+# toJS
+
+
+`toJS(value, options?)`
+
+Recursively converts an (observable) object to a javascript _structure_.
+Supports observable arrays, objects, maps and primitives.
+Computed values and other non-enumerable properties won't be part of the result.
+Cycles are detected and properly supported by default, but this can be disabled to improve performance.
+
+`toJS` accepts three options
+ 1. `exportMapsAsObjects` whether to serialize observable maps to objects (`true`) or javascript Map objects (`false`) default `true`.
+ 2. `detectCycles` if a cycle is detected, reuse the already serialized object. Which prevents endless recursion. Default `true`.
+ 3. `recurseEverything` detects and converts observable objects that are "behind" non-observable objects.
+
+For more complex (de)serialization scenario's, one can use [serializr](https://github.com/mobxjs/serializr)
+
+```javascript
+var obj = mobx.observable({
+ x: 1
+});
+
+var clone = mobx.toJS(obj);
+
+console.log(mobx.isObservableObject(obj)); // true
+console.log(mobx.isObservableObject(clone)); // false
+```
+
+Note: this method was named `toJSON` before MobX 2.2
diff --git a/docs/refguide/when.md b/docs/refguide/when.md
new file mode 100644
index 000000000..17add9d46
--- /dev/null
+++ b/docs/refguide/when.md
@@ -0,0 +1,58 @@
+---
+title: when
+sidebar_label: when
+hide_title: true
+---
+
+# when
+
+
+
+ egghead.io lesson 9: custom reactions
+
+
+
# MobX
@@ -15,21 +15,21 @@ _Simple, scalable state management_
MobX is proudly sponsored by Mendix, Coinbase, Facebook Open Source, Canva, Algolia, Guilded, Auction Frontier, Mantro and TalentPlot for 100\$/month or more! And beyond that by many [individual backers](#backers) and through [one time contributions](https://github.com/mobxjs/mobx/blob/master/sponsors.md).
**🥇Gold sponsors (\$250+ pm):** 
+
+
**🥈Silver sponsors (\$100+ pm):**
-
-
-
-
-
+
+
+
+
+
+
**🥉Bronze sponsors:**
-
-
+
+
+
# Installation
@@ -67,7 +67,7 @@ _Tip: Consider using the faster and smaller ES6 build if targetting a modern env
- Egghead.io course
- [Ten minute, interactive MobX + React tutorial](https://mobxjs.github.io/mobx/getting-started.html)
-- 
[The MobX book](https://books.google.nl/books?id=ALFmDwAAQBAJ&pg=PP1&lpg=PP1&dq=michel+weststrate+mobx+quick+start+guide:+supercharge+the+client+state+in+your+react+apps+with+mobx&source=bl&ots=D460fxti0F&sig=ivDGTxsPNwlOjLHrpKF1nweZFl8&hl=nl&sa=X&ved=2ahUKEwiwl8XO--ncAhWPmbQKHWOYBqIQ6AEwAnoECAkQAQ#v=onepage&q=michel%20weststrate%20mobx%20quick%20start%20guide%3A%20supercharge%20the%20client%20state%20in%20your%20react%20apps%20with%20mobx&f=false) by Pavan Podila and Michel Weststrate (which despite it's name is in-depth!)
+- 
[The MobX book](https://books.google.nl/books?id=ALFmDwAAQBAJ&pg=PP1&lpg=PP1&dq=michel+weststrate+mobx+quick+start+guide:+supercharge+the+client+state+in+your+react+apps+with+mobx&source=bl&ots=D460fxti0F&sig=ivDGTxsPNwlOjLHrpKF1nweZFl8&hl=nl&sa=X&ved=2ahUKEwiwl8XO--ncAhWPmbQKHWOYBqIQ6AEwAnoECAkQAQ#v=onepage&q=michel%20weststrate%20mobx%20quick%20start%20guide%3A%20supercharge%20the%20client%20state%20in%20your%20react%20apps%20with%20mobx&f=false) by Pavan Podila and Michel Weststrate (which despite its name is in-depth!)
- [Official MobX 4 documentation and API overview](https://mobxjs.github.io/mobx/refguide/api.html) ([MobX 3](https://github.com/mobxjs/mobx/blob/54557dc319b04e92e31cb87427bef194ec1c549c/docs/refguide/api.md), [MobX 2](https://github.com/mobxjs/mobx/blob/7c9e7c86e0c6ead141bb0539d33143d0e1f576dd/docs/refguide/api.md))
- [How to (not) use decorators](https://mobx.js.org/best/decorators.html)
- Videos:
@@ -87,7 +87,7 @@ _Anything that can be derived from the application state, should be derived. Aut
This includes the UI, data serialization, server communication, etc.
-
+
React and MobX together are a powerful combination. React renders the application state by providing mechanisms to translate it into a tree of renderable components. MobX provides the mechanism to store and update the application state that React then uses.
@@ -308,7 +308,7 @@ And finally, kudos to all the people that believed in, tried, validated and even
## Further resources and documentation
-- 
+
+# MobX
+
+_Simple, scalable state management_
+
+[](https://travis-ci.org/mobxjs/mobx)
+[](https://coveralls.io/github/mobxjs/mobx?branch=master)
+[](https://gitter.im/mobxjs/mobx?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[](https://hashnode.com/n/mobx)
+[](#backers)
+[](#sponsors)
+[](https://github.com/prettier/prettier)
+
+
+
+MobX is proudly sponsored by Mendix, Coinbase, Facebook Open Source, Canva, Algolia, Guilded, Auction Frontier, Mantro and TalentPlot for 100\$/month or more! And beyond that by many [individual backers](#backers) and through [one time contributions](https://github.com/mobxjs/mobx/blob/master/sponsors.md).
+
+**🥇Gold sponsors (\$250+ pm):** 
+
+
+**🥈Silver sponsors (\$100+ pm):**
+
+
+
+
+
+
+**🥉Bronze sponsors:**
+
+
+
+
+# Installation
+
+- Installation: `npm install mobx --save`. React bindings: `npm install mobx-react --save`. To enable ESNext decorators (optional), see below.
+- CDN:
+
+* https://unpkg.com/mobx/lib/mobx.umd.js
+* https://cdnjs.com/libraries/mobx
+
+# Browser support
+
+- MobX >=5 runs on any browser with [ES6 proxy support](https://kangax.github.io/compat-table/es6/#test-Proxy). It will throw an error on startup on older environments such as IE11, Node.js <6 or React Native Android on old JavaScriptCore [how-to-upgrade](https://github.com/react-community/jsc-android-buildscripts#how-to-use-it-with-my-react-native-app).
+- MobX 4 runs on any ES5 browser and will be actively maintained. The MobX 4 and 5 api's are the same and semantically can achieve the same, but MobX 4 has some [limitations](#mobx-4-vs-mobx-5).
+
+_Tip: the main entry point of the MobX 5 package ships with ES5 code for backward compatibility with all build tools. But since MobX 5 runs only on modern browsers anyway, consider using the faster and smaller ES6 build: `lib/mobx.es6.js`. For example by setting up a webpack alias: `resolve: { alias: { mobx: __dirname + "/node_modules/mobx/lib/mobx.es6.js" }}`_
+
+## Translations
+
+- [中文](http://cn.mobx.js.org)
+
+## Getting started
+
+- egghead.io course
+- [Ten minute, interactive MobX + React tutorial](https://mobxjs.github.io/mobx/getting-started.html)
+- 
[The MobX book](https://books.google.nl/books?id=ALFmDwAAQBAJ&pg=PP1&lpg=PP1&dq=michel+weststrate+mobx+quick+start+guide:+supercharge+the+client+state+in+your+react+apps+with+mobx&source=bl&ots=D460fxti0F&sig=ivDGTxsPNwlOjLHrpKF1nweZFl8&hl=nl&sa=X&ved=2ahUKEwiwl8XO--ncAhWPmbQKHWOYBqIQ6AEwAnoECAkQAQ#v=onepage&q=michel%20weststrate%20mobx%20quick%20start%20guide%3A%20supercharge%20the%20client%20state%20in%20your%20react%20apps%20with%20mobx&f=false) by Pavan Podila and Michel Weststrate (which despite its name is in-depth!)
+- [Official MobX 4 documentation and API overview](https://mobxjs.github.io/mobx/refguide/api.html) ([MobX 3](https://github.com/mobxjs/mobx/blob/54557dc319b04e92e31cb87427bef194ec1c549c/docs/refguide/api.md), [MobX 2](https://github.com/mobxjs/mobx/blob/7c9e7c86e0c6ead141bb0539d33143d0e1f576dd/docs/refguide/api.md))
+- Videos:
+ - [ReactNext 2016: Real World MobX](https://www.youtube.com/watch?v=Aws40KOx90U) - 40m [slides](https://docs.google.com/presentation/d/1DrI6Hc2xIPTLBkfNH8YczOcPXQTOaCIcDESdyVfG_bE/edit?usp=sharing)
+ - [Practical React with MobX](https://www.youtube.com/watch?v=XGwuM_u7UeQ). In depth introduction and explanation to MobX and React by Matt Ruby on OpenSourceNorth (ES5 only) - 42m.
+ - LearnCode.academy MobX tutorial [Part I: MobX + React is AWESOME (7m)](https://www.youtube.com/watch?v=_q50BXqkAfI) [Part II: Computed Values and Nested/Referenced Observables (12m.)](https://www.youtube.com/watch?v=nYvNqKrl69s)
+ - [Screencast: intro to MobX](https://www.youtube.com/watch?v=K8dr8BMU7-8) - 8m
+ - [Talk: State Management Is Easy, React Amsterdam 2016 conf](https://www.youtube.com/watch?v=ApmSsu3qnf0&feature=youtu.be) ([slides](https://speakerdeck.com/mweststrate/state-management-is-easy-introduction-to-mobx))
+- [Boilerplates and related projects](http://mobxjs.github.io/mobx/faq/boilerplates.html)
+- More tutorials, blogs, videos, and other helpful resources can be found on the [MobX awesome list](https://github.com/mobxjs/awesome-mobx#awesome-mobx)
+
+## Introduction
+
+MobX is a battle tested library that makes state management simple and scalable by transparently applying functional reactive programming (TFRP).
+The philosophy behind MobX is very simple:
+
+_Anything that can be derived from the application state, should be derived. Automatically._
+
+which includes the UI, data serialization, server communication, etc.
+
+
+
+React and MobX together are a powerful combination. React renders the application state by providing mechanisms to translate it into a tree of renderable components. MobX provides the mechanism to store and update the application state that React then uses.
+
+Both React and MobX provide an optimal and unique solutions to common problems in application development. React provides mechanisms to optimally render UI by using a virtual DOM that reduces the number of costly DOM mutations. MobX provides mechanisms to optimally synchronize application state with your React components by using a reactive virtual dependency state graph that is only updated when strictly needed and is never stale.
+
+## Core concepts
+
+MobX has only a few core concepts. The following snippets can be tried online using [codesandbox example](https://codesandbox.io/s/v3v0my2370).
+
+### Observable state
+
+Egghead.io lesson 1: observable & observer
+
+MobX adds observable capabilities to existing data structures like objects, arrays and class instances.
+This can simply be done by annotating your class properties with the [@observable](http://mobxjs.github.io/mobx/refguide/observable-decorator.html) decorator (ES.Next).
+
+```javascript
+import { observable } from "mobx"
+
+class Todo {
+ id = Math.random()
+ @observable title = ""
+ @observable finished = false
+}
+```
+
+Using `observable` is like turning a property of an object into a spreadsheet cell.
+But unlike spreadsheets, these values can be not only primitive values, but also references, objects and arrays.
+
+If your environment doesn't support decorator syntax, don't worry.
+You can read [here](http://mobxjs.github.io/mobx/best/decorators.html) about how to set them up.
+Or you can skip them altogether, as MobX can be used fine without decorator _syntax_, by leveraging the _decorate_ utility.
+Many MobX users do prefer the decorator syntax though, as it is slightly more concise.
+
+```javascript
+import { decorate, observable } from "mobx"
+
+class Todo {
+ id = Math.random()
+ title = ""
+ finished = false
+}
+decorate(Todo, {
+ title: observable,
+ finished: observable
+})
+```
+
+### Computed values
+
+Egghead.io lesson 3: computed values
+
+With MobX you can define values that will be derived automatically when relevant data is modified.
+By using the [`@computed`](http://mobxjs.github.io/mobx/refguide/computed-decorator.html) decorator or by using getter / setter functions when using `(extend)Observable` (Of course, you can use `decorate` here again as alternative to the `@` syntax).
+
+```javascript
+class TodoList {
+ @observable todos = []
+ @computed get unfinishedTodoCount() {
+ return this.todos.filter(todo => !todo.finished).length
+ }
+}
+```
+
+MobX will ensure that `unfinishedTodoCount` is updated automatically when a todo is added or when one of the `finished` properties is modified.
+Computations like these resemble formulas in spreadsheet programs like MS Excel. They update automatically and only when required.
+
+### Reactions
+
+Egghead.io lesson 9: custom reactions
+
+Reactions are similar to a computed value, but instead of producing a new value, a reaction produces a side effect for things like printing to the console, making network requests, incrementally updating the React component tree to patch the DOM, etc.
+In short, reactions bridge [reactive](https://en.wikipedia.org/wiki/Reactive_programming) and [imperative](https://en.wikipedia.org/wiki/Imperative_programming) programming.
+
+#### React components
+
+Egghead.io lesson 1: observable & observer
+
+If you are using React, you can turn your (stateless function) components into reactive components by simply adding the [`observer`](http://mobxjs.github.io/mobx/refguide/observer-component.html) function / decorator from the `mobx-react` package onto them.
+
+```javascript
+import React, { Component } from "react"
+import ReactDOM from "react-dom"
+import { observer } from "mobx-react"
+
+@observer
+class TodoListView extends Component {
+ render() {
+ return (
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+One time donations through paypal are welcome as well and are recorded in the [sponsors](sponsors.md) list.
+
+[](https://mobxjs.github.io/mobx/donate.html)
+
+### Sponsors
+
+Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/mobx#sponsor)]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/assets/action-state-view.png b/docs/assets/action-state-view.png
new file mode 100644
index 000000000..3db0b78b7
Binary files /dev/null and b/docs/assets/action-state-view.png differ
diff --git a/docs/algolia.jpg b/docs/assets/algolia.jpg
similarity index 100%
rename from docs/algolia.jpg
rename to docs/assets/algolia.jpg
diff --git a/docs/auctionfrontier.jpeg b/docs/assets/auctionfrontier.jpeg
similarity index 100%
rename from docs/auctionfrontier.jpeg
rename to docs/assets/auctionfrontier.jpeg
diff --git a/docs/assets/blokt.jpg b/docs/assets/blokt.jpg
new file mode 100644
index 000000000..cd61d242c
Binary files /dev/null and b/docs/assets/blokt.jpg differ
diff --git a/docs/book.jpg b/docs/assets/book.jpg
similarity index 100%
rename from docs/book.jpg
rename to docs/assets/book.jpg
diff --git a/docs/canva.png b/docs/assets/canva.png
similarity index 100%
rename from docs/canva.png
rename to docs/assets/canva.png
diff --git a/docs/assets/codefirst.png b/docs/assets/codefirst.png
new file mode 100644
index 000000000..0d8561af6
Binary files /dev/null and b/docs/assets/codefirst.png differ
diff --git a/docs/coinbase.jpeg b/docs/assets/coinbase.jpeg
similarity index 100%
rename from docs/coinbase.jpeg
rename to docs/assets/coinbase.jpeg
diff --git a/docs/assets/concept.png b/docs/assets/concept.png
new file mode 100644
index 000000000..cd6894448
Binary files /dev/null and b/docs/assets/concept.png differ
diff --git a/docs/assets/devtools-noDisplayName.png b/docs/assets/devtools-noDisplayName.png
new file mode 100644
index 000000000..417316a02
Binary files /dev/null and b/docs/assets/devtools-noDisplayName.png differ
diff --git a/docs/assets/devtools-withDisplayName.png b/docs/assets/devtools-withDisplayName.png
new file mode 100644
index 000000000..98434dcfb
Binary files /dev/null and b/docs/assets/devtools-withDisplayName.png differ
diff --git a/docs/assets/devtools.gif b/docs/assets/devtools.gif
new file mode 100644
index 000000000..cf49646f3
Binary files /dev/null and b/docs/assets/devtools.gif differ
diff --git a/docs/assets/faire.jpg b/docs/assets/faire.jpg
new file mode 100644
index 000000000..45af35aca
Binary files /dev/null and b/docs/assets/faire.jpg differ
diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png
new file mode 100644
index 000000000..63da62bc9
Binary files /dev/null and b/docs/assets/favicon.png differ
diff --git a/docs/fbos.jpeg b/docs/assets/fbos.jpeg
similarity index 100%
rename from docs/fbos.jpeg
rename to docs/assets/fbos.jpeg
diff --git a/docs/flow.png b/docs/assets/flow.png
similarity index 100%
rename from docs/flow.png
rename to docs/assets/flow.png
diff --git a/docs/guilded.jpg b/docs/assets/guilded.jpg
similarity index 100%
rename from docs/guilded.jpg
rename to docs/assets/guilded.jpg
diff --git a/docs/mantro.png b/docs/assets/mantro.png
similarity index 100%
rename from docs/mantro.png
rename to docs/assets/mantro.png
diff --git a/docs/mendix-logo.png b/docs/assets/mendix-logo.png
similarity index 100%
rename from docs/mendix-logo.png
rename to docs/assets/mendix-logo.png
diff --git a/docs/assets/mobservable.png b/docs/assets/mobservable.png
new file mode 100644
index 000000000..386c308ce
Binary files /dev/null and b/docs/assets/mobservable.png differ
diff --git a/docs/assets/mobservable.svg b/docs/assets/mobservable.svg
new file mode 100644
index 000000000..4802b1278
--- /dev/null
+++ b/docs/assets/mobservable.svg
@@ -0,0 +1,118 @@
+
+
+
+
diff --git a/docs/mobx.png b/docs/assets/mobx.png
similarity index 100%
rename from docs/mobx.png
rename to docs/assets/mobx.png
diff --git a/docs/assets/observed-refs.png b/docs/assets/observed-refs.png
new file mode 100644
index 000000000..c02ffe563
Binary files /dev/null and b/docs/assets/observed-refs.png differ
diff --git a/docs/assets/overview.svg b/docs/assets/overview.svg
new file mode 100644
index 000000000..0774d28ab
--- /dev/null
+++ b/docs/assets/overview.svg
@@ -0,0 +1,405 @@
+
+
+
+
diff --git a/docs/assets/overview_bw.svg b/docs/assets/overview_bw.svg
new file mode 100644
index 000000000..a5e60f624
--- /dev/null
+++ b/docs/assets/overview_bw.svg
@@ -0,0 +1,406 @@
+
+
+
+
diff --git a/docs/talentplot.png b/docs/assets/talentplot.png
similarity index 100%
rename from docs/talentplot.png
rename to docs/assets/talentplot.png
diff --git a/docs/assets/trace-tips2.png b/docs/assets/trace-tips2.png
new file mode 100644
index 000000000..56f4c17d2
Binary files /dev/null and b/docs/assets/trace-tips2.png differ
diff --git a/docs/assets/trace.gif b/docs/assets/trace.gif
new file mode 100644
index 000000000..35f171861
Binary files /dev/null and b/docs/assets/trace.gif differ
diff --git a/docs/best/actions.md b/docs/best/actions.md
new file mode 100644
index 000000000..8645b9cec
--- /dev/null
+++ b/docs/best/actions.md
@@ -0,0 +1,212 @@
+---
+sidebar_label: async actions & flows
+title: Writing asynchronous actions
+hide_title: true
+---
+
+
+# Writing asynchronous actions
+
+
+The `action` wrapper / decorator only affects the currently running function, not functions that are scheduled (but not invoked) by the current function!
+This means that if you have a `setTimeout`, promise`.then` or `async` construction, and in that callback some more state is changed, those callbacks should be wrapped in `action` as well! There are several ways to create asynchronous actions. No approach is strictly better than the other, but this section just list different approaches you can take to writing asynchronous code.
+Let's start with a basic example:
+
+### Promises
+
+```javascript
+mobx.configure({ enforceActions: "observed" }) // don't allow state modifications outside actions
+
+class Store {
+ @observable githubProjects = []
+ @observable state = "pending" // "pending" / "done" / "error"
+
+ @action
+ fetchProjects() {
+ this.githubProjects = []
+ this.state = "pending"
+ fetchGithubProjectsSomehow().then(
+ projects => {
+ const filteredProjects = somePreprocessing(projects)
+ this.githubProjects = filteredProjects
+ this.state = "done"
+ },
+ error => {
+ this.state = "error"
+ }
+ )
+ }
+}
+```
+
+The above example would throw exceptions, as the callbacks passed to the `fetchGithubProjectsSomehow` promise are not part of the `fetchProjects` action, as actions only apply to the current stack.
+
+A first simple fix is to extract the callbacks to actions. (Note that binding using `action.bound` is important here to get a correct `this`!):
+
+```javascript
+mobx.configure({ enforceActions: "observed" })
+
+class Store {
+ @observable githubProjects = []
+ @observable state = "pending" // "pending" / "done" / "error"
+
+ @action
+ fetchProjects() {
+ this.githubProjects = []
+ this.state = "pending"
+ fetchGithubProjectsSomehow().then(this.fetchProjectsSuccess, this.fetchProjectsError)
+ }
+
+ @action.bound
+ fetchProjectsSuccess(projects) {
+ const filteredProjects = somePreprocessing(projects)
+ this.githubProjects = filteredProjects
+ this.state = "done"
+ }
+
+ @action.bound
+ fetchProjectsError(error) {
+ this.state = "error"
+ }
+}
+```
+
+Although this is clean and explicit, it might get a bit verbose with complex async flows. Alternative, you can wrap the promise callbacks with the `action` keyword. It is recommended, but not mandatory, to give them a name as well:
+
+```javascript
+mobx.configure({ enforceActions: "observed" })
+
+class Store {
+ @observable githubProjects = []
+ @observable state = "pending" // "pending" / "done" / "error"
+
+ @action
+ fetchProjects() {
+ this.githubProjects = []
+ this.state = "pending"
+ fetchGithubProjectsSomehow().then(
+ // inline created action
+ action("fetchSuccess", projects => {
+ const filteredProjects = somePreprocessing(projects)
+ this.githubProjects = filteredProjects
+ this.state = "done"
+ }),
+ // inline created action
+ action("fetchError", error => {
+ this.state = "error"
+ })
+ )
+ }
+}
+```
+
+### The `runInAction` utility
+
+A downside of inline actions is that TypeScript does not apply type inference on them, so you would have type all your callbacks.
+Instead of creating an action for the entire callback, you can also run only the state modifying part of the callback in an action.
+The advantage of this pattern is that it encourages you to not litter the place with `action`, but rather put all the state modifications as much as possible at the end of the whole process:
+
+```javascript
+mobx.configure({ enforceActions: "observed" })
+
+class Store {
+ @observable githubProjects = []
+ @observable state = "pending" // "pending" / "done" / "error"
+
+ @action
+ fetchProjects() {
+ this.githubProjects = []
+ this.state = "pending"
+ fetchGithubProjectsSomehow().then(
+ projects => {
+ const filteredProjects = somePreprocessing(projects)
+ // put the 'final' modification in an anonymous action
+ runInAction(() => {
+ this.githubProjects = filteredProjects
+ this.state = "done"
+ })
+ },
+ error => {
+ // the alternative ending of this process:...
+ runInAction(() => {
+ this.state = "error"
+ })
+ }
+ )
+ }
+}
+```
+
+Note that `runInAction`'s can also be given a name as first argument. `runInAction(f)` is in fact just sugar for `action(f)()`
+
+### async / await
+
+Async / await based functions can initially seem confusing when starting with actions.
+Because lexically they appear to synchronous functions, it gives the impression that `@action` applies to the entire function.
+Which is of course not the case, as async / await is just syntactic sugar around a promise based process.
+As a result, `@action` only applies to the code block until the first `await`.
+And after each `await` a new asynchronous function is started, so after each `await`, state modifying code should be wrapped as action.
+This is where `runInAction` comes in handy again:
+
+```javascript
+mobx.configure({ enforceActions: "observed" })
+
+class Store {
+ @observable githubProjects = []
+ @observable state = "pending" // "pending" / "done" / "error"
+
+ @action
+ async fetchProjects() {
+ this.githubProjects = []
+ this.state = "pending"
+ try {
+ const projects = await fetchGithubProjectsSomehow()
+ const filteredProjects = somePreprocessing(projects)
+ // after await, modifying state again, needs an actions:
+ runInAction(() => {
+ this.state = "done"
+ this.githubProjects = filteredProjects
+ })
+ } catch (error) {
+ runInAction(() => {
+ this.state = "error"
+ })
+ }
+ }
+}
+```
+
+### flows
+
+However, a nicer approach is to use the built-in concept of `flow`s. They use generators. Which might look scary in the beginning, but it works the same as `async` / `await`. Just use `function *` instead of `async` and `yield` instead of `await`.
+The advantage of `flow` is that it is syntactically very close to async / await (with different keywords), and no manually action wrapping is needed for async parts, resulting in very clean code.
+
+`flow` can be used only as function and not as decorator.
+`flow` integrates neatly with MobX development tools, so that it is easy to trace the process of the async function.
+
+```javascript
+mobx.configure({ enforceActions: "observed" })
+
+class Store {
+ @observable githubProjects = []
+ @observable state = "pending"
+
+ fetchProjects = flow(function * () { // <- note the star, this a generator function!
+ this.githubProjects = []
+ this.state = "pending"
+ try {
+ const projects = yield fetchGithubProjectsSomehow() // yield instead of await
+ const filteredProjects = somePreprocessing(projects)
+ // the asynchronous blocks will automatically be wrapped in actions and can modify state
+ this.state = "done"
+ this.githubProjects = filteredProjects
+ } catch (error) {
+ this.state = "error"
+ }
+ })
+}
+```
+
+#### Flows can be cancelled
+
+Flows are cancellable, that means that you can call `cancel()` on the returned promise. This will stop the generator immediately, but any finally clause will still be processed. The returned promise itself will reject with `FLOW_CANCELLED`.
diff --git a/docs/best/decorators.md b/docs/best/decorators.md
new file mode 100644
index 000000000..28188ee7d
--- /dev/null
+++ b/docs/best/decorators.md
@@ -0,0 +1,192 @@
+---
+sidebar_label: How to (not) use decorator syntax
+title: How to (not) use decorators
+hide_title: true
+---
+
+
+# How to (not) use decorators
+
+
+Using ES.next decorators in MobX is optional. This section explains how to use them, or how to avoid them.
+
+Advantages of using decorator syntax:
+
+* Minimizes boilerplate, declarative.
+* Easy to use and read. A majority of the MobX users use them.
+
+Disadvantages of using decorator syntax:
+
+* Stage-2 ES.next feature
+* Requires a little setup and transpilation, only supported with Babel / Typescript transpilation so far
+
+You can approach using decorators in two ways in MobX
+
+1. Enable the currently experimental decorator syntax in your compiler (read on)
+2. Don't enable decorator syntax, but leverage the MobX built-in utility `decorate` to apply decorators to your classes / objects.
+
+Using decorator syntax:
+
+```javascript
+import { observable, computed, action } from "mobx";
+
+class Timer {
+ @observable start = Date.now();
+ @observable current = Date.now();
+
+ @computed
+ get elapsedTime() {
+ return this.current - this.start + "milliseconds";
+ }
+
+ @action
+ tick() {
+ this.current = Date.now();
+ }
+}
+```
+
+Using the `decorate` utility:
+
+```javascript
+import { observable, computed, action, decorate } from "mobx";
+
+class Timer {
+ start = Date.now();
+ current = Date.now();
+
+ get elapsedTime() {
+ return this.current - this.start + "milliseconds";
+ }
+
+ tick() {
+ this.current = Date.now();
+ }
+}
+decorate(Timer, {
+ start: observable,
+ current: observable,
+ elapsedTime: computed,
+ tick: action
+});
+```
+
+For applying multiple decorators on a single property, you can pass an array of decorators. The decorators application order is from right to left.
+
+```javascript
+import { decorate, observable } from "mobx"
+import { serializable, primitive } from "serializr"
+import persist from "mobx-persist";
+
+class Todo {
+ id = Math.random();
+ title = "";
+ finished = false;
+}
+decorate(Todo, {
+ title: [serializable(primitive), persist("object"), observable],
+ finished: [serializable(primitive), observable]
+})
+```
+Note: Not all decorators can be composed together, and this functionality is just best-effort. Some decorators affect the instance directly and can 'hide' the effect of other decorators that only change the prototype.
+
+---
+
+The `observer` function from `mobx-react` is both a decorator and a function, that means that all these syntax variants will work:
+
+```javascript
+@observer
+class Timer extends React.Component {
+ /* ... */
+}
+
+const Timer = observer(class Timer extends React.Component {
+ /* ... */
+})
+
+const Timer = observer((props) => (
+ /* rendering */
+))
+```
+
+## Enabling decorator syntax
+
+If you want to use decorators follow the following steps.
+
+**TypeScript**
+
+Enable the compiler option `"experimentalDecorators": true` in your `tsconfig.json`.
+
+**Babel 6: using `babel-preset-mobx`**
+
+A more convenient way to setup Babel for usage with mobx is to use the [`mobx`](https://github.com/zwhitchcox/babel-preset-mobx) preset, that incorporates decorators and several other plugins typically used with mobx:
+
+```
+npm install --save-dev babel-preset-mobx
+```
+
+.babelrc:
+
+```json
+{
+ "presets": ["mobx"]
+}
+```
+
+**Babel 6: manually enabling decorators**
+
+To enable support for decorators without using the mobx preset, follow the following steps.
+Install support for decorators: `npm i --save-dev babel-plugin-transform-decorators-legacy`. And enable it in your `.babelrc` file:
+
+```json
+{
+ "presets": ["es2015", "stage-1"],
+ "plugins": ["transform-decorators-legacy"]
+}
+```
+
+Note that the order of plugins is important: `transform-decorators-legacy` should be listed _first_.
+Having issues with the babel setup? Check this [issue](https://github.com/mobxjs/mobx/issues/105) first.
+
+**Babel 7**
+
+Install support for decorators: `npm i --save-dev @babel/plugin-proposal-class-properties @babel/plugin-proposal-decorators`. And enable it in your `.babelrc` file:
+
+```json
+{
+ "plugins": [
+ ["@babel/plugin-proposal-decorators", { "legacy": true}],
+ ["@babel/plugin-proposal-class-properties", { "loose": true}]
+ ]
+}
+```
+
+Note that the `legacy` mode is important (as is putting the decorators proposal first). Non-legacy mode is [WIP](https://github.com/mobxjs/mobx/pull/1732).
+
+## Decorator syntax and Create React App (v1)
+
+* Decorators are not supported out of the box in `create-react-app@1.*`. To fix this, you can either use the `decorate` utility, eject, or use the [react-app-rewired](https://github.com/timarney/react-app-rewired/tree/master/packages/react-app-rewire-mobx) package.
+
+## Decorator syntax and Create React App (v2)
+
+* Decorators are only supported out of the box when using TypeScript in `create-react-app@^2.1.1`. In older versions or when using vanilla JavaScript use either the `decorate` utility, eject, or the [customize-cra](https://github.com/arackaf/customize-cra) package.
+
+---
+
+## Disclamer: Limitations of decorator syntax:
+
+_The current transpiler implementations of decorator syntax are quite limited and don't behave exactly the same.
+Also, many compositional patterns are currently not possible with decorators, until the stage-2 proposal has been implemented by all transpilers.
+For this reason the scope of decorator syntax support in MobX is currently scoped to make sure that the supported features
+behave consistently accross all environments_
+
+The following patterns are not officially supported by the MobX community:
+
+* Redefining decorated class members in inheritance trees
+* Decorating static class members
+* Combining decorators provided by MobX with other decorators
+* Hot module reloading (HMR) / React-hot-loader might not work as expected
+
+Decorated properties might not be visible yet on class instances as _own_ property until the first read / write to that property occurred.
+
+(N.B.: not supported doesn't mean it doesn't work, it means that if it doesn't work, reported issues will not be processed until the official spec has been moved forward)
diff --git a/docs/best/devtools.md b/docs/best/devtools.md
new file mode 100644
index 000000000..473daa59c
--- /dev/null
+++ b/docs/best/devtools.md
@@ -0,0 +1,43 @@
+---
+sidebar_label: MobX + React DevTools
+title: MobX + React DevTools
+hide_title: true
+---
+
+# MobX + React DevTools
+
+
+
+
+
+MobX ships with DevTools that can be used to track the rendering behavior and data dependencies of your app.
+
+
+
+## Usage:
+
+Install:
+
+`npm install mobx-react-devtools`
+
+To enable devtools, import and render the devtools somewhere in your codebase.
+
+```JS
+import DevTools from 'mobx-react-devtools'
+
+const App = () => (
+