Choosing the state structure

Well-structured state is the difference between a component that's pleasant to change and one that keeps growing bugs. The rules on this page are mostly the same as React's, because they're about data, not rendering. A few are weft's own: how many boxes to use, and how to shape an object so a list reads it one entry at a time.

Principles for structuring state

When a component holds some state, you choose how many boxes to make and what shape their values have. Any structure can be made to work, but some make bugs easy to write. These principles help:

1. Group related state. If two values always change together, keep them in one box.
2. Avoid contradictions. If two boxes can disagree in a way that means nothing, merge them.
3. Avoid redundant state. If you can compute it from props or other state, it's a derived value.
4. Avoid duplication. If the same data is in two places, they will drift apart. Store an id.
5. Avoid deep nesting. Deep trees are awkward to update. Flatten them into an object keyed by id.

The goal is state you can update without making mistakes. As a database designer would put it: normalize, so each fact is stored once.

Group related state

A pointer position has two numbers, and they always change together. You could keep them in two boxes:

const x = state(0)const y = state(0)

or in one:

import { state } from '@weft-js/core'export function Pointer() {  const pos = state({ x: 0, y: 0 })  return (    <div style="block-size: 12rem" onPointerMove={e => (pos.value = { x: e.offsetX, y: e.offsetY })}>      {pos.value.x}, {pos.value.y}    </div>  )}

Both work. The second is closer to how you think about it, and one write can't update x and forget y.

One box, many boxes, or one object box

This choice matters a little more in weft than in React, because each box is its own source of updates. Whatever reads a box re-runs when that box gets a new value, and nothing else does. That gives you three shapes to choose from:

The third is weft's answer to a list of a thousand rows where one changes: each row reads box.get(id), and a write re-runs only the rows whose entry changed. It's the subject of Keyed state and entries.

When you're unsure, start with separate boxes. Merge them when you notice you always write them together.

Avoid contradictions

Here is a feedback form with two booleans:

const isSending = state(false)const isSent = state(false)

Nothing stops both from being true. Every handler has to remember to set one and clear the other, and the day someone forgets, the form shows "Sending…" and "Thanks!" at once.

Since both can't be true, replace them with one box whose type lists what can happen:

const status = state<'typing' | 'sending' | 'sent'>('typing')

You can still have readable names by deriving them: const isSending = derived(() => status.value === 'sending'). They can't contradict each other, because they're computed from one value. Reacting to input with state builds a whole form this way.

Avoid redundant state

If you can compute a value from props or other state while the page runs, don't store it:

const first = state('')const last = state('')const full = state('') // redundant: every write to first or last must also write this

Make it a derived value instead:

import { derived, state } from '@weft-js/core'export function Name() {  const first = state('')  const last = state('')  const full = derived(() => `${first.value} ${last.value}`.trim())  return (    <form>      <input aria-label="First name" value={first.value} onInput={e => (first.value = e.currentTarget.value)} />      <input aria-label="Last name" value={last.value} onInput={e => (last.value = e.currentTarget.value)} />      <p>Your ticket will be issued to <b>{full.value}</b></p>    </form>  )}

full can never be stale, and nothing can write it. In React you'd compute it in the body; in weft the body runs once, so it has to be derived (or written inline in the JSX).

Don't copy props into state

The most common redundant state is a prop copied into a box:

function Message(props: { color: string }) {  const color = state(props.color) // W005  return <p style={`color: ${color.value}`}>Hi</p>}

The box is made once, with whatever color was then. When the parent passes a new colour, the box doesn't follow, and the message keeps the old one. This is the same bug as React's useState(prop), and weft reports it as W005.

What to do depends on what you meant:

• You only want to read it. Read the prop. props.color is always current, and so is const color = props.color, which in weft is a live alias, not a copy.
• The component should be able to change it locally, and take the parent's value again when that changes: state.linked(() => props.color). It follows the prop until you write to it, and resets when the prop changes. let { color } = props does the same with less ceremony; see Passing props.
• You really want the first value only, and to ignore later ones: say so with untrack, and name the prop so a reader knows it's only a starting point.

import { state, untrack } from '@weft-js/core'export function Counter(props: { initialCount: number }) {  // Only the first value matters: later changes to `initialCount` are ignored, on purpose.  const count = state(untrack(() => props.initialCount))  return <button type="button" onClick={() => count.value++}>{count.value}</button>}

Avoid duplication

Here a menu lets you pick a snack. The obvious way to remember the choice is to keep the chosen item:

const snacks = state<Snack[]>([...])const chosen = state(snacks.value[0]) // a second copy of one item

Now the same snack is in two places. Rename it in the list, and chosen still holds the old object with the old name.

Store its id instead, and derive the item:

const chosenId = state(1)const chosen = derived(() => snacks.value.find(s => s.id === chosenId.value))

The snack lives in one place, the list. The choice is a number. Renaming updates the list, and chosen reads the renamed item because it looks it up each time either box changes.

Avoid deep nesting

Imagine a travel plan as a tree: planets, then continents, then countries. Nesting each place inside its parent looks natural, but changing one country means copying every level above it. Removing a place means finding it first.

Flatten it instead. Keep every place in one object keyed by id, and give each one the ids of its children:

// src/lib/plan.tsexport type Place = { id: number; title: string; childIds: number[] }export const initialPlan: Record<number, Place> = {  0: { id: 0, title: '(root)', childIds: [1, 5] },  1: { id: 1, title: 'Europe', childIds: [2, 3, 4] },  2: { id: 2, title: 'Portugal', childIds: [] },  3: { id: 3, title: 'Norway', childIds: [] },  4: { id: 4, title: 'Greece', childIds: [] },  5: { id: 5, title: 'Americas', childIds: [6, 7] },  6: { id: 6, title: 'Peru', childIds: [] },  7: { id: 7, title: 'Canada', childIds: [] },}

Now each place is one entry. The tree component reads its own entry with .get(id), so ticking off Greece re-runs Greece's row and its parent's list, nothing else:

import { derived, state, type State } from '@weft-js/core'import { initialPlan, type Place } from '../lib/plan'function PlaceTree(props: { id: number; plan: State<Record<number, Place>>; onDone: (parent: number, id: number) => void; parent: number }) {  const place = derived(() => props.plan.get(props.id))  return (    <li>      {place.value.title}      <button type="button" onClick={() => props.onDone(props.parent, props.id)}>Done</button>      <ol>        {place.value.childIds.map(child => (          <PlaceTree key={child} id={child} parent={props.id} plan={props.plan} onDone={props.onDone} />        ))}      </ol>    </li>  )}export function TravelPlan() {  const plan = state(initialPlan)  const done = (parent: number, id: number) =>    plan.set(d => {      const p = d[parent]      if (p) d[parent] = { ...p, childIds: p.childIds.filter(c => c !== id) }    })  const root = derived(() => plan.get(0))  return (    <ol>      {root.value.childIds.map(id => <PlaceTree key={id} id={id} parent={0} plan={plan} onDone={done} />)}    </ol>  )}

plan.set copies the outer object one level, so you replace only the parent you changed. Every other place keeps its object, and .get compares entries with Object.is, so their rows don't re-run. The removed place stays in the object, unreachable; delete it too if memory matters.

Recap

• Group values that change together. Separate the ones that don't.
• One box re-runs its readers on every write; .get(key) re-runs only the readers of that key.
• Replace booleans that can contradict each other with one status.
• Derive what can be computed. Don't store it.
• Don't copy a prop into state (W005). Read it, state.linked it, or untrack it on purpose.
• Store ids, not copies of items. Flatten nested data into an object keyed by id.

Try it