r-state-tree

r-state-tree is a reactive state management library for building complex applications by moving state out of your render tree.

• Stores hold application/view state as a tree and drive your UI.
• Models hold domain state as a separate tree with snapshots, identifiers and references.
• Views become dumb renderers that react to Stores/Models.

Installation

pnpm add r-state-tree

Requirements

This library strongly recommends using decorators.

• Recommended: decorators (@child, @model, @state, @id, @modelRef, @computed). Requires TypeScript 5.0+ with target: "es2022" or higher.
• Fallback: static types configuration (no decorators) if you can't or don't want to enable decorators in your toolchain.

The library includes a decorator metadata polyfill for runtimes that don't yet natively support Symbol.metadata.

TypeScript config (Stage 3 decorators)

TypeScript 5+ supports TC39 Stage 3 decorators.

Only needed if you use decorators.

{
	"compilerOptions": {
		"target": "es2022",
		"module": "esnext",
		"moduleResolution": "bundler",
		"strict": true,
		"experimentalDecorators": false,
		"useDefineForClassFields": true,
		"lib": ["es2022", "dom"],
		"jsx": "react-jsx",
		"noEmit": true
	}
}

• experimentalDecorators must be false for Stage 3 decorators.
• useDefineForClassFields: true is recommended with modern toolchains targeting ES2022.
• The library includes a Symbol.metadata polyfill via @tsmetadata/polyfill.

Vite / esbuild config (SSR)

When using Vite or esbuild for SSR, ensure the target is set to es2022 to support Stage 3 decorators:

// vite.config.ts
export default defineConfig({
	esbuild: {
		target: "es2022",
	},
});

Core concepts

• Stores: application/view state containers. Create with createStore(), attach with mount(), and dispose with Symbol.dispose. Compose with @child and register owned effect/reaction behavior in constructors. Update reactive props via updateStore().
• Models: domain state containers. Create with Model.create(). Persistent via snapshots (toSnapshot, applySnapshot, onSnapshot, diffs via onSnapshotDiff). Structure with @state, @child, identifiers via @id, and references via @modelRef.
• Context: pass data through Store/Model trees without prop drilling using createContext<T>(), [Context.provide], and Context.consume(this). Context is reactive and can be overridden by descendants.
• Reactivity: powered by signals. Use observable(), computed / @computed, effect, reaction, batch, and untracked for precise updates.

Separation of concerns

• Models: domain state + domain logic. Keep invariants, domain mutations (in-place updates), and computed/derived getters here. Models are serializable; mutate arrays/maps/sets in place and expose methods to add/remove/upsert. Derive values via getters.
• Stores: application/view state + orchestration. Coordinate routing, timers, reactions, and I/O. Stores call model methods to perform domain changes. Avoid embedding domain rules in stores.

Why Stores and Models (motivation)

• What is a Model? Persistent domain state plus domain rules. It holds identifiers, references, invariants, and exposes pure domain mutations and derived getters. It is serializable (snapshots), re-hydratable, and safe to reuse across views.
• What is a Store? Application/view state and orchestration. It wires effects (reactions, timers, I/O), reacts to user intent, and delegates domain changes to Models. Stores are not snapshotted.
• Why separate?
  • Snapshots/undo/redo work cleanly when only domain lives in Models.
  • Views stay simple: UI reads derived getters, calls Store methods; Stores call Model methods.
  • Reuse: one Model can back multiple Stores/views without UI coupling.
  • Testability: Models are deterministic and easy to unit test; Stores are thin orchestrators.
  • Performance/identity: Models mutate in place; Stores manage child identity with key.
• Quick rule of thumb:
  • If it should be in a snapshot or referenced by id, put it in a Model (@state, @child, @id, @modelRef).
  • If it is ephemeral UI/app state or side-effect orchestration, put it in a Store.
  • Components should read from one Store; if a component needs multiple sources, compose them into a higher-level Store.

Stores

Stores describe reactive state containers composed into a tree.

import { Store, createStore, mount, child } from "r-state-tree";

class TodoStore extends Store<{ title: string }> {
	get title() {
		return this.props.title;
	}
}

class AppStore extends Store {
	@child get todo() {
		return createStore(TodoStore, { title: "Write docs" });
	}
}

const app = mount(createStore(AppStore));
app.todo.title; // "Write docs"

Fallback (no decorators) using static types:

import { Store, createStore, mount, child } from "r-state-tree";

class TodoStore extends Store<{ title: string }> {
	get title() {
		return this.props.title;
	}
}

class AppStore extends Store {
	get todo() {
		return createStore(TodoStore, { title: "Write docs" });
	}

	static types = {
		todo: child,
	};
}

const app = mount(createStore(AppStore));
app.todo.title;

Store creation, props, and typing

