How an update reaches the DOM

In React, a state change asks React to render your component again: it calls your function, compares the new JSX with the old, and commits the difference to the DOM. Most of React's chapter on interactivity is about the consequences: render and commit, state as a snapshot, queueing updates. weft takes a different path, and this page follows it from one write to the DOM. It's short, and once you've seen it most of weft's behaviour stops being surprising.

Three steps from a write to the page

When a handler writes count.value = 1:

1. The box changes, now. It stores the new value at once. Then it marks everything that read it: derived values that used it are marked stale, and the bits of DOM that showed it are put in a queue.
2. The queue runs once, soon. On the next microtask, after your handler and anything else running with it has finished, weft runs the queued bindings in the order they were created. Each one reads its expression again and writes its own DOM node: one text, one attribute, one class.
3. Derived values recompute when read. A stale derived doesn't run on its own. It recomputes the next time something reads it, which is usually one of those bindings.

Nothing in that list calls your component. It ran once, when it was created, to build its DOM and set up the bindings. After that, the bindings are what update.

You can watch this happen. Each line below is a derived that counts how many times it ran:

Adding an apple runs the apple line and nothing else. The pear line didn't read apples, so the write never reached it. And setting apples to 5 a second time runs nothing at all: the write compared 5 with 5 using Object.is, found nothing changed, and stopped there.

What the compiler makes of your JSX

The pieces that update are made by the compiler. Take this component:

import { state } from '@weft-js/core'export function Counter() {  const count = state(0)  return (    <p class={count.value > 9 ? 'big' : 'small'}>      Clicked {count.value} times      <button type="button" onClick={() => count.value++}>+1</button>    </p>  )}

weft's compiler turns it into something like this. The real output uses generated names, and its helpers are internal, but the shape is the same:

// The static markup, parsed once per module and cloned for each Counter.const template = tpl('<p>Clicked <!> times<button type="button">+1</button></p>')export function Counter() {  const count = state(0)  const p = template()  const marker = p.firstChild.nextSibling  const button = p.lastChild  // One binding per element's dynamic attributes: read, then write what changed.  bind(() => (count.value > 9 ? 'big' : 'small'), (value, prev) => cls(p, value, prev))  // One binding per dynamic child: this one owns the text before the marker.  child(p, () => count.value, marker)  // The handler, stored on the element: one document listener serves every click.  button.$$click = () => count.value++  return p}delegate(['click'])

Every {…} in your JSX became a small function, and each one is a reader of the boxes it touches. When count changes, the child binding reads count.value again and replaces one text node's content. The class binding reads its expression again, and writes the attribute only if the result changed. The <p>, the button and the words around the number were made once, from the template, and are never touched again.

That is why weft has no virtual DOM and no diffing step for ordinary updates. Each binding already knows which node it owns. (Lists are the one place that compares: a keyed list matches rows by key, so it can move, add and remove rows rather than rebuild them. See Rendering lists.)

Reads after writes see the new value

Because the box changes at once, the next line of your handler already sees the new value. There is no snapshot:

score.value = score.value + 1   // 1score.value = score.value + 1   // 2score.value = score.value + 1   // 3

Each line reads what the line before it wrote, so pressing +3 adds three.

In React, the same three calls to setScore(score + 1) add one: score is that render's snapshot, fixed at the value it had when the render ran, so all three calls ask for the same number. React's answer is an updater function, setScore(s => s + 1), which is queued and applied in order. weft needs neither: there is no snapshot to work around, and no queue of updates to reason about. A box is a place, and score.value is what's in it now.

The same holds for derived. A derived value read after a write in the same handler recomputes on that read and gives you the up-to-date answer, even though the DOM hasn't been updated yet:

import { derived, state } from '@weft-js/core'import { Button } from '@weft-js/warp'export function Basket() {  const qty = state(1)  const total = derived(() => qty.value * 12)  const addTwo = () => {    qty.value += 2    console.log(total.value)   // 36: computed on this read, from the new qty  }  return <Button onClick={addTwo}>Add two ({total.value})</Button>}

The page catches up after your handler

Writes are batched. However many boxes you write in a handler, and however many times, the DOM is updated once, after the handler returns, in a single pass. That pass runs on the next microtask: before the browser paints, and before any timer.

Usually you never notice. But code that reads the DOM in the handler, right after a write, sees the page as it was:

count.value is the new number at once. The <strong> still shows the old one until flush(). flush() from @weft-js/core runs the queue now, so the DOM matches your boxes before the next line.

You need it when the DOM itself is what you want next: focusing or scrolling to an element that a write just showed, or measuring one that a write just changed.

import { flush, state } from '@weft-js/core'import { Button, Input } from '@weft-js/warp'export function Rename() {  const editing = state(false)  let field: HTMLInputElement | undefined  const start = () => {    editing.value = true    flush()            // the input exists now    field?.focus()  }  return (    <div>      {editing.value        ? <Input label="Name" ref={(el: HTMLInputElement) => (field = el)} />        : <Button onClick={start}>Rename</Button>}    </div>  )}

Without flush(), field would still be undefined: the input is only made when the queue runs.

batch()

batch(fn) runs fn and returns what it returned. It changes nothing: writes are always batched until the flush. It exists so code ported from libraries where batching is opt-in can say so at the call, and so a reader of your code knows the writes inside belong together:

import { batch, type State } from '@weft-js/core'export function rename(name: { first: State<string>; last: State<string> }, first: string, last: string) {  batch(() => {    name.first.value = first    name.last.value = last  })}

If you want one change to be a single step in undo history, that's what an action in 0 is for: each action call is one transaction.

Reading without subscribing: untrack()

Every .value read inside JSX, a derived or a watch source subscribes. Now and then you want the value without the subscription: "use the unit as it is now, but don't recompute when it changes". Wrap that read in untrack:

import { derived, state, untrack } from '@weft-js/core'export function makeReading() {  const celsius = state(20)  const label = state('Kitchen')  // Recomputes when the temperature changes. The label is read as it is then, without subscribing to it.  const line = derived(() => `${untrack(() => label.value)}: ${celsius.value} °C`)  return { celsius, label, line }}

Use it sparingly. Something that should update when a box changes should read it normally. untrack in a component body whose result only the JSX reads renders the value from setup time and never updates; the compiler warns about that with W018. Handlers don't need untrack: they aren't readers, so nothing they read subscribes.

Where your code runs, and how often

Putting it together, each piece of a component runs at its own time:

This table is the reason for most of weft's rules. A value computed in the body is computed once and goes stale, so it belongs in derived (W001). An early return that depends on state is checked once (also reported as W001), so the branch belongs in JSX. A let counter changes but nothing re-reads it (W041 in the catalog; this weft doesn't report it yet). Each rule is the table, applied.

Recap

• A write stores the value at once, marks its readers and queues the DOM bindings that read it.
• The queue runs once, on the next microtask, in creation order. Each binding updates the one node it owns.
• The component body never runs again. There's no re-render and no diff, except matching rows by key in lists.
• A write that's Object.is the old value does nothing; a derived that comes out the same stops the update there.
• Reads after a write see the new value, derived included. There is no snapshot and no need for updater functions.
• The DOM catches up after the handler. flush() brings it up to date now, for focus, scroll or measuring.
• batch() only names a batch that was happening anyway. untrack() reads without subscribing.

Try it