Installation

This page is only about setup: install the packages, choose your decorator mode, and make sure your toolchain is configured correctly.

If you want to build a first working store after setup, continue with Getting Started.

npm

npm install mobx mobx-keystone

pnpm

pnpm add mobx mobx-keystone

yarn

yarn add mobx mobx-keystone

mobx-keystone requires mobx as a peer dependency, so both packages need to be installed.

When using TypeScript, version 5.4 or newer is required.

If you are using React, add mobx-react-lite too:

npm

npm install mobx-react-lite

pnpm

pnpm add mobx-react-lite

yarn

yarn add mobx-react-lite

This library requires a modern JavaScript environment with support for:

• MobX 7, 6, 5 (or 4 with its gotchas)
• Proxies
• Symbols
• WeakMap/WeakSet

In practice, this covers current browsers and Node.js releases, but not Internet Explorer.

If you are using TypeScript:

• Version 5.0+ is recommended (standard decorators).
• mobx-keystone decorators also support the legacy transform (experimentalDecorators: true).

MobX 7 itself no longer supports legacy decorators. When using MobX 7, choose the standard decorator transform for code that uses MobX decorators such as @computed, @action, or @observable.

Setup checklist

Before writing your first model, make sure your app setup matches these assumptions:

• mobx is installed next to mobx-keystone.
• Your TypeScript / Babel / SWC config consistently uses either standard decorators or legacy decorators.
• If your app has a long-lived application store, registering it as a root store is recommended.
• Your UI layer uses a MobX binding such as mobx-react-lite if you want React components to observe model changes.

Transpiler configuration

This library uses JavaScript decorators and class properties.

Standard decorators

Use this mode if you want standard decorators. For Babel, ensure class static blocks are transformed (for example via @babel/preset-env targets, or by adding @babel/plugin-transform-class-static-block).

TypeScript

tsconfig.json

{
  "compilerOptions": {
    "experimentalDecorators": false,
    "useDefineForClassFields": true
  }
}

Babel

babel.config.json

{
  "presets": [
    ["@babel/preset-typescript", { "allowDeclareFields": true }], // if using TypeScript
    ["@babel/preset-env"]
  ],
  "plugins": [
    ["@babel/plugin-proposal-decorators", { "version": "2023-11" }],
    ["@babel/plugin-proposal-class-properties", { "loose": false }]
  ]
}

SWC

.swcrc

{
  "jsc": {
    "parser": {
      "syntax": "typescript", // or "ecmascript" for JavaScript
      "decorators": true
    },
    "transform": {
      "decoratorVersion": "2022-03",
      "useDefineForClassFields": true
    },
    "loose": false
  }
}

Legacy decorators

Use this mode if your project is on legacy decorators (experimentalDecorators: true). This mode remains supported by mobx-keystone decorators. MobX 7's own decorators cannot be used in this mode; choose the standard decorator configuration above if your code uses them.

TypeScript

tsconfig.json

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "useDefineForClassFields": true
  }
}

Babel

babel.config.json

{
  "presets": [
    ["@babel/preset-typescript", { "allowDeclareFields": true }] // if using TypeScript
  ],
  "plugins": [
    ["@babel/plugin-proposal-decorators", { "version": "legacy" }],
    ["@babel/plugin-proposal-class-properties", { "loose": false }]
  ]
}

SWC

.swcrc

{
  "jsc": {
    "parser": {
      "syntax": "typescript", // or "ecmascript" for JavaScript
      "decorators": true
    },
    "transform": {
      "legacyDecorator": true // required for JavaScript, optional for TypeScript
    },
    "loose": false
  }
}

Next step

Once installation and transpiler setup are done, move on to Getting Started for the first working store.