• Always create with createStore() and attach with mount(). Stores cannot be constructed with new directly.
• Prefer no custom constructor. Type stores as Store<Props> and access props via this.props.
• Constructors may register framework-owned reactions and effects after super(props). Store registrations activate when mounting and are disposed with the store; return cleanup from effects to release resources.
• Do not shadow or re-declare props as a class field; props is read-only. Use the generic Store<{ ... }> for typing.

class ItemStore extends Store<{ id: number; title?: string }> {
	get id() {
		return this.props.id;
	}
	get title() {
		return this.props.title ?? "";
	}
}

const root = mount(createStore(ItemStore, { id: 1, title: "Hello" }));

Updating props

Stores receive reactive props objects. Use updateStore to change them.

import { updateStore } from "r-state-tree";

updateStore(app.todo, { title: "Ship release" });

Child stores

Use @child for both single child stores and arrays.

import { child } from "r-state-tree";

class ListStore extends Store {
	items = ["Buy milk", "Walk dog"];

	@child get todos() {
		return this.items.map((title, i) =>
			createStore(TodoStore, { title, key: i })
		);
	}
}

Child store keys and identity

• Pass a stable key (e.g., an id) when creating child stores to preserve identity across reorders.
• @child must decorate a getter; child stores are derived from current state on access, and identity is preserved by keys.

class ItemsStore extends Store {
	items = [
		{ id: 1, title: "A" },
		{ id: 2, title: "B" },
	];

	@child get itemStores() {
		return this.items.map((it) =>
			createStore(TodoStore, { key: it.id, title: it.title })
		);
	}
}

Store lifetime and owned effects

Stores implement Disposable, and their owned effects run only during the mounted lifetime:

class TodoStore extends Store {
	constructor(props) {
		super(props);
		this.effect(() => {
			const connection = connect();
			return () => connection.close();
		});
	}
}

const store = mount(createStore(TodoStore));
store[Symbol.dispose]();

{
	using store = mount(createStore(TodoStore));
} // Symbol.dispose is called automatically

Reactions

Create side effects that run when reactive values change:

class TodoStore extends Store {
	constructor(props) {
		super(props);
		this.reaction(
			() => this.props.title,
			(title, previousTitle) => console.log(previousTitle, "->", title)
		);
	}
}

Store.effect() and Store.reaction() register mount-scoped behavior. Mounting first links the complete store tree and commits its private mounted state bottom-up in one transaction. Registrations then activate bottom-up, so even a grandchild's initial effect sees a complete tree. A reaction establishes its initial value at activation and still skips its initial callback. Calling the disposer returned during construction cancels the pending registration; after mount, it disposes the live subscription. All registrations are disposed automatically with the store.

Registration activation is non-reentrant. If an active effect or reaction lazily materializes another child store, the new child's registrations are queued until the current callback and child getter stack have returned. This prevents initialization behavior from running inside the getter that created the store.

Context

Share data across the store tree without prop drilling:

import { createContext } from "r-state-tree";

const ThemeContext = createContext<"light" | "dark">("light");

class AppStore extends Store {
	theme = "dark";

	[ThemeContext.provide]() {
		return this.theme;
	}

	@child get todo() {
		return createStore(TodoStore);
	}
}

class TodoStore extends Store {
	get theme() {
		return ThemeContext.consume(this);
	}
}

const app = mount(createStore(AppStore));
app.todo.theme; // "dark"

Context is reactive and updates automatically when the provided value changes.

Actions and batching

batch groups updates to avoid redundant reactions.

import { batch } from "r-state-tree";

batch(() => {
	app.todo.props.title = "Refactor";
});

Models injection (@model)

Inject domain models into stores via the models creation prop and consume them with @model on the store. @model fields are read-only references.

import { Model, Store, model, createStore, mount } from "r-state-tree";

class User extends Model {
	@id id = 0;
	@state name = "";
}

class ProfileStore extends Store {
	@model user!: User;
}

const user = User.create({ id: 1, name: "Ada" });
const profile = mount(createStore(ProfileStore, { models: { user } }));
profile.user.name; // "Ada"

Fallback (no decorators) using static types:

import {
	Model,
	Store,
	createStore,
	mount,
	model,
	id,
	state,
} from "r-state-tree";

class User extends Model {
	id = 0;
	name = "";
	static types = { id, name: state };
}

class ProfileStore extends Store {
	user!: User;
	static types = { user: model };
}

const user = User.create({ id: 1, name: "Ada" });
const profile = mount(createStore(ProfileStore, { models: { user } }));
profile.user.name;

Type stores as Store<Props> and explicitly type @model fields for clarity. The models prop may also provide arrays of models.

Modeling guide

Store ↔ Component mapping (quick guide)

• Pair each container/screen component with one owning Store; components should read from a single Store.

• The Store tree overlays the component tree: parents map to parent Stores; children map to @child Stores; lists map to arrays of child Stores with stable keys.

• A Store can power multiple components (header/body/sidebar), but a component shouldn’t pull from multiple Stores. If it needs to, introduce a parent/adapter Store that composes and exposes exactly what the component needs.

