Skip to content

Introduction

What Xote is, what it feels like to use, and where to go next.

docs/index.md
Raw Markdown

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.

Counter.res
1let count = Signal.make(0)
2let doubled = Computed.make(() => Signal.get(count) * 2)
3
4@xote.component
5let 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 View helpers 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

ModuleWhat it's for
SignalState you can read and update
ComputedValues derived from other signals
EffectSide effects that rerun when their inputs change
View and JSXComponents, lists, conditions, refs, portals
Context New in 7.2Values shared with everything a component renders
Resource New in 7.2Async data as signals, with Suspense
RouterURL matching, links and navigation
SSR and HydrationRender on the server, pick up on the client

Where to start

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

ItemValue
Packagexote (npm)
LanguageReScript 12 (JSX v4 with "module": "XoteJSX")
Current stable7.2.0
New in 7.2.0adds 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 corere-exported from rescript-signals (Signal, Computed, Effect)

Module map

ModulePurposeReScript accessJS entrySince
Signalwritable state, get/peek/set/update/batch/untrackXote.Signalxote, xote/signalstable
Computedderived read-only valuesXote.Computedxote, xote/computedstable
Effectreactive side effects with cleanupXote.Effectxote, xote/effectstable
Viewnodes, JSX primitives (For, Show, Maybe, Value, Text…), mountingXote.Viewxote, xote/viewstable
MaybeSignala prop that is either static or reactiveXote.MaybeSignalxote, xote/maybe-signal7.1.0
XoteJSXthe JSX module ("jsx": {"module": "XoteJSX"})Xote.XoteJSXxote/jsxstable
Router, RouteURL matching, links, navigationXote.Routerxote/routerstable
SSR, SSRContext, SSRStateserver rendering, environment checks, state transferXote.SSRxote/ssrstable
Hydrationhydrate server-rendered HTMLXote.Hydrationxote/hydrationstable
Mdxrender MDX documents as Xote nodesXote.Mdxxote/mdxstable
Contextvalues scoped to a subtreeXote.Contextxote, xote/context7.2.0 (new)
Resourceasync values as signals; works with View.SuspenseXote.Resourcexote, xote/resource7.2.0 (new)

Prop is a deprecated alias of MaybeSignal; MUST NOT be used in new code.

Rules

  1. Every component MUST be a module (or file) whose make is annotated @xote.component (recommended) or @jsx.component. One component per module.
  2. A component body runs exactly once per instance, untracked. It MUST NOT be relied on to re-run.
  3. A Signal.get written in JSX position (an attribute value of an intrinsic element, or a bare {…} child) under @xote.component becomes a reactive leaf. The same call in the component body, or bound to a let, is a one-time read.
  4. Props of user components are evaluated once. To pass changing data, pass the Signal.t (or a MaybeSignal.t, or a thunk) and read it inside the child's JSX.
  5. Derived values MUST be computeds, not signals synchronised by effects.
  6. Effects are for work outside the node tree (timers, storage, network, logging). An effect that allocates something MUST return Some(cleanup).
  7. Lists that can reorder, insert or remove MUST use View.For with by (a stable string key), not Array.map inside a tracked region.
  8. if/switch on a signal in JSX rebuilds only the selected branch when the condition changes; reads inside the branch stay fine-grained.
  9. Code that touches window/document MUST NOT run at module top level or in a component body of an app that is server-rendered; use View.onMount (7.2.0) or guard with SSRContext.isClient.
  10. Signal equality defaults to ===. Replacing a record/array with a structurally equal copy still notifies; pass ~equals to Signal.make to change that.

API

The entry points an agent touches first:

NameSignatureBehaviour
Signal.make('a, ~name: string=?, ~equals: ('a, 'a) => bool=?) => Signal.t<'a>creates a signal
Signal.getSignal.t<'a> => 'atracked read
Signal.set(Signal.t<'a>, 'a) => unitwrite; notifies if not equal
Signal.update(Signal.t<'a>, 'a => 'a) => unitwrite 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=?) => unitruns now and on dependency change
View.mountById(View.node, string) => unitrenders into the element with that id
View.ForJSX: <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.res
2let count = Signal.make(0)
3let doubled = Computed.make(() => Signal.get(count) * 2)
4
5@xote.component
6let 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.res
2View.mountById(<Counter />, "app")

Which page answers which task

TaskRead
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.component
2let 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.component
2let 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 None
5})

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.component is 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.probe logs 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 rescript exits 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).
  • /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.