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.

yarn

yarn add mobx mobx-keystone

pnpm

pnpm add mobx mobx-keystone

npm

npm install --save mobx mobx-keystone

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

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

yarn

yarn add mobx-react-lite

pnpm

pnpm add mobx-react-lite

npm

npm install --save mobx-react-lite

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:

• Version 5.0+ is recommended (standard decorators).
• Legacy decorators are also supported (experimentalDecorators: true).

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 are on TypeScript 5+ and 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).

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.