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.

• Start here: Installation
• Learn by building: Class Models
• See a full example: Todo List Example
• Migrating from MST: Migration Guide
• API reference: 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.

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

"Thank you for this amazing library. [...] After evaluating every state library out there, mobx-keystone stands out [...] a true single source of truth for records, first-class relationships [...] first-class reactivity."

• @lolmaus, #566

"First of all thank you for this amazing library, it really is a joy to work with."

• @exception-producer, #559

"mobx-keystone is awesome and way easier to use for typesafe domain modeling than MST."

• @krnsk0, #467

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

Resources for LLM workflows

Need markdown exports for AI/LLM tools? See llms.txt, llms-full.txt, or the MD docs intro.