• Use Context for cross‑cutting concerns (theme, auth) instead of coupling components to multiple Stores.

• Keep domain logic in Models; Stores orchestrate and delegate to Model methods, and expose derived getters for the UI.

• Root store: mount a single root Store that composes the application via @child properties.

• View stores: create one Store per view/route/tab. Views render from stores; stores drive view transitions.

• Keyed children: pass { key } when creating child stores to preserve identity across reorders.

• Models in stores: pass domain Models via { models } and consume with @model on the Store.

import { Store, Model, child, createStore, mount } from "r-state-tree";

class TabViewStore extends Store<{ title: string }> {}

class RootStore extends Store {
	@child get tabs() {
		return ["Home", "Profile"].map((title, i) =>
			createStore(TabViewStore, { title, key: i })
		);
	}
}

const root = mount(createStore(RootStore));

Patterns: deriving Stores from Models

Derive child stores directly from model arrays with stable keys; delegate mutations to model methods.

class ItemModel extends Model {
	@id id = 0;
	@state title = "";
}

class ListModel extends Model {
	@child(ItemModel) items: ItemModel[] = [];

	add(id: number, title: string) {
		this.items.push(ItemModel.create({ id, title }));
	}
	remove(id: number) {
		const i = this.items.findIndex((m) => m.id === id);
		if (i >= 0) this.items.splice(i, 1);
	}
	get titles() {
		return this.items.map((m) => m.title);
	}
}

class ItemStore extends Store {
	@model item!: ItemModel;
	get title() {
		return this.item.title;
	}
}

class ListStore extends Store {
	@model list!: ListModel;

	@child get items() {
		return this.list.items.map((item) =>
			createStore(ItemStore, { key: item.id, models: { item } })
		);
	}

	addItem(id: number, title: string) {
		this.list.add(id, title); // delegate to domain
	}
}

Mutability rules

• Models: model fields are shallow-reactive, but values are not auto-wrapped. For raw @state arrays/objects, prefer reassignment (immutability) so snapshots stay up to date. If you want in-place mutation (push, splice, set, etc.) to trigger updates and snapshot invalidation, store an observable() container (or signal()) in @state.
• Stores: store fields are shallow-reactive. Use observable() containers (or signal()) when you want in-place mutations of nested values/collections to trigger updates.

Observable base class

For class instances that need to be reactive, extending the Observable base class is the supported pattern. This ensures compatibility with ES #private fields and built-in brand checks because the observable is created in the base constructor, allowing derived field initializers (including #private) to run on the observable.

import { Observable, effect } from "r-state-tree";

class Counter extends Observable {
	count = 0; // Public fields are automatically reactive
	#internal = 0; // Private fields also work perfectly

	get total() {
		return this.count + this.#internal;
	}

	increment() {
		this.count++;
		this.#internal++;
	}
}

const counter = new Counter();

// Use an effect to track and react to property changes
effect(() => {
	console.log(`Visible: ${counter.count}, Total: ${counter.total}`);
});

counter.increment();

[!IMPORTANT] > Why extends Observable? ES #private fields are brand-checked. If you wrap a class instance with observable() after it has been created (post-hoc wrapping), or if you return an observable from a standard constructor, the private state is installed on the original this, but methods run with the observable as this, causing TypeError: Cannot read private member.

extends Observable solves this by returning the observable from super(), so derived classes initialize their private fields directly on the observable receiver.

Limitations of observable(instance)

The observable() function is selective about what it makes observable. It wraps supported containers only:

• Plain objects
• Arrays
• Maps and Sets
• Dates

Functions are not observable containers. Calling observable(fn) returns the function unchanged with a dev-mode warning. However, functions stored as properties on observable objects are still automatically batched as actions when called—this existing behavior is preserved, just not via observable(fn) directly.

If you pass an arbitrary class instance, built-in (like URL, RegExp, Promise, or DOM objects), or frozen object to observable(), it will return the object unchanged and emit a warning in development mode.

This design prevents “silent failure” where an observable object appears to work but throws TypeError when accessing private members or internal slots. For your own classes, use extends Observable. For third-party or built-in objects, use composition:

// ❌ Post-hoc wrapping - returns raw URL, not an observable
const url = observable(new URL("..."));

// ✅ Composition - wrap a container instead
const state = observable({ url: new URL("...") });

Wrap values with observable() for reactivity. Collections (arrays, maps, sets) track mutations:

import { observable, effect, isObservable } from "r-state-tree";

class DataStore {
	// Wrap state with observable() for reactivity
	state = observable({ count: 0 });

	// Wrap array with observable() to track push/pop/splice etc.
	items = observable([]);
}

const store = new DataStore();

effect(() => {
	console.log("Items length:", store.items.length);
});

store.items.push({ value: 1 }); // Triggers effect
console.log(isObservable(store.items[0])); // false - shallow by default

Shallow behavior

All observables are shallow by default. Only the container's own properties are tracked—nested values are NOT wrapped:

