Live reload
How the browser reloads when you save a file during chroma dev, and the exact flags, variables, and settings that turn it on or off.
During chroma dev in a browser, the dev server watches your project and reloads the whole tab when a source file changes. This is a full page reload, not hot module replacement: the tab restarts, so state held in signals is lost and the WASM engine and module graph stay consistent.
Chroma Desktop develop mode never reloads. The window keeps running while you edit; reopen or refresh it yourself to see changes.
When reload is on
| How you run it | Live reload |
|---|---|
chroma dev in the browser (--no-desktop, or any app without dev.desktop: true) | On |
chroma dev with dev.desktop: true (Chroma Desktop opens) | Off |
engine run by hand without flags | Off |
chroma build output | Off, no client is injected |
Turn it on or off
This table is the single reference for every switch. The same names appear in the CLI reference and Server.
| Switch | Where | Effect |
|---|---|---|
dev.hotReload | chroma.json | false disables reload for the project. When set, it wins over the variable and the flags below. The key keeps this name. |
chroma dev --no-reload | CLI (alias --no-hot-reload) | Disable for this session. |
chroma dev --reload | CLI (alias --hot-reload) | Enable for this session. |
CHROMA_DEV_RELOAD=0 or 1 | Environment | 0 disables, 1 enables. Desktop develop mode sets 0 for you. |
CHROMA_DEV_RELOAD_DEBOUNCE_MS | Environment | Wait after a change before reloading. Default 300. |
engine --reload | Dev server (aliases --watch, --hot-reload) | Enable for this process. |
engine --no-reload | Dev server (alias --no-watch) | Disable. Beats --reload and CHROMA_DEV_RELOAD=1. |
For the standalone engine, reload is on only if you pass --reload (or set CHROMA_DEV_RELOAD=1) and nothing disables it. CHROMA_DEV_RELOAD=0 always wins.
What the server watches
Under the app root, skipping hidden folders and node_modules, dist, target, pkg, build, coverage:
chroma.jsonandchroma-fs.json- Everything under
assets/ - Any
.chrfile - Files in
src/andplugins/with a web extension (chr,js,mjs,html,css,json,svg,wasm,png,jpg,jpeg,webp,ico) - Any
.htmlfile, including the rootindex.html
The watcher polls file modification times every 200 ms, then waits the debounce interval and confirms the change before reloading.
How it works
- The dev server injects
<script src="/__chroma/dev-reload.js"></script>into every HTML response. - That script opens a WebSocket to
/__chroma/dev/reload?clientKind=browser. - When a watched file changes, the server sends
{"type":"reload"}and the page callslocation.reload(). If the socket drops, the script reconnects every 800 ms.
A page URL containing chroma_no_reload=1 skips the client script. A WebSocket request with clientKind=desktop is rejected with 403.
Try it
cd my-app
chroma dev --no-desktop
# Open http://localhost:4173 (or your dev.port) and view source:
# it includes /__chroma/dev-reload.js.
# Edit src/App.chr and save: the tab reloads within about a second.To confirm it is off with Desktop, run chroma dev in an app with dev.desktop: true, edit a .chr file, and notice the window does not reload.