legend-state-best-practices

Legend State Best Practices

Use Legend State to put reactive ownership at the smallest useful boundary.

Verify The Surface

Before changing code:

• Check the installed @legendapp/state version, imports, nearby store helpers, persistence setup, and tests.
• Consult the current docs for exact signatures and version-specific migration guidance:
  • https://legendapp.com/open-source/state/v3/intro/introduction/
  • https://legendapp.com/open-source/state/v3/llms.txt
• Search for existing store factories, typed field hooks, reactive components, and naming conventions before adding a new abstraction.
• Identify values that must update rendered UI separately from values read only by commands, callbacks, native bridges, or async work.

This skill is policy, not an API reference. Prefer the installed version's source and types when docs and code differ.

Choose The Mode

• Build: choose observable ownership, render subscriptions, effects, persistence or sync boundaries, and validation before writing code.
• Audit: inspect ownership, subscription breadth, non-reactive reads, React-to-observable mirrors, effects, persistence, and hot paths; report only concrete findings, ranked by impact and confidence.
• Fix: run the same audit and state a ranked plan. Before a non-trivial ownership, persistence, or broad render change, wait for explicit approval such as go; after approval, change the proven misuse in reviewable slices and verify the affected subscriptions and behavior. Stop when the correct model requires a product decision or materially larger scope.

For audits, trace each finding from the mutation source through the tracked read to the component or effect that updates. Do not label an observable read broad or expensive without identifying the subscribers it wakes and the rendered value they consume.

Ownership

• Use observables for shared UI, session, settings, document, selection, and command state with many narrow consumers.
• Use useObservable for component-lifetime state when nested UI needs field-level reactivity or handlers need a stable observable handle.
• Keep one-off local UI state in React when it has no broader ownership, imperative-read, or render-fanout need.
• Store canonical data once. Derive display values with a selector, computed observable, or local render calculation.
• Reuse existing observable references. Do not pass an observable to observable or useObservable, or place it inside another observable merely for ownership, stability, or context. Nest one only when intentionally creating a link whose reads and writes forward to the source.
• Keep one canonical owner; do not mirror between React and observable state. If downstream code needs observable state, replace the originating React state. Bridge only at a true external integration such as native APIs, storage, or measurement.
• Keep routing, file picking, native calls, and other app-specific work outside generic observable stores.