Thinking in signals
Components run once; only the parts that read a signal update. Everything else follows from that.
Xote has one idea that shapes everything else: a component runs once, and only the parts that read a signal update afterwards. Once that clicks, the rest of the docs read like details.
A component runs once
In many UI libraries a component is a function that runs again on every change. In Xote it runs one time, builds its piece of the page, and is done. Try it:
1let bodyRuns = ref(0)2let clicks = Signal.make(0)34@xote.component5let make = () => {6 bodyRuns := bodyRuns.contents + 17 let ranAtRender = bodyRuns.contents89 <div>10 <button onClick={_ => Signal.update(clicks, n => n + 1)}>11 {"Click me"}12 </button>13 <p> {"Clicks: "} {Signal.get(clicks)} </p>14 <p> {"Times the component ran: "} {ranAtRender} </p>15 </div>16}Clicks: 0
Times the component ran: 1
The click count climbs. The run count stays at 1. Clicking never calls the component again; it only updates the one text node that reads clicks.
Reads in JSX stay live
When you write Signal.get(clicks) inside JSX, @xote.component turns that spot into a live binding: a text node, or an attribute, that updates itself when the signal changes. Each binding is independent, so a change touches only the bindings that read it.
The same call outside JSX, in the component body, is a plain one-time read:
1@xote.component2let make = () => {3 let label = Int.toString(Signal.get(count)) // read once, when the component runs4 <p> {label} </p> // so this never changes5}
Read the signal where you show it instead:
1@xote.component2let make = () => <p> {Signal.get(count)} </p>
The component body is for setup: creating local signals, defining handlers, starting effects. The JSX is where values are shown.
Derive, don't copy
When a value depends on other signals, make it a computed. It stays in sync on its own and recalculates only when one of its inputs changes.
1let price = Signal.make(20)2let quantity = Signal.make(2)3let total = Computed.make(() => Signal.get(price) * Signal.get(quantity))
There's no dependency list to maintain: whatever the function reads is what it depends on. Read total like any signal, with Signal.get(total). More in Computeds.
Effects talk to the outside world
Use an effect when a change should cause something outside the page's markup: saving to storage, logging, starting a timer, calling an API.
1Effect.run(() => {2 Console.log2("Total is now", Signal.get(total))3 None4})
It runs once right away, then again whenever a signal it read changes. If you find yourself setting a signal from an effect just to keep two values in sync, you want a computed instead. More in Effects.
Pass signals to components, not values
Props are read once, when the child component runs. To give a child something that changes, pass the signal itself and let the child read it in its JSX:
1module Badge = {2 @xote.component3 let make = (~count: Signal.t<int>) => <span class="badge"> {Signal.get(count)} </span>4}56<Badge count />
Writing <Badge count={Signal.get(count)} /> instead would hand over a snapshot that never updates. The type checker helps here: count is a Signal.t<int>, not an int.
Conditions rebuild only their branch
An if or switch on a signal inside JSX swaps its branch when the condition changes. The rest of the component stays as it is, and inside the branch, reads stay fine-grained.
1@xote.component2let make = () =>3 <div>4 {if Signal.get(loggedIn) {5 <p> {"Welcome back, "} {Signal.get(name)} </p>6 } else {7 <button onClick={_ => Signal.set(loggedIn, true)}> {"Log in"} </button>8 }}9 </div>
Changing name updates just the name. Changing loggedIn swaps the branch. Lists work the same way with View.For, which adds, moves and removes items instead of rebuilding the list.
If you know React
| In React | In Xote |
|---|---|
useState | Signal.make, at module level or in the component body |
useMemo | Computed.make |
useEffect | Effect.run, or View.onMount New in 7.2 for DOM setup |
| Dependency arrays | None: reads are tracked automatically |
| Re-rendering a component | Doesn't happen; bindings update in place |
React.memo, useCallback | Not needed |
The React comparison goes deeper.
Next
Build something with these ideas in the tutorial, or start the Learn section with Signals.
Summary
This page specifies Xote's execution model: which code runs once, which code re-runs, and exactly which signal reads subscribe. A component's make runs once per instance; its returned node tree is built once; afterwards only tracking scopes re-run when one of their dependencies changes. Under @xote.component, the PPX turns each attribute or bare child that reads a signal into its own tracking scope (a reactive leaf). The one rule that decides most bugs: a read is reactive only if it is evaluated inside a tracking scope; everything else is a one-time value.
Availability
| Item | Value |
|---|---|
| Model | all versions |
PPX decomposition (@xote.component, View.child, View.probe, condition-only tracking of control flow, helper functions decomposed) | stable since 7.1.0 (ppx-flags: ["xote/ppx/ppx"]) |
View.tracked | stable since 7.1.0 |
View.onMount, View.onCleanup | 7.2.0 (new) |
Rules
What runs, and when
- A component's
make(the component body) runs once per instance, untracked: signal reads in it do not subscribe anything. - The node tree returned by
makeis built once. Elements keep their DOM identity for the life of the instance. - A tracking scope re-runs when any of its dependencies changes. Tracking scopes are: a computed's function, an effect's function, a reactive leaf, a
View.trackedblock, the condition of a reactiveif/switchin JSX, and a resource's fetch up to its firstawait. - Dependencies are re-collected on every run of a scope: a read that a run did not perform (e.g. in an untaken branch) is not a dependency for that run.
- A signal notifies only when the new value is not equal to the old one (
===by default,~equalsto override). - Computeds are lazy: they compute when read and cache until a dependency changes.
- Effects run once immediately when created, then after each change of a dependency; the previous run's cleanup runs first.
- Signals, computeds, effects and resources created during a component body are owned by that component and disposed with it (since 7.1.0 for effects).
What the PPX makes reactive (@xote.component)
- Attribute on an intrinsic element (
<div class={…}>) whose expression reads a signal → thunked into a reactive attribute (View.computedAttr). Without a read → static attribute. - Bare child
{…}→ wrapped inView.child. An expression that reads a signal is thunked first and becomes reactive text; a scalar ("x",42) becomes static text; an existing node passes through; a bareSignal.tvalue becomes reactive text; an array becomes a fragment. if/switchin child position whose condition reads a signal → the branches are decomposed, then wrapped inView.tracked, which tracks only the condition (andwhenguards). Changing the condition rebuilds the selected branch; reads inside the branch remain separate leaves.if/switchwhose condition reads nothing → not wrapped; branches still decomposed.- User-component props (
<Card label={…} />) are never thunked: each is a one-time read evaluated where the JSX is written. Exception: props whose value is JSX or a function returning JSX are decomposed as node position. attrs,data, event handlers are left exactly as written. Reactivity inattrscomes from passing a thunk or a signal as the value:attrs=[("data-theme", () => Signal.get(theme))].- Scope of the transform: in a file containing at least one
@xote.component, all JSX is decomposed, including plain helper functions that return JSX. A file with no annotation is not transformed. - Read detection recognises
Signal.get,MaybeSignal.get,Prop.get, pipes,let/module/openaliases, local helper functions whose body reads, and helpers in same-file modules.Signal.peekis never a read. - Hidden reads: a read behind a call the PPX cannot resolve (a function in another module) compiles to a one-time value. In development the leaf is wrapped in
View.probe, which logs once per source location:[Xote] File.res:line:col: this value reads a signal through a call @xote.component cannot see …. Development mode isglobalThis.__XOTE_DEV__if set, elseprocess.env.NODE_ENV !== "production". - A value already written as a thunk (
{() => …},class={() => …}) is never double-wrapped; wrapping in a thunk is always a valid way to force reactivity. - Binding a read to a
letmakes it a one-time read. To extract a reactive expression, bind a thunk (let label = () => …) and use{label()}or{label}.
API
| Name | Signature | Behaviour |
|---|---|---|
Signal.get | Signal.t<'a> => 'a | tracked read inside a tracking scope; plain read elsewhere |
Signal.peek | Signal.t<'a> => 'a | untracked read, never subscribes |
Signal.untrack | (unit => 'a) => 'a | runs the function with tracking disabled |
View.tracked | (unit => View.node) => View.node | a region that re-renders wholesale when any read inside it changes |
View.child | 'a => View.node | runtime coercion used for bare children under the PPX |
View.probe | (string, unit => 'a) => 'a | emitted by the PPX around unresolvable calls; reports hidden reads in development |
Patterns
Reactive leaf (use for any value shown in markup):
1@xote.component2let make = () => <p class={Signal.get(active) ? "on" : "off"}> {Signal.get(count)} </p>
Pass a signal to a child component (use when the child shows a changing value):
1module Badge = {2 @xote.component3 let make = (~count: Signal.t<int>) => <span> {Signal.get(count)} </span>4}56@xote.component7let make = () => <Badge count />
Reusable reactive expression bound as a thunk (use to name a computation used in markup):
1@xote.component2let make = () => {3 let label = () => "n=" ++ Int.toString(Signal.get(count))4 <p> {label()} </p>5}
Derived value shared by several leaves (use when more than one place needs it, or it is expensive):
1let total = Computed.make(() => Signal.get(price) * Signal.get(quantity))
Cross-module helper made reactive at the call site:
1<p> {() => Store.label()} </p>
Mapping from React
| React | Xote | Notes |
|---|---|---|
useState | Signal.make in the component body or at module level | body runs once, so no hook rules; module level = shared state |
useMemo | Computed.make | no dependency array; reads are tracked |
useEffect | Effect.run | runs immediately, re-runs on change, cleanup via Some(fn) |
useEffect(…, []) for DOM work | View.onMount (7.2.0) | runs once after insertion, client only |
useRef (DOM) | View.Ref.make + ref= (7.2.0) | |
useContext | Context.use (7.2.0) | |
React.memo, useCallback | not needed | components never re-run |
key on list items | View.For with by | Array.map in a tracked region rebuilds every item |
Suspense, error boundary | View.Suspense, View.ErrorBoundary (7.2.0) | |
className, htmlFor, type | class, for_, type_ | for_ and type_ render as for and type; className is a compile error |
| re-render on prop change | not applicable | pass signals; leaves update |
Non-equivalents: there is no render function to re-run; there is no stale-closure problem (handlers read current values via Signal.get/Signal.peek); and there is no automatic batching: each Signal.set outside Signal.batch notifies its dependents synchronously, so two consecutive writes run a dependent effect twice. Wrap related writes in Signal.batch.
Anti-patterns
Hoisted read:
1@xote.component2let make = () => {3 let label = Int.toString(Signal.get(count))4 <p> {label} </p>5}
Symptom: text never updates. Fix: <p> {Signal.get(count)} </p> or bind a thunk (rule 19).
Value passed to a component prop:
1<Badge count={Signal.get(count)} />
Symptom: compile error if ~count is Signal.t<int>; if ~count is int, the badge is frozen. Inside a reactive branch, the read also subscribes the branch, which then rebuilds wholesale whenever count changes. Fix: pass the signal.
Cross-module helper in a leaf:
1<p> {Store.label()} </p>
Symptom: static text plus one [Xote] … reads a signal through a call @xote.component cannot see warning in development. Fix: {() => Store.label()}, or move the read inline.
List built with Array.map over a signal:
1<ul> {Signal.get(items)->Array.map(item => <li> {item} </li>)} </ul>
Symptom: every change rebuilds all items; focus and input state inside rows are lost. Fix: <View.For each={MaybeSignal.reactive(items)} by={item => item} render={item => <li> {item} </li>} /> (use a real id as the key).
Large View.tracked block:
Symptom: any dependency change replaces the whole block's DOM. Fix: plain JSX under the PPX (leaves are separate), if/switch for structure, View.For for lists.
Edge cases
View.childaccepts any type: a record or variant in child position compiles under the PPX and renders[object Object]with a development warning.- A probed site warns only on its first evaluation and only for a scalar result; a hidden read in a branch never rendered during development is not reported.
- A branch swap builds the new branch from scratch (no diff between branches); state inside the old branch is discarded.
- Reads inside event handlers are not tracked (handlers are not tracking scopes); use
Signal.peekthere to make the intent explicit. - Writing a signal inside an effect is allowed but SHOULD be avoided for derived data (use a computed).
SSR and hydration
During SSR.renderToString, component bodies run once and leaves are evaluated once to produce HTML; effects do not run. Hydration re-runs component bodies on the client to rebuild the reactive graph and attaches to the existing DOM instead of creating it. Code in a component body therefore runs on both server and client.
Verify
- Inspect compiled output: a reactive leaf appears as
View.child(() => …)or a thunked attribute; a static value appears without a thunk. - Runtime test: mount in jsdom, record the element (
document.querySelector), change a signal, assert the same element is still in the document and only its text/attribute changed. - In development, any
[Xote] … reads a signal through a call @xote.component cannot seewarning marks a stale leaf to fix.
Related
/docs/learn/rendering— leaves, attributes, conditionals and lists in practice./docs/learn/signals— equality, peek, untrack./docs/learn/computeds,/docs/learn/effects— the other tracking scopes./docs/learn/components— props and children.