OpenParable
Skip to content
← Back to skills

Mobx

Development
mobx

Mobx is an Agent Skill for development published in the MatrixAges/polywise repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guides state management implementation using MobX + tsyringe. Triggered when handling data models, state logic, or Store architecture.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/MatrixAges/polywise/blob/HEAD/.opencode/skills/mobx/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/mobx, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

MobX State Management Guide

This skill provides mandatory specifications for using MobX and tsyringe (for dependency injection DI) for state management in this project.

1. Architecture Overview

  • MobX: Core state management library (using makeAutoObservable).
  • tsyringe: Dependency injection container for models.
  • Modular Models: State is split into specialized models (e.g., GlobalModel, Settings).
  • Auto-binding: Actions are automatically bound to class instances.

2. Model Implementation Patterns

2.1 Basic Model Structure

import { makeAutoObservable } from 'mobx'
import { injectable } from 'tsyringe'

@injectable()
export default class FeatureModel {
	count = 0
	loading = false

	constructor() {
		// ✅ Use autoBind: true for convenient event handling
		makeAutoObservable(this, {}, { autoBind: true })
	}

	increment() {
		this.count++
	}

	async fetchData() {
		this.loading = true
		try {
			// API call logic
		} finally {
			this.loading = false
		}
	}
}

2.2 Singleton Model (Root Store)

import { singleton } from 'tsyringe'

import { Settings } from '@/models'

@singleton()
export default class GlobalModel {
	// ✅ Dependency injection via constructor
	constructor(public settings: Settings) {}

	init() {
		this.settings.init()
	}

	off() {
		this.settings.off()
	}
}

2.3 Handling Complex Models (DI Composition)

For complex state management (more than 20 reactive variables), models should be split into smaller, focused sub-models and composed using DI.

// ✅ Recommended: split complex models into multiple sub-models and inject
@injectable()
export default class ComplexFeatureModel {
	constructor(
		public data: DataSubModel,
		public ui: UISubModel,
		public sync: SyncSubModel,
		public util: Util
	) {
		// Note: exclude injected dependencies, don't make them observable
		makeAutoObservable(this, { data: false, ui: false, sync: false, util: false }, { autoBind: true })
	}
}

3. Parent-Child Model Communication

3.1 Accessing Singleton GlobalModel

In sub-models, you can declare a non-observable property and bind the singleton GlobalModel instance in the constructor using the getGlobal utility function.

import { injectable } from 'tsyringe'

import { getGlobal } from '@/utils'

import type { GlobalModel } from '@/models'

@injectable()
export default class SubModel {
	// ✅ Declare as non-reactive property
	global = null as unknown as GlobalModel

	constructor() {
		makeAutoObservable(this, { global: false }, { autoBind: true })

		// ✅ Bind instance via utility function
		getGlobal(this.global)
	}
}

3.2 Accessing Parent in Transient Models

In non-singleton models, container.resolve() creates new instances. To ensure sub-models access the correct parent instance, the parent must explicitly pass its reference.

Key Principles:

  1. Avoid Recursive Injection: Never call container.resolve(ParentModel) inside the constructor of a sub-model that the parent model depends on.
  2. Active Assignment: The parent model is responsible for establishing the association reference.

4. Lifecycle Management

All models should implement init() and off() methods for initialization setup and destruction cleanup.

@injectable()
export default class Index {
	constructor(public util: Util) {
		makeAutoObservable(this, { util: false }, { autoBind: true })
	}

	async init() {
		// ✅ Collect cleanup functions (disposers) into util.acts array
		this.util.acts = [
			/* ... */
		]
	}

	off() {
		// ✅ Execute cleanup logic
		this.util.off()
	}
}

5. Constraints and Best Practices

5.1 Observable Rules

  • Reactive State: Define all reactive state as class properties.
  • Exclusions: Use the second parameter of makeAutoObservable to exclude injected services/util classes (set to false), preventing them from becoming reactive.

5.2 Dependency Injection (tsyringe)

  • @injectable(): For feature models that can be instantiated multiple times or locally injected.
  • @singleton(): For global stores that should only have one instance.
  • Constructor Injection: Always prefer constructor injection, and use the public keyword to automatically assign properties.

5.3 Code Style

  • No Comments: Don't write explanatory comments in model files.
  • snake_case: All reactive state variable names must use snake_case.
  • camelCase: All methods must use camelCase.
  • PascalCase: All class names must use PascalCase.
  • AutoBind: Always use { autoBind: true } in makeAutoObservable.

5.4 Common Errors

  • Forgetting the @injectable decorator will cause DI failure.
  • Forgetting to clean up reactions in off() will cause memory leaks.
  • Constructors should not be too heavy; time-consuming initialization logic must be placed in init().