Quick start
Install Xote, turn on its JSX transform, and render your first component.
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 xote2pnpm 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 writeSignalandViewinstead ofXote.SignalandXote.View. Without it, addopen Xoteat the top of each file.
Write your first component
Create src/Counter.res:
1let count = Signal.make(0)23@xote.component4let 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
| Item | Value |
|---|---|
| Package | xote (npm), stable 7.2.0 |
| Compiler | ReScript 12 (the PPX is validated against ReScript 12's ppx ABI) |
| PPX | xote/ppx/ppx, prebuilt for linux-x64, linux-arm64 (glibc), darwin-x64, darwin-arm64, win32-x64 (ppx/ppx.exe) |
| Bundler | any ES-module bundler; examples use Vite |
| Required runtime dependency | rescript-signals (installed automatically as a dependency of xote) |
Rules
rescript.jsonMUST list"xote"in"dependencies". Without it,Xote.*modules cannot be resolved.rescript.jsonMUST set"jsx": {"version": 4, "module": "XoteJSX"}. Without it, JSX compiles against React's JSX module and fails.- To use
@xote.component,rescript.jsonMUST set"ppx-flags": ["xote/ppx/ppx"]. The flag belongs in the application'srescript.json, not in any dependency. "compiler-flags": ["-open Xote"]SHOULD be set; otherwise every file that usesSignal,View, … MUST start withopen Xote.- The npm install script of
xote(postinstall:node ppx/postinstall.js) MUST have run once; it copies the platform binary tonode_modules/xote/ppx/ppx. pnpm skips dependency install scripts by default; runpnpm approve-buildsornode node_modules/xote/ppx/postinstall.js. - 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
ocamloptis onPATH; otherwise it prints instructions and exits 0. It never fails the install. - When no binary could be installed (and not on Windows), the install script writes an executable stub at
ppx/ppxthat fails the build with a message naming the fix. - 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). - The HTML page MUST contain the element whose id is passed to
View.mountById, and MUST load the compiled entry (Main.res.mjswith the usual"suffix": ".res.mjs","in-source": true) astype="module". - The ReScript compiler and the bundler run as two processes in development (
npx rescript watchandnpx vite); the bundler consumes the compiled.res.mjsfiles.
API
| Name | Signature | Behaviour |
|---|---|---|
View.mountById | (View.node, string) => unit | renders 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) => unit | renders into a given element |
Patterns
Checklist (execute in order)
- Create a project if none exists:
npm create rescript-app@latest, choose the Vite template. - Install:
npm install xote(pnpm:pnpm add xotethenpnpm approve-builds; yarn:yarn add xote). - Confirm the PPX binary:
node_modules/xote/ppx/ppx --helpexits 0 (Windows:ppx.exe). If not, runnode node_modules/xote/ppx/postinstall.jsand read its output. - Merge into
rescript.json(keep existingsources,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}
- Create
src/Counter.res:
1let count = Signal.make(0)23@xote.component4let 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>
- Create
src/Main.res:
1View.mountById(<Counter />, "app")
- In
index.html:
1<body>2 <div id="app"></div>3 <script type="module" src="/src/Main.res.mjs"></script>4</body>
- Build once:
npx rescript(exit code 0). Develop:npx rescript watchandnpx vitein 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)23@jsx.component4let 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.res2@xote.component3let 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.componentfrom 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) | Cause | Fix |
|---|---|---|
The module or file Signal can't be found. | no -open Xote and no open Xote in the file, or xote missing from dependencies | add "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 {"…"} child | bare 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 installed | run 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 binary | same as above |
`type` is a reserved keyword. Keywords need to be escaped | type="text" on an element | write type_="text" |
The field className does not belong to type Xote.XoteJSX.Elements.props | React-style prop | write class |
Only one component definition is allowed for each module. | two annotated makes in one module | move one into a submodule or file |
This has type: Xote.Signal.t<int> / But the component prop count is expected to have type: int | passing a signal to a prop declared as a value | declare 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 ran | add 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 --helpexits 0.npx rescriptexits 0;src/Counter.res.mjsexists and contains noView.text("hello")where a reactive read was intended (reactive leaves compile to thunks such asView.child(() => …)).- In the browser, clicking the button changes only the number; no console errors.
Related
/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).