A MobX powered state management solution based on data trees with first-class support for TypeScript, snapshots, patches and much more
New! Y.js bindings for mobx-keystone are now available in the mobx-keystone-yjs package as well as a working example in the examples section of the online docs.
New! Loro CRDT bindings for mobx-keystone are now available in the mobx-keystone-loro package with native move operation support for arrays, as well as a working example in the examples section of the online docs.
mobx-keystone helps you build complex client-side apps with a single source of truth, mutable model code, and immutable traceability built in.
You write straightforward actions and computed values, while the library gives you snapshots, patches, undo/redo, and runtime protection on top.
You can think of it as a TypeScript-first model layer on top of MobX that scales better as your domain grows.
import { computed } from "mobx"
import { Model, model, modelAction, prop, registerRootStore } from "mobx-keystone"
@model("todo/Todo")
class Todo extends Model({
text: prop<string>(""),
done: prop(false),
}) {
@modelAction
toggle() {
this.done = !this.done
}
}
@model("todo/Store")
class TodoStore extends Model({
todos: prop<Todo[]>(() => []),
}) {
@computed
get pendingCount() {
return this.todos.filter((t) => !t.done).length
}
@modelAction
addTodo(text: string) {
this.todos.push(new Todo({ text }))
}
}
const store = new TodoStore({})
registerRootStore(store)- Mutable action code with protected updates, so state changes stay explicit and safe.
- Runtime snapshots and JSON patches for persistence, sync, replay, and debugging.
- Built-in primitives for references, transactions, action middlewares, and undo/redo.
- Strong TypeScript inference for models, snapshots, and actions.
- Composable domain models that stay maintainable as app complexity grows.
- Seamless integration with MobX and
mobx-react-lite.
"I've never been so in love with a tool. [...] In my eyes it is the perfect state management tool for TS/React projects. [...] Building complex clientside apps has never been so easy and fun for me."
"I'm absolutely loving this project. [...] It's taken all the best bits from mobx and mobx-state-tree and put them into a single package that's a joy to work with. [...] You've literally thought of everything!"
At the center of mobx-keystone is a living tree of mutable but strictly protected models, arrays, and plain objects.
You update state through model actions, and immutable structurally shared snapshots are derived automatically.
This gives you mutability where it helps developer experience, plus immutable traceability where it helps reliability.
Trees can only be modified by actions that belong to the same subtree. Actions are replayable and can be distributed, and fine-grained changes can be observed as JSON patches.
Because mobx-keystone uses MobX behind the scenes, it integrates naturally with mobx and mobx-react-lite.
The snapshot and middleware system also makes it possible to replace a Redux reducer/store pair with model-driven state and connect Redux devtools.
mobx-keystone consists of composable models that capture domain state and behavior together.
Model instances are created from props, protect their own updates, and reconcile efficiently when applying snapshots.
This library requires a more or less modern JavaScript environment to work, namely one with support for:
- MobX 6, 5, or 4 (with its gotchas)
- Proxies
- Symbols
- WeakMap/WeakSet
In other words, it should work on mostly anything except it won't work in Internet Explorer.
If you are using TypeScript, then version >= 4.2.0 is recommended, though it might work with older versions.
npm install mobx-keystone
yarn add mobx-keystone
pnpm add mobx-keystone
