Skip to content

Quick start

Install Xote, turn on its JSX transform, and render your first component.

docs/quick-start.md
Raw Markdown

This page takes you from an empty folder to a working counter in the browser. It takes about five minutes.

Start a ReScript project

Xote works in a ReScript 12 project with a bundler such as Vite. If you're starting fresh, create one with Vite:

1npm create rescript-app@latest

Pick the Vite template when asked. You'll get a rescript.json, an index.html and a src folder. Already have a project? Skip ahead.

Install Xote

1npm install xote

With pnpm, also allow Xote's install script so it can set up the JSX transform (see Troubleshooting):

1pnpm add xote
2pnpm approve-builds

Turn on the JSX transform

Add these fields to your rescript.json:

1{
2 "dependencies": ["xote"],
3 "jsx": {
4 "version": 4,
5 "module": "XoteJSX"
6 },
7 "ppx-flags": ["xote/ppx/ppx"],
8 "compiler-flags": ["-open Xote"]
9}

What each line does:

  • "dependencies" makes Xote's modules available to your code.
  • "jsx" tells ReScript to compile JSX with Xote instead of React.
  • "ppx-flags" enables @xote.component, which lets you read signals right inside JSX. It's a small prebuilt binary that ships in the package. It's the recommended way to write components, though a few of its details are still settling; see its README.
  • "-open Xote" lets you write Signal and View instead of Xote.Signal and Xote.View. Without it, add open Xote at the top of each file.

Write your first component

Create src/Counter.res:

1let count = Signal.make(0)
2
3@xote.component
4let make = () =>
5 <div>
6 <h1> {"Counter"} </h1>
7 <p> {"Count: "} {Signal.get(count)} </p>
8 <button onClick={_ => Signal.update(count, n => n + 1)}> {"Increment"} </button>
9 </div>

Signal.make(0) creates a piece of state. Signal.get(count) inside the JSX shows it and keeps it up to date. Signal.update changes it when the button is clicked.

Mount it

Create src/Main.res to put the component on the page:

1View.mountById(<Counter />, "app")

Then point index.html at the compiled file and give it an element with that id:

1<body>
2 <div id="app"></div>
3 <script type="module" src="/src/Main.res.mjs"></script>
4</body>

The mount lives in its own file because a ReScript module can't refer to itself by name.

Run it

Start the ReScript compiler in watch mode and the Vite dev server, each in its own terminal:

1npx rescript watch
1npx vite

Open the address Vite prints and click the button. The count goes up, and that number is the only thing on the page that changes.

Troubleshooting

The build fails at @xote.component or ppx-flags. The JSX transform binary wasn't set up. Package managers that skip install scripts (pnpm does by default) need pnpm approve-builds, or run the setup once by hand:

1node node_modules/xote/ppx/postinstall.js

No prebuilt binary for your platform. Binaries ship for Linux (x64, arm64), macOS (x64, arm64) and Windows (x64). On anything else the install script builds the transform from source, which needs the OCaml compiler (ocamlopt). You can rerun that build with sh node_modules/xote/ppx/build.sh.

Rather not use the transform? Leave out ppx-flags and write @jsx.component instead of @xote.component. Reactive values then need explicit wrappers; Rendering shows both styles.

"The module or file Signal can't be found." Add "-open Xote" to compiler-flags, or open Xote at the top of the file.

Next

Read Thinking in signals next. It explains the one idea behind everything you just did, and it's short.

Summary

This page is an executable setup checklist for a new or existing ReScript 12 project, followed by an error→cause→fix table. A correct setup needs four rescript.json fields (dependencies, jsx, ppx-flags, compiler-flags), the xote npm package with its install script run (it installs the PPX binary), an entry file that calls View.mountById, and an HTML element with the matching id. The most common failure is a missing PPX binary because the package manager skipped install scripts.

Availability

