Home

How react-state-basis works

Basis is a development-time diagnostic for React. It watches when state updates happen and how those updates line up with each other. It does not read state values.

The point is to surface update patterns that are easy to miss in review: an effect that forces a second paint, two flags that always move together, local state that only copies Context, one click that fans out across several stores.

These are signals, not proofs. Valid React can still look “busy” at runtime. Use the output as a prompt to inspect the code.

Why “Basis”

The name is a metaphor from linear algebra: a basis is a minimal set of independent vectors. Here it just means “state that is actually its own source of truth,” as opposed to values you could compute during render.

The library does not prove independence. It approximates it from timing and from the update graph.

What the engine does

Updates are sampled on animation frames (requestAnimationFrame), so “same tick” means the same screen frame, not an arbitrary clock.

From those ticks it builds a directed graph: what fired, what followed, and which updates look like they share a cause (a click, an effect, a store write).

Heavy work runs when the browser is idle (requestIdleCallback). Recording a tick is meant to stay cheap: fixed-size ring buffers (Uint8Array), no allocations on the hot path.

Limits

• Observes timing and edges, never values.
• The graph is a sliding window (on the order of seconds), not the whole session.
• A slow async gap (a late fetch) can look like two unrelated updates.
• Overhead is small in the cases we measured; it still depends on how much state you instrument.

Installation and usage live in the README.

See the sidebar for patterns, instrumentation, and performance.