Skip to main content

Introduction

mobx-keystone gives you MobX-powered, TypeScript-first state trees: a single source of truth, mutable model code, and immutable traceability built in.

Quick glance​

Straightforward models. Explicit actions. Reactive state.

Todo.ts
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)

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.

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.
  • Optional Y.js and Loro bindings for collaborative, offline-friendly state.
  • 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.

Choose your starting point​

Getting Started →Set up a first store in a real app. Class Models →The main model style for app state. Data Models →Backend-shaped data without $modelType. Root Stores →App life-cycle and where side effects belong. Snapshots →Immutable, serializable views of any part of the tree. Coming from MST? →Concepts, terminology and a step-by-step migration.

See it running​

Each example is a working app running right in the page, with its full source below it.

Todo List →A complete app with live logs of its actions, patches and snapshots. Client/Server →Two clients kept in sync through a server by replaying actions. Y.js Binding →Two replicas of the same store, synced as a Y.js CRDT over WebRTC. Loro Binding →Two replicas of the same store, synced as a Loro CRDT in the browser.

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.