ItemValue
Packagexote (npm), stable 7.2.0
CompilerReScript 12 (the PPX is validated against ReScript 12's ppx ABI)
PPXxote/ppx/ppx, prebuilt for linux-x64, linux-arm64 (glibc), darwin-x64, darwin-arm64, win32-x64 (ppx/ppx.exe)
Bundlerany ES-module bundler; examples use Vite
Required runtime dependencyrescript-signals (installed automatically as a dependency of xote)

Rules

  1. rescript.json MUST list "xote" in "dependencies". Without it, Xote.* modules cannot be resolved.
  2. rescript.json MUST set "jsx": {"version": 4, "module": "XoteJSX"}. Without it, JSX compiles against React's JSX module and fails.
  3. To use @xote.component, rescript.json MUST set "ppx-flags": ["xote/ppx/ppx"]. The flag belongs in the application's rescript.json, not in any dependency.
  4. "compiler-flags": ["-open Xote"] SHOULD be set; otherwise every file that uses Signal, View, … MUST start with open Xote.
  5. The npm install script of xote (postinstall: node ppx/postinstall.js) MUST have run once; it copies the platform binary to node_modules/xote/ppx/ppx. pnpm skips dependency install scripts by default; run pnpm approve-builds or node node_modules/xote/ppx/postinstall.js.
  6. If no prebuilt binary matches the platform, or it does not execute (e.g. musl/Alpine, because the Linux binaries are glibc-linked), the install script compiles the PPX from source when ocamlopt is on PATH; otherwise it prints instructions and exits 0. It never fails the install.
  7. When no binary could be installed (and not on Windows), the install script writes an executable stub at ppx/ppx that fails the build with a message naming the fix.
  8. A module MUST NOT render itself by its own file name. Put View.mountById(<App />, "app") in a separate entry file (e.g. Main.res).
  9. The HTML page MUST contain the element whose id is passed to View.mountById, and MUST load the compiled entry (Main.res.mjs with the usual "suffix": ".res.mjs", "in-source": true) as type="module".
  10. The ReScript compiler and the bundler run as two processes in development (npx rescript watch and npx vite); the bundler consumes the compiled .res.mjs files.

API

NameSignatureBehaviour
View.mountById(View.node, string) => unitrenders the node into the element with that id; logs Container element not found: <id> to the console if missing
View.mount(View.node, Dom.element) => unitrenders into a given element

Patterns

Checklist (execute in order)

  1. Create a project if none exists: npm create rescript-app@latest, choose the Vite template.
  2. Install: npm install xote (pnpm: pnpm add xote then pnpm approve-builds; yarn: yarn add xote).
  3. Confirm the PPX binary: node_modules/xote/ppx/ppx --help exits 0 (Windows: ppx.exe). If not, run node node_modules/xote/ppx/postinstall.js and read its output.
  4. Merge into rescript.json (keep existing sources, package-specs, suffix):
1{
2 "dependencies": ["xote"],
3 "jsx": { "version": 4, "module": "XoteJSX" },
4 "ppx-flags": ["xote/ppx/ppx"],
5 "compiler-flags": ["-open Xote"]
6}
  1. Create src/Counter.res:
1let count = Signal.make(0)
2
3@xote.component
4let make = () =>
5 <div>
6 <h1> {"Counter"} </h1>
7 <p> {"Count: "} {Signal.get(count)} </p>
8 <button onClick={_ => Signal.update(count, n => n + 1)}> {"Increment"} </button>
9 </div>
  1. Create src/Main.res:
1View.mountById(<Counter />, "app")
  1. In index.html:
1<body>
2 <div id="app"></div>
3 <script type="module" src="/src/Main.res.mjs"></script>
4</body>
  1. Build once: npx rescript (exit code 0). Develop: npx rescript watch and npx vite in two terminals.

File layout

rescript.json
index.html
src/
  Main.res          entry: mounts the root component
  App.res           root component (optional)
  Counter.res       one component per file (or per submodule)

Without the PPX

Use when the PPX cannot be installed. Omit ppx-flags; write @jsx.component; reactive attributes take thunks; text uses value components:

1let count = Signal.make(0)
2
3@jsx.component
4let make = () =>
5 <p class={() => Signal.get(count) > 0 ? "on" : "off"}>
6 <View.Text> "Count: " </View.Text>
7 <View.Int> {count} </View.Int>
8 </p>

Anti-patterns

ppx-flags added to a dependency's config or omitted from the app: @xote.component is then an unknown attribute and bare children fail to type-check (error below). Fix: add "ppx-flags": ["xote/ppx/ppx"] to the app's rescript.json.

Mount call inside the component file:

1// Counter.res
2@xote.component
3let make = () => <p> {"hi"} </p>
4View.mountById(<Counter />, "app")

Symptom: compile error The module or file Counter can't be found. (a module cannot reference itself). Fix: move the call to Main.res.

Running only the bundler: Vite serves stale or missing .res.mjs files. Fix: run npx rescript watch alongside it.

Edge cases

  • The PPX opt-in is per file: in a file containing at least one @xote.component, all JSX (including helper functions returning JSX) is decomposed. A file without the annotation is untouched.
  • Removing the last @xote.component from a file silently makes its helpers static, or breaks the build if they use bare children.
  • A ReScript release that changes the ppx AST version makes the PPX fail the build immediately with an error naming the mismatched magic number; pin ReScript 12.

Error → cause → fix

Error text (as printed by ReScript or the stub)CauseFix
The module or file Signal can't be found.no -open Xote and no open Xote in the file, or xote missing from dependenciesadd "compiler-flags": ["-open Xote"] or open Xote; add "xote" to dependencies
This has type: string / But this function argument is expecting: XoteJSX.element on a {"…"} childbare child without the PPX (no ppx-flags, or the file has no @xote.component)enable the PPX and annotate, or wrap in <View.Text> / View.text(…)
xote: @xote.component ppx binary missing (the install script did not run).stub at ppx/ppx: install script ran but no binary could be installedrun node node_modules/xote/ppx/postinstall.js (pnpm: pnpm approve-builds first); on unsupported platforms install ocamlopt or run sh node_modules/xote/ppx/build.sh
try_package_path: upward traversal did not find 'xote/ppx/ppx'install script never ran (pnpm default, --ignore-scripts), or Windows without a binarysame as above
`type` is a reserved keyword. Keywords need to be escapedtype="text" on an elementwrite type_="text"
The field className does not belong to type Xote.XoteJSX.Elements.propsReact-style propwrite class
Only one component definition is allowed for each module.two annotated makes in one modulemove one into a submodule or file
This has type: Xote.Signal.t<int> / But the component prop count is expected to have type: intpassing a signal to a prop declared as a valuedeclare the prop as Signal.t<int> (to stay reactive) or pass Signal.get(x) (one-time value)
Container element not found: app (browser console)no element with that id when mountById ranadd the element, or load the script after it / with type="module"

SSR and hydration

Not part of a minimal setup. For server rendering, the server calls SSR.renderToString/SSR.renderDocument and the client calls Hydration.hydrateById instead of View.mountById; see /docs/advanced/ssr and /docs/guides/deploying.

Verify

  • node_modules/xote/ppx/ppx --help exits 0.
  • npx rescript exits 0; src/Counter.res.mjs exists and contains no View.text("hello") where a reactive read was intended (reactive leaves compile to thunks such as View.child(() => …)).
  • In the browser, clicking the button changes only the number; no console errors.
  • /docs/thinking-in-signals — what the PPX turns into reactive leaves.
  • /docs/guides/project-structure — larger layouts and where state lives.
  • /docs/learn/rendering — both component styles (with and without the PPX).