• Collections (Arrays, Maps, Sets) wrapped with observable() track mutations
• Plain objects assigned to properties are NOT wrapped (helps preserve structuredClone compatibility for stored values)
• Nested object properties do NOT trigger effects unless explicitly wrapped

Mental model: reactive property, explicit reactive value

• Reading/writing a property on an observable container (including Stores/Models) is reactive.
• The value you store is not auto-wrapped. If you store a plain object/array, mutating inside it won’t trigger reactions; wrap nested values with observable() (or use signal()), or use toObservableTree for a one-time deep wrap of an existing JSON-like structure.

What gets tracked in shallow mode:

| Expression | Tracked? | Why | | ----------------------- | ------------- | ------------------------------------------------ | | data.nested | ✅ Yes | Property access on the observable container | | data.nested.value | ❌ No | data.nested is a plain object, not observable | | data.nested = { ... } | ✅ Triggers | Reassigns a property on the observable container | | data.nested.value = 2 | ❌ No trigger | Mutates a plain object; container unchanged |

const data = observable({ nested: { value: 1 } });

effect(() => {
	data.nested.value; // Reads `data.nested` (tracked), then reads `.value` (not tracked)
});

data.nested.value = 2; // Does NOT trigger — mutating a plain object
data.nested = { value: 3 }; // DOES trigger — reassigning a property on the observable

To make nested reactive, wrap it explicitly:

const data = observable({ nested: observable({ value: 1 }) });
data.nested.value = 2; // Now triggers — `nested` is also observable

Plain objects (implicit reactivity)

Plain objects wrapped with observable() use implicit reactivity:

import { observable, effect } from "r-state-tree";

const state = observable({ count: 0 });

effect(() => {
	console.log(state.count); // All properties are reactive
});

state.count++; // Triggers the effect

Observables (low‑level)

Create reactive structures outside Stores/Models. Supported: Objects, Arrays, Map, Set, WeakMap, WeakSet.

• Track reads with effect/reaction. Observables are shallow: reads are tracked on the observable container, but nested object mutations do not trigger unless you explicitly wrap nested values with observable() (or use signals).
• Access backing values via source(value); check if something is reactive with isObservable(value).
• Rule of thumb: source(...) returns the backing data, not a sanitizer—it's only observable-free if you didn't manually seed observables into the backing source.
• Arrays: reading specific indices (arr[i]) or length tracks those; common mutators (push/pop/shift/unshift/splice/reverse/sort/fill) are reactive; non-index and symbol keys are not reactive.

source() and structuredClone

source(x) returns the backing value behind an observable. It is not a “observable stripper”.

One-way rule (important):

• If you mutate through the observable wrapper (e.g. obj.prop = observable(child)), r-state-tree stores the raw backing value in source(obj).prop (unwrap-on-write).
• If you manually mutate backing sources yourself (e.g. source(obj).prop = observable(child)), r-state-tree does not sanitize or rewrite your data. In that case, source(...) may contain observables.

If you need to pass values to APIs that require cloneable data (e.g. structuredClone, postMessage), avoid seeding observables into backing sources. Prefer reading via source(...) and keep your stored values plain/cloneable.

import { observable, effect, computed, reaction } from "r-state-tree";

// Object
const state = observable({ count: 0, nested: observable({ value: 1 }) });

effect(() => {
	// tracks reads
	state.count;
	state.nested.value;
});

state.count++;
state.nested.value++;

// Computed
const doubled = computed(() => state.count * 2);
effect(() => {
	doubled.value;
});

// Array
const arr = observable([0, 1]);
effect(() => arr[0]);
arr[0]++; // triggers; arr.push(2) does not, index 0 didn't change

// Map
const map = observable(new Map([["k", 1]]));
effect(() => map.get("k"));
map.set("k", 2); // triggers

// Set
const set = observable(new Set([1]));
effect(() => set.has(2));
set.add(2); // triggers

// Reaction (runs only on changes, skips initial)
let last: number | undefined;
reaction(
	() => state.count,
	(v) => {
		last = v;
	}
);
state.count++;

Derived collections and identity preservation

Native methods that return copies of a collection—such as Array.prototype.slice, filter, and concat, or Set.prototype.union and intersection—behave according to the Explicit Architecture:

• Raw Return: The returned container is a plain JavaScript object (raw, non-observable).
• Identity Preservation: Each element in the returned container maintains the same identity it had in the observable source. If an element was an observable (because it was explicitly owned), it remains an observable in the raw result.

This ensures that "derived" state is not automatically made reactive, while still allowing observers to maintain reference stability with existing objects in your state tree.

const item = observable({ id: 1 });
const arr = observable([item, { id: 2 }]);

// slice() returns a plain array
const sliced = arr.slice();
isObservable(sliced); // false

// Identity is preserved
sliced[0] === item; // true (same observable identity)

// If you want the result to be reactive, wrap it explicitly
const reactiveSlice = observable(arr.slice());

