1 | [![Build Status](https://travis-ci.org/mobxjs/mobx-angular.svg?branch=master)](https://travis-ci.org/mobxjs/mobx-angular)
|
2 | [![npm version](https://badge.fury.io/js/mobx-angular.svg)](https://badge.fury.io/js/mobx-angular)
|
3 | # mobx-angular
|
4 |
|
5 | ## MobX connector for Angular (versions 2, 4, 5)
|
6 | If you're looking for the Angular 1 version version, it's [here](https://github.com/NgMobx/ng1-mobx)
|
7 |
|
8 | ## Features
|
9 | 1. The library allows you to automatically observe all the observables that your component uses
|
10 | 2. Automatically runs change detection - works great with OnPush strategy
|
11 | 3. Disposes of all the observers when the component is destroyed
|
12 | 4. Debugging tools
|
13 |
|
14 | ## Usage
|
15 |
|
16 | Install:
|
17 | ```
|
18 | $ npm install --save mobx-angular mobx
|
19 | ```
|
20 |
|
21 | Import the MobxAngularModule:
|
22 | ```ts
|
23 | import { MobxAngularModule } from 'mobx-angular';
|
24 |
|
25 | @NgModule({
|
26 | imports: [..., MobxAngularModule]
|
27 | })
|
28 | export class MyModule {}
|
29 | ```
|
30 |
|
31 | ## autorun
|
32 | Use `*mobxAutorun` directive in your template:
|
33 | ```ts
|
34 | import { Component, ChangeDetectionStrategy } from '@angular/core';
|
35 | import {store} from './store/counter';
|
36 |
|
37 | @Component({
|
38 | changeDetection: ChangeDetectionStrategy.OnPush,
|
39 | template: `
|
40 | <div *mobxAutorun>
|
41 | {{ store.value }} - {{ store.computedValue }}
|
42 | <button (click)="store.action">Action</button>
|
43 | </div>
|
44 | `
|
45 | })
|
46 | export class AppComponent {
|
47 | store = store;
|
48 | }
|
49 | ```
|
50 |
|
51 | The directive will do the following:
|
52 | - Run `detach` on the view under *mobxAutorun (disables change detection)
|
53 | - Observe all the observables / computed values that your component uses
|
54 | - Automatically run the `detectChanges` method whenever there's a relevant change
|
55 |
|
56 | Under the hood, this magic happens by running `autorun(() => view.detecChanges)`
|
57 |
|
58 | ## dontDetach
|
59 | If you rather not detach your view from Change Detection - you can pass a config object to mobxAutorun:
|
60 | ```
|
61 | <ng-container *mobxAutorun="{ dontDetach: true }">
|
62 | ...
|
63 | </ng-container>
|
64 | ```
|
65 |
|
66 | But notice that this misses the purpose of using *mobxAutorun for better performance.
|
67 | If you need something outside of the store you have 2 options without disabling detach:
|
68 | - Define local component properties as observables or computed values
|
69 | - Surround with *mobxAutorun only the parts that actually use observable / computed values from the store
|
70 |
|
71 | ## autorunSync
|
72 | This method is deprecated - do not use it
|
73 |
|
74 | ## reaction
|
75 | Aside from autorun, MobX allows you to react to specific data changes.
|
76 |
|
77 | Usage:
|
78 | ```ts
|
79 | import { Component, ChangeDetectionStrategy } from '@angular/core';
|
80 |
|
81 | @Component({
|
82 | changeDetection: ChangeDetectionStrategy.OnPush,
|
83 | template: `<div *mobxReaction="getParity.bind(this)">
|
84 | {{ parity }}
|
85 | </div>`
|
86 | })
|
87 | class AppComponent {
|
88 | getParity() {
|
89 | return this.parity = store.counter % 2 ? 'Odd' : 'Even';
|
90 | }
|
91 | }
|
92 | ```
|
93 | The `callback` function will automatically re-run whenever any observable that it uses changes.
|
94 | Change Detection will run automatically whenever the return value of `callback` changes.
|
95 | If you don't return anything, change detection will not run.
|
96 |
|
97 | In this example, the `parity` property will be updated according to `counter`,
|
98 | and change detection will run only when the `parity` changes.
|
99 |
|
100 | ## Injectable stores
|
101 | You can easily make your stores injectable:
|
102 | ```ts
|
103 | import { observable, action } from 'mobx-angular';
|
104 |
|
105 | @Injectable()
|
106 | class Store {
|
107 | @observable value;
|
108 | @action doSomething() { ... }
|
109 | }
|
110 | ```
|
111 | ## Using with OnPush or ngZone: 'noop'
|
112 | To achieve great performance, you can set `OnPush` change detection strategy on your components (this can be configured as default in `.angular-cli.json`).
|
113 | MobX will run change detection manually for you on the components that need to be updated.
|
114 |
|
115 | * In Angular 5 there's a new option, which is to disable Zone completely when bootstrapping the app (ngZone: 'noop').
|
116 | Please note that this means that all 3rd-party components will stop working (because they rely on change detection to work via Zone).
|
117 |
|
118 | ## Debugging MobX
|
119 | mobx-angular comes with a handy debug tool.
|
120 | To turn on / off the debug tool, open developer tools' console, and run:
|
121 | ```ts
|
122 | mobxAngularDebug(true) // turn on
|
123 | mobxAngularDebug(false) // turn off
|
124 | ```
|
125 | Then you can right-click on the components that use mobx directives, and you will see a console log of the components' dependencies.
|
126 | Also, every action that happens in mobx will be console.logged in a nice way.
|
127 |
|
128 | ## Examples
|
129 | See the `example` folder, specifically these files:
|
130 | `/example/todos/src/app/stores/todos.ts`
|
131 | `/example/todos/src/app/app.component.ts`
|
132 |
|
133 | To run the examples, clone this repo and run:
|
134 | ```
|
135 | $ npm install -g @angular/cli
|
136 | $ cd example/<example-folder>
|
137 | $ npm install
|
138 | $ ng serve
|
139 | ```
|