Full documentation can be found on the site:

mobx-keystone.js.org

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.

Introduction

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.

Quick links

• Installation
• Class Models
• Todo List Example
• MST Migration Guide
• API docs

Quick glance

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)

Why teams choose mobx-keystone

• 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.

What users are saying

"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."

• @finallyblueskies, #538

"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!"

• @robclouth, #146

How it works

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.

Requirements

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.

Installation

npm install mobx-keystone

yarn add mobx-keystone

pnpm add mobx-keystone