Recursively wrapping nested values (toObservableTree)

By default, observable() is shallow: only the top-level container is wrapped, and nested objects/arrays are not. This is intentional for performance and structuredClone compatibility.

toObservableTree performs a one-time initial pass that wraps all existing nested plain objects and arrays with observable(). After the initial wrap, the returned observables behave exactly like normal shallow observables — new assignments are not auto-wrapped.

import { toObservableTree, effect, source, isObservable } from "r-state-tree";

// Initial pass wraps all existing nested plain objects/arrays
const tree = toObservableTree({
	user: { name: "Alice", tags: ["admin", "active"] },
	settings: { theme: "dark" },
});

effect(() => {
	// Existing nested values are observable and tracked
	console.log(tree.user.name);
	console.log(tree.user.tags[0]);
});

// Mutations to initially-wrapped values trigger effects
tree.user.name = "Bob"; // triggers
tree.user.tags[0] = "superadmin"; // triggers

// NEW assignments are NOT auto-wrapped (normal shallow behavior)
tree.newProp = { foo: 1 };
isObservable(tree.newProp); // false — not wrapped

// Source is observable-free and clonable *as long as you don't manually seed observables*
// into backing data structures. r-state-tree unwraps observables on writes performed
// through observable containers, but it does not sanitize user-mutated backing sources.
const snapshot = structuredClone(source(tree));

Key behavior:

• One-time pass: Only values present at call time are wrapped. New assignments afterward behave like normal observable() (shallow).
• Not MobX-style "deep": This does NOT change the observable's behavior. It's just a convenience for wrapping an existing structure upfront.

When to use:

• Hydrating API/JSON responses where you want all nested values observable from the start
• Cases where manually wrapping each nested object would be tedious

Constraints:

• Input must be JSON-like and acyclic (no circular references)
• Only plain objects and arrays are wrapped; other types (Map, Set, Date, class instances, RegExp, Error, etc.) are left as-is and not traversed

Models and snapshots

Models capture persistent state with snapshot utilities.

Important: @state is shallow-reactive at the property level (assignments track), but values are not auto-wrapped. If you need nested mutations to be reactive (and to invalidate snapshot caches on in-place mutation), store observable() containers or signal() values inside @state.

import {
	Model,
	state,
	id,
	applySnapshot,
	onSnapshot,
	toSnapshot,
} from "r-state-tree";

class TodoModel extends Model {
	@id id = 0;
	@state title = "";
	@state completed = false;
}

const todo = TodoModel.create({ id: 1, title: "Learn signals" });

const stop = onSnapshot(todo, (snapshot) => {
	console.log(snapshot); // { id: 1, title: "Learn signals", completed: false }
});

todo.title = "Learn r-state-tree";
stop();

Snapshot data contract

Snapshots are JSON-only: they contain primitives, arrays, plain objects, and Dates (serialized as ISO strings).

• Primitives: string, number, boolean, null, undefined pass through.
• Arrays: recursively cloned.
• Plain objects: recursively cloned (prototype must be Object.prototype or null).
• Dates: serialize to ISO strings (e.g., "2024-01-15T10:30:00.000Z").
• Signals: serialize to their current .value (recursively cloned).
• Map/Set/WeakMap/WeakSet and other non-plain objects are rejected with a descriptive error. Convert them to plain structures before storing in @state.

class Event extends Model {
	@state title = "Meeting";
	@state createdAt = new Date(); // Date → ISO string in snapshot
}

const event = Event.create();
toSnapshot(event);
// { title: "Meeting", createdAt: "2024-01-15T10:30:00.000Z" }

If you store a Map or class instance in @state, snapshotting will throw:

class M extends Model {
	@state cache = new Map(); // ❌ Will throw on toSnapshot()
}
// Error: r-state-tree: snapshots do not support Map at path "cache". ...

Convert to a plain structure instead:

class M extends Model {
	@state cache: Record<string, unknown> = {}; // ✅ Plain object
}

Snapshot invalidation rules

Snapshots are memoized computeds. Once a snapshot is observed (via onSnapshot, onSnapshotDiff, or toSnapshot), subsequent calls return the cached value unless a reactive dependency changes.

Because snapshots are memoized computeds and observables are shallow, the snapshot cache is invalidated only by:

1. Reassigning the @state field itself.
2. Mutating observable containers (observable()) or signals (signal()) stored in the field.

Rule: Treat raw @state values (plain objects/arrays) as immutable. If you mutate them in place without reassignment, the snapshot cache goes stale—onSnapshot won't fire and toSnapshot returns the old cached value.

class M extends Model {
	@state tags: string[] = [];

	// ❌ In-place mutation — snapshot cache goes stale
	addTagBroken(tag: string) {
		this.tags.push(tag);
	}

	// ✅ Reassign — invalidates cache, onSnapshot fires
	addTagReassign(tag: string) {
		this.tags = [...this.tags, tag];
	}
}

