Introduction
What Xote is, what it feels like to use, and where to go next.
Xote is a small UI library for ReScript. You keep state in signals, write components in JSX, and when a value changes Xote updates exactly the text or attribute that shows it. Nothing else re-renders.
A first look
A signal holds a value. A computed derives one. The component reads both, and each read becomes a tiny live binding in the page.
1let count = Signal.make(0)2let doubled = Computed.make(() => Signal.get(count) * 2)34@xote.component5let make = () =>6 <div>7 <button onClick={_ => Signal.update(count, n => n + 1)}>8 {"Clicked "}9 {Signal.get(count)}10 {" times"}11 </button>12 <p> {"Doubled: "} {Signal.get(doubled)} </p>13 </div>Doubled: 0
Click the button and only the two numbers change. The component function ran once, when it was first rendered; the button, the paragraph and the static text were built then and stay put.
Why Xote
- Updates where they matter. No virtual DOM and no re-running components. A change goes straight from the signal to the DOM node that reads it.
- A small surface. Signals, computeds and effects for state; JSX and a handful of
Viewhelpers for UI. Most apps need little else. - Types all the way down. ReScript checks your state, props and events at compile time, and compiles fast.
- The rest is built in. A router, server rendering with hydration, context and async resources come in the same package.
What's in the box
| Module | What it's for |
|---|---|
Signal | State you can read and update |
Computed | Values derived from other signals |
Effect | Side effects that rerun when their inputs change |
View and JSX | Components, lists, conditions, refs, portals |
Context New in 7.2 | Values shared with everything a component renders |
Resource New in 7.2 | Async data as signals, with Suspense |
Router | URL matching, links and navigation |
SSR and Hydration | Render on the server, pick up on the client |
Where to start
- New to Xote? Go to Quick start to set up a project, then read Thinking in signals for the one idea everything else builds on.
- Like learning by building? Follow the tutorial to make a small temperature converter.
- New to ReScript? Learning ReScript covers the syntax you'll see in these docs.
- Coming from React or SolidJS? See how Xote compares to React and to SolidJS.
- Not using ReScript? Xote's runtime also works from JavaScript.
Xote's reactive core comes from rescript-signals, which follows the same model as the JavaScript signals proposal.
Summary
Xote is a ReScript UI library with fine-grained reactivity. State lives in signals; derived state in computeds; side effects in effects. Components are functions that run once and return a node tree; afterwards, only reactive leaves (single attributes, single text nodes) and reactive regions (conditional branches, keyed lists) update. There is no virtual DOM, no diffing of component output, and no component re-execution. The rule that matters most: a signal read subscribes only where it is evaluated inside a tracking scope; a read in the component body is a one-time value.
Availability
| Item | Value |
|---|---|
| Package | xote (npm) |
| Language | ReScript 12 (JSX v4 with "module": "XoteJSX") |
| Current stable | 7.2.0 |
| New in 7.2.0 | adds Context, Resource, View.Suspense, View.ErrorBoundary, View.Portal, View.Ref, View.onMount, View.onCleanup) |
| Recommended component style | @xote.component (the PPX, "ppx-flags": ["xote/ppx/ppx"]), stable since 7.1.0 |
| Reactive core | re-exported from rescript-signals (Signal, Computed, Effect) |
Module map
| Module | Purpose | ReScript access | JS entry | Since |
|---|---|---|---|---|
Signal | writable state, get/peek/set/update/batch/untrack | Xote.Signal | xote, xote/signal | stable |
Computed | derived read-only values | Xote.Computed | xote, xote/computed | stable |
Effect | reactive side effects with cleanup | Xote.Effect | xote, xote/effect | stable |
View | nodes, JSX primitives (For, Show, Maybe, Value, Text…), mounting | Xote.View | xote, xote/view | stable |
MaybeSignal | a prop that is either static or reactive | Xote.MaybeSignal | xote, xote/maybe-signal | 7.1.0 |
XoteJSX | the JSX module ("jsx": {"module": "XoteJSX"}) | Xote.XoteJSX | xote/jsx | stable |
Router, Route | URL matching, links, navigation | Xote.Router | xote/router | stable |
SSR, SSRContext, SSRState | server rendering, environment checks, state transfer | Xote.SSR | xote/ssr | stable |
Hydration | hydrate server-rendered HTML | Xote.Hydration | xote/hydration | stable |
Mdx | render MDX documents as Xote nodes | Xote.Mdx | xote/mdx | stable |
Context | values scoped to a subtree | Xote.Context | xote, xote/context | 7.2.0 (new) |
Resource | async values as signals; works with View.Suspense | Xote.Resource | xote, xote/resource | 7.2.0 (new) |
Prop is a deprecated alias of MaybeSignal; MUST NOT be used in new code.
Rules
- Every component MUST be a module (or file) whose
makeis annotated@xote.component(recommended) or@jsx.component. One component per module. - A component body runs exactly once per instance, untracked. It MUST NOT be relied on to re-run.
- A
Signal.getwritten in JSX position (an attribute value of an intrinsic element, or a bare{…}child) under@xote.componentbecomes a reactive leaf. The same call in the component body, or bound to alet, is a one-time read. - Props of user components are evaluated once. To pass changing data, pass the
Signal.t(or aMaybeSignal.t, or a thunk) and read it inside the child's JSX. - Derived values MUST be computeds, not signals synchronised by effects.
- Effects are for work outside the node tree (timers, storage, network, logging). An effect that allocates something MUST return
Some(cleanup). - Lists that can reorder, insert or remove MUST use
View.Forwithby(a stable string key), notArray.mapinside a tracked region. if/switchon a signal in JSX rebuilds only the selected branch when the condition changes; reads inside the branch stay fine-grained.- Code that touches
window/documentMUST NOT run at module top level or in a component body of an app that is server-rendered; useView.onMount(7.2.0) or guard withSSRContext.isClient. - Signal equality defaults to
===. Replacing a record/array with a structurally equal copy still notifies; pass~equalstoSignal.maketo change that.
API
The entry points an agent touches first:
| Name | Signature | Behaviour |
|---|---|---|
Signal.make | ('a, ~name: string=?, ~equals: ('a, 'a) => bool=?) => Signal.t<'a> | creates a signal |
Signal.get | Signal.t<'a> => 'a | tracked read |
Signal.set | (Signal.t<'a>, 'a) => unit | write; notifies if not equal |
Signal.update | (Signal.t<'a>, 'a => 'a) => unit | write from the current value |
Computed.make | (unit => 'a, ~name: string=?, ~equals: ('a, 'a) => bool=?) => Signal.t<'a> | derived value, lazy |
Effect.run | (unit => option<unit => unit>, ~name: string=?) => unit | runs now and on dependency change |
View.mountById | (View.node, string) => unit | renders into the element with that id |
View.For | JSX: <View.For each by? render /> | list rendering, keyed with by |
Full signatures: /docs/api/signal, /docs/api/computed, /docs/api/effect, /docs/api/view.
Patterns
Minimal correct project configuration (rescript.json), use when creating or fixing a project:
1{2 "dependencies": ["xote"],3 "jsx": { "version": 4, "module": "XoteJSX" },4 "ppx-flags": ["xote/ppx/ppx"],5 "compiler-flags": ["-open Xote"]6}
Minimal component and mount (two files; a module cannot reference itself by file name), use as the starting template:
1// Counter.res2let count = Signal.make(0)3let doubled = Computed.make(() => Signal.get(count) * 2)45@xote.component6let make = () =>7 <div>8 <button onClick={_ => Signal.update(count, n => n + 1)}>9 {"Clicked "}10 {Signal.get(count)}11 {" times"}12 </button>13 <p> {"Doubled: "} {Signal.get(doubled)} </p>14 </div>
1// Main.res2View.mountById(<Counter />, "app")
Which page answers which task
| Task | Read |
|---|---|
| Set up a project, fix build/PPX errors | /docs/quick-start |
| Understand when code re-runs and why a value is stale | /docs/thinking-in-signals |
| State, equality, batching | /docs/learn/signals, /docs/advanced/batching |
| Derived values | /docs/learn/computeds |
| Timers, storage, network side effects | /docs/learn/effects |
| Component structure, props, children, mounting | /docs/learn/components |
| Text, attributes, events, conditionals, lists | /docs/learn/rendering |
| DOM refs, mount/cleanup, portals, error boundaries | /docs/learn/lifecycle |
| Subtree-scoped values | /docs/learn/context |
| Async data, loading/error states, Suspense | /docs/learn/async-data, /docs/guides/fetching-data |
| URLs and navigation | /docs/learn/routing |
| Forms | /docs/guides/forms |
| Server rendering and hydration | /docs/advanced/ssr, /docs/guides/deploying |
| Tests | /docs/guides/testing |
| Calling Xote from JavaScript | /docs/javascript |
| Vocabulary used across these pages | /docs/glossary |
Anti-patterns
Hoisted read (compiles, renders a stale value):
1@xote.component2let make = () => {3 let label = Int.toString(Signal.get(count))4 <p> {label} </p>5}
Symptom: the paragraph never changes after the first render. Fix: read in JSX position.
1@xote.component2let make = () => <p> {Signal.get(count)} </p>
Passing a value to a prop that should change (compiles, frozen):
1<Badge count={Signal.get(count)} />
Symptom: the badge keeps the initial number. Fix: declare ~count: Signal.t<int> on Badge and pass <Badge count />.
Synchronising state with an effect (compiles, extra work, transient inconsistency):
1let total = Signal.make(0)2Effect.run(() => {3 Signal.set(total, Signal.get(price) * Signal.get(quantity))4 None5})
Fix: let total = Computed.make(() => Signal.get(price) * Signal.get(quantity)).
Edge cases
View.child(the coercion behind bare children) accepts any type. A record or variant in child position compiles under the PPX and renders[object Object](with a development warning). Without the PPX it is a compile error.- A file with no
@xote.componentis not transformed by the PPX at all: bare children and inline reads there behave as in plain JSX (bare non-node children are compile errors). - A signal read hidden behind a function from another module is invisible to the PPX; it compiles to a one-time value and, in development,
View.probelogs one warning per source location. Wrap the value in() => …to make it reactive.
SSR and hydration
Components render to HTML with SSR.renderToString/SSR.renderDocument; the client calls Hydration to attach without re-creating DOM. Effects do not run on the server; resources stay Pending during a server render; View.onMount runs only on the client after hydration. See /docs/advanced/ssr.
Verify
- Build:
npx rescriptexits 0 with no "We've found a bug for you!" blocks. - Behaviour: mount into jsdom (
/docs/guides/testing), change a signal, assert only the expected text/attribute changed; the component function MUST NOT be called again. - Server:
SSR.renderToString(() => <App />)returns a string without throwing (no top-level DOM access).
Related
/docs/quick-start— exact setup and an error→fix table./docs/thinking-in-signals— the execution model and PPX decomposition rules./docs/glossary— definitions of the terms used on every page./llms.txt— index of every page as Markdown.