If you need in-place mutations and snapshot updates, wrap the value in observable() or use signal():

class M extends Model {
	// ✅ observable() container — in-place mutations invalidate cache
	@state items: { id: number }[] = observable([]);

	addItem(id: number) {
		this.items.push({ id }); // onSnapshot fires
	}
}

class Counter extends Model {
	// ✅ signal() — .value updates invalidate cache
	@state count = signal(0);

	increment() {
		this.count.value++; // onSnapshot fires
	}
}

Snapshots and persistence

• Snapshots capture Models (not Stores).
• Hydrate/persist with applySnapshot and onSnapshot:

const STORAGE_KEY = "list";

// hydrate
const list = ListModel.create();
const saved = localStorage.getItem(STORAGE_KEY);
if (saved) applySnapshot(list, JSON.parse(saved));

// persist
const off = onSnapshot(list, (snap) => {
	localStorage.setItem(STORAGE_KEY, JSON.stringify(snap));
});

Mutate Models through domain methods and let snapshots record changes automatically.

Model creation and named factories

Model.create() accepts a canonical snapshot. For defaults, identifier generation, normalization, migrations, or external API formats, use a named static factory that prepares the input before calling create():

class TodoModel extends Model {
	@id id = "";
	@state title = "";

	static new(title = "Untitled") {
		return this.create({
			id: crypto.randomUUID(),
			title: title.trim(),
		});
	}

	static fromApi(input: ApiTodo) {
		return this.create({
			id: input.todo_id,
			title: input.name.trim(),
		});
	}
}

const todo = TodoModel.new("  Write documentation  ");
todo.title; // "Write documentation"

This keeps snapshot hydration predictable: create(snapshot) and applySnapshot(model, snapshot) both consume the same canonical shape. Named factories make non-canonical inputs and generated values explicit and independently typed. Nested snapshots must already be canonical.

Model attachment and disposal

Models are inert state trees: creating or attaching one does not start reactions or effects. The public parent relationship remains reactive, so an external owner may observe it explicitly when needed:

const stop = reaction(
	() => todo.parent,
	(parent, previousParent) => {
		if (previousParent) console.log("detached", previousParent);
		if (parent) console.log("attached", parent);
	}
);

The external caller owns stop. Detachment is reversible. model[Symbol.dispose]() is terminal and recursively disposes owned child models, but never model refs.

Model configuration

Recommended: configure model properties with decorators.

Fallback: if you can't or don't want to use decorators, use static types.

import { Model, state, id, child, modelRef } from "r-state-tree";

class User extends Model {
	@id id = 0;
	@state name = "";
}

class TodoModel extends Model {
	@id id = 0;
	@state title = "";
	@modelRef(User) assignee?: User; // Reference to another model by ID
	@child metadata = MetadataModel.create(); // Nested child model
	@child tags: TagModel[] = []; // Array of child models
}

Fallback (no decorators) using static types:

import { Model, id, state, child, modelRef } from "r-state-tree";

class User extends Model {
	id = 0;
	name = "";
	static types = { id, name: state };
}

class TodoModel extends Model {
	id = 0;
	title = "";
	assignee?: User;
	metadata = MetadataModel.create();
	tags: TagModel[] = [];

	static types = {
		id,
		title: state,
		assignee: modelRef(User),
		metadata: child(MetadataModel),
		tags: child(TagModel),
	};
}

The child and modelRef helpers support both single values and arrays. You can also specify the child type using @child(ChildType) (decorators) or child(ChildType) (static types):

class TodoModel extends Model {
	@child(TagModel) tags: TagModel[] = []; // Type-safe array of child models
	@child(TagModel) primaryTag: TagModel | null = null; // Can switch between single and array at runtime
}

Model references

Reference models by ID using @modelRef(ModelType) (or modelRef(ModelType) in static types). The model constructor is required because identifiers are namespaced by model type:

class ProjectModel extends Model {
	@id id = 0;
	@child users: User[] = [];
	@modelRef(User) owner?: User; // Single reference
	@modelRef(User) assignees: User[] = []; // Array of references

	assignOwner(userId: number) {
		// Find user by ID and set as owner
		const user = this.users.find((u) => u.id === userId);
		this.owner = user;
	}
}

const project = ProjectModel.create({
	id: 1,
	users: [
		{ id: 1, name: "Alice" },
		{ id: 2, name: "Bob" },
	],
	owner: { id: 1 }, // Reference by ID in snapshot
});

project.owner?.name; // "Alice"

Both @child and @modelRef support runtime type switching between single values and arrays:

class ItemModel extends Model {
	@id id = 0;
	@state value = 0;
}

class ContainerModel extends Model {
	@child(ItemModel) items: ItemModel | ItemModel[]; // Can be single or array

	setSingle() {
		this.items = ItemModel.create({ id: 1, value: 10 });
	}

	setArray() {
		this.items = [
			ItemModel.create({ id: 2, value: 20 }),
			ItemModel.create({ id: 3, value: 30 }),
		];
	}
}

API surface

• Stores
  • Store, createStore, mount, updateStore
• Models
  • Model, Model.create()
  • configuration: decorators (@state, @id, @child, @modelRef) or static types with state, id, child, modelRef
• Store configuration
  • decorators (@child, @model) or static types with child, model
• Snapshots
  • onSnapshot, toSnapshot, applySnapshot, onSnapshotDiff
  • Types: Snapshot, SnapshotDiff, IdType, Configuration
• Context
  • createContext, type Context
• Reactivity and observables
  • observable, computed, effect, reaction, batch, untracked
  • Utilities: isObservable, source, reportObserved, reportChanged
• Advanced
  • toObservableTree — recursively wrap nested values in a JSON-like structure
• Signals interop
  • signal, getSignal, types Signal, ReadonlySignal

UI integration and signals interop

r-state-tree is built on @preact/signals-core. You can interoperate with signals directly:

• Per-property signals via getSignal(obj, key).
• Re-exported utilities: signal, computed, effect, batch, untracked, and types Signal, ReadonlySignal.

import { observable, effect, getSignal } from "r-state-tree";

const state = observable({ count: 0 });

const countSignal = getSignal(state, "count");

effect(() => {
	console.log("count:", countSignal.value);
});

// Update via signal or through the object
countSignal.value = 1;
state.count = 2;

React / Preact usage

• Preact: use @preact/signals. Reading signal.value inside JSX is reactive; components re-render automatically.
• React: use @preact/signals-react. Call useSignals() in a component and read signal.value in render; updates re-render the component.

// Preact
function TodoView({ store }: { store: TodoStore }) {
	const titleSignal = getSignal(store, "title");
	return <h1>{titleSignal.value}</h1>;
}

// React
import { useSignals } from "@preact/signals-react/runtime";
function TodoView({ store }: { store: TodoStore }) {
	useSignals();
	const titleSignal = getSignal(store, "title");
	return <h1>{titleSignal.value}</h1>;
}

Use the observers/renderers provided by the signals bindings for your UI library; r-state-tree will participate automatically because Stores/Models are signal-backed.

Identifier and reference rules

• @id values are unique per exact runtime Model class within a tree. Different Model classes may use the same id; subclasses have their own identifier namespace. IDs cannot be cleared to undefined after assignment.
• Identifiers are mutable and can be reassigned (including in snapshots) as long as the new id is unused by that exact Model class. A failed reassignment preserves the old id and its references.
• Use @modelRef(ModelType) or modelRef(ModelType) when ids can overlap across Model classes; references resolve only within the declared Model class.
• @modelRef(ModelType) requires an explicit model constructor. The referenced model must have an id and be attached to the tree; the ref becomes undefined when the model detaches.
• When a model is re-attached to the same tree, compatible refs restore automatically; attaching to a different root does not restore prior refs.
• @modelRef and @child can switch between single and array at runtime; reactions observe the property itself rather than internal array mutations.

Use findModelById for an optional, typed lookup within a model tree:

const user = findModelById(root, User, 1); // User | undefined

The lookup is reactive inside an effect or computed value. It returns undefined when the matching model changes its id, detaches, or is disposed.

Snapshot diffs

Use onSnapshotDiff to receive undo/redo payloads:

const history: SnapshotDiff[] = [];

const off = onSnapshotDiff(todo, (diff) => {
	history.push(diff);
});

todo.title = "New title";
todo.completed = true;

// Undo
applySnapshot(todo, history[history.length - 1].undo);

// Redo
applySnapshot(todo, history[history.length - 1].redo);

Context with Models

Models also support context:

const AuthContext = createContext<User | null>(null);

class AppModel extends Model {
	@child currentUser = User.create({ id: 1, name: "Alice" });

	[AuthContext.provide]() {
		return this.currentUser;
	}

	@child project = ProjectModel.create();
}

class ProjectModel extends Model {
	get currentUser() {
		return AuthContext.consume(this);
	}
}

Do/Don’t guide

Do:

• Keep domain operations in Models
• Delegate from Stores to Models for domain changes
• Use @child for child stores (getter-based)
• Use stable key values for child stores
• Mutate @child model collections and observable() containers in place (push/splice/set/add/etc.)
• Treat raw @state arrays/objects as immutable: use reassignment so snapshots stay up to date (or store an observable() container / signal() inside @state)

Don’t:

• Shadow or re-declare props on stores
• Instantiate Stores with new
• Perform effectful work in constructors
• Manually “sync” store state into Models (call model methods instead)

Compact code samples

Store without a constructor:

class ViewStore extends Store<{ q?: string }> {
	get q() {
		return this.props.q ?? "";
	}
}

Store with an injected @model:

class ItemStore extends Store {
	@model item!: ItemModel;
}
const item = ItemModel.create({ id: 1, title: "X" });
const s = mount(createStore(ItemStore, { models: { item } }));

@child mapping from a model array (stable keys):

class ListStore extends Store {
	@model list!: ListModel;
	@child get items() {
		return this.list.items.map((item) =>
			createStore(ItemStore, { key: item.id, models: { item } })
		);
	}
}

Model with in-place mutations and a derived getter:

class ListModel extends Model {
	@child(ItemModel) items: ItemModel[] = [];
	add(m: ItemModel) {
		this.items.push(m);
	}
	get count() {
		return this.items.length;
	}
}

Store lifecycle registration:

class S extends Store {
	constructor(props) {
		super(props);
		this.effect(() => {
			const resource = acquireResource();
			return () => resource.dispose();
		});
	}
}

Snapshot hydrate/persist:

const m = ListModel.create();
const saved = localStorage.getItem("m");
if (saved) applySnapshot(m, JSON.parse(saved));
const off = onSnapshot(m, (snap) =>
	localStorage.setItem("m", JSON.stringify(snap))
);

Common pitfalls

• Forgetting stable keys for @child arrays causes identity churn.
• Assuming deep reactivity: nested plain objects/arrays are not reactive unless you explicitly wrap them (or use toObservableTree for initial hydration).
• Mutating raw @state arrays/objects in place (push, obj.x = 1) and expecting snapshots to update. Snapshots are memoized; use reassignment or store observable() containers / signal() values in @state.
• Passing observables to third‑party APIs that expect cloneable/serializable values (e.g. structuredClone). Use source(value) to get the backing value. It will be observable-free for values written via r-state-tree’s observable APIs (unwrap-on-write), but source(...) is not guaranteed observable-free if you manually seed observables into backing sources.
• Creating child stores in constructors: @child must be on getters so identity and lifecycle can be managed by the framework.
• Passing models into child stores during mount can create a recursive mount loop. Break the ownership cycle rather than wiring models back through a child during mount.

Circular store/model creation

When child stores are created during mount with models that point back into the parent, it is easy to trigger an endless mount loop. The runtime guards this with a descriptive circular-creation error. Break the cycle so models are produced independently of the child mount.

LLM implementation checklist

• Do not thread context data via props. Provide contexts at the parent and consume them in children. Passing getX callbacks for resource/page/video/skill is a red flag—consume contexts instead.
• Avoid aggregating contexts into a single ctx object; consume where needed or expose small, focused getters.
• Only create stores in three places: root, @child getters, or immediately before mounting. Avoid standalone factory helpers; inline createStore in @child getters.
• Do not wrap createStore calls with as Record<string, unknown>; fix typing instead.
• Domain/persistent state belongs in Models; UI/app orchestration in Stores. Keep UI terms out of domain models—name domain concepts (e.g., ChatThreadsModel).
• If state is persistent/rehydratable, model it and derive stores from the model; keep purely view/ephemeral state in stores.
• Use r-state-tree snapshots (toSnapshot/applySnapshot) instead of hand-rolled serialize/rehydrate unless a different shape is required.
• Keep onPersist only when syncing store state into a backing model; otherwise prefer snapshot listeners.
• Pure, stateless helpers belong in utility modules, not as store methods. If a method does not touch this, extract it; keep coupled helpers in the store.
• Provide stable, rarely changing resource/view/video/page data via context (resourceId, resourceType, totalPages, current page/display mode, page offsets, document title, skill/detail, video info). Children should consume context directly.
• Use @child getters to create child stores with stable keys; avoid constructor creation. Pass only what the child needs; avoid prop drilling context.
• Eliminate blanket casts; fix types and let inference work. Avoid any.
• For createStore props, extend Record<string, unknown> only if needed; otherwise rely on proper prop types and context.
• Avoid barrel files if they cause import confusion; prefer direct imports.
• Keep file boundaries clean: one model per file; avoid piling multiple models together.
• Do not shadow props; constructors are the registration phase for owned reactions and effects.
• Use @model/model for injected models; @child/child for child stores; stable keys for arrays.

Typing recipes

• Type stores as Store<Props>; read this.props inside methods/getters.
• Explicitly type @model fields on stores, and pass matching values via the models creation prop.
• When a store has no props, use class X extends Store {}.

Cheat sheet

• Configuration (no decorators): static types = { ... } with state, id, child, modelRef, model, computed
• Decorators (Models): @state, @id, @child, @modelRef
• Decorators (Stores): @child, @model
• Core: createStore, mount, Symbol.dispose, updateStore
• Snapshots: onSnapshot, toSnapshot, applySnapshot, onSnapshotDiff
• Lifecycle: Store-owned reaction/effect, reactive Model.parent, and Symbol.dispose
• Best practices: domain in Models; delegate from Stores; stable keys for @child; return cleanup from store effects; don’t shadow props.

Testing

The repository ships with Vitest suites covering stores, models, containers, and observable primitives.

pnpm test

Build & publishing

pnpm build

The build emits CommonJS, ESM bundles, and type declarations under dist/.

License

MIT