Duolith docs

The dev server

duolith dev serves your app at http://localhost:4321/, watches the project, and swaps each change into the open page as soon as it is saved. The page does not reload: what you typed, the posts you added and the screen you are on stay as they were.

duolith dev examples/social

What a change does

You editWhat the page does
A page's or layout's markup, script or handlersIts screens are built again from the new code. Each state(...) keeps the value it had. The router, the history, the layouts around the screen and every other screen stay.
A style block, or a utility class that only changes stylesThe styles are replaced. No screen is built again.
A componentEvery page and layout that places it, directly or through other components, is built again, keeping its state. The component's own state starts again.
A component a page loads as an island (load=)The page reloads, and the terminal and the console say why (E0571).
A state's type, in a page or layoutThat screen is built again with all its state from the start (E0572), and the terminal and the console say which state changed.
The routes (a page added, removed or moved), duolith.yaml, a duolith.<mode>.env file, a behaviour file or a public fileThe page reloads, and the terminal and the console say why (E0571).
Anything, so that it no longer builds or type-checksThe error shows over the running app, with the terminal's message. The app keeps running underneath, with its state, and the error goes when you fix it.

A state keeps its value while its name and its type stay the same. The type is what the script says: the type argument (state<Post[]>([])) with every type the file declares that it uses, so adding a field to type Post counts as a change, or, for state("") with none, the kind of the initial value (for state(load()), the expression itself). When the type or first value names an import from a file of the project, a change to that file starts the state again too. White space never counts. State shared by name (state(false, { shared: "signed-in" })) and state.load live on by themselves.

The type check runs after the swap, so a type error shows a moment after the code that has it.

To reload the whole page on every change instead, as before, run duolith dev --no-hot.

How it works

  1. The watcher looks at the project's files every 50 ms and rebuilds when one changed. The runtime is compiled once per run.
  2. The build is compared with the last one (crates/cli/src/dev/changes.rs). Only the files whose bytes changed are sent; a page whose module differs only in its styles is a change of styles.
  3. A message goes on the reload channel, /_duolith/reload (server-sent events): each changed module, its kind (page, layout, component, style) and a version, or a reload and why, or an error.
  4. In the browser, packages/client/src/web/hot imports each changed module again at ?v=<version>, so the browser fetches it, and the server points its imports of changed components at their versions too. All are loaded first, then swapped in together.
  5. State is carried by name: in a dev build the compiler wraps each state a page declares as duolith$keep("posts", "<type hash>", state(...)) and writes the same list into the module. The new screen takes the old one's values before anything reads them.

The native dev server (duolith dev --target android|ios) sends the same messages on its socket. A phone still loads the whole bundle again: swapping one module into a running Lynx app needs a device to verify.

Security

Hot replacement adds nothing another site can use:

  • The server listens on 127.0.0.1 only.
  • It answers only its own pages. A request whose Host is not localhost or an address written as numbers with the server's port, whose Origin is another site, or that a page on another site made (Sec-Fetch-Site) is refused with 403 (E0570). So a page open in the same browser can neither read your modules nor listen on the channel, and a name that only resolves to your computer (DNS rebinding) reads nothing. Every response says Cross-Origin-Resource-Policy: same-origin, X-Content-Type-Options: nosniff and X-Frame-Options: SAMEORIGIN, so another site can neither embed a module nor frame the app.
  • Messages name only modules under /_duolith/ on the page's own origin; the runtime ignores anything else.
  • The dev shell keeps the Content-Security-Policy of decision 0150: no eval, no new Function, no inline handlers. Modules load by address, and the error overlay sets its message as text.
  • Nothing of it ships: duolith build writes no hot module, no message handler and no state names, and checks every file it emits for them before writing anything (E0574).

How fast

pnpm bench --only dev-edit times each edit from the save to the browser showing it, with hot replacement and with a full reload, on the same machine. It fails unless hot replacement is faster for every edit. On the cloud build machine (18 November 2026, release build, Chromium):

EditHot replacementFull reload
Text in examples/social123 ms172 ms
A style121 ms165 ms
A handler108 ms195 ms
A component (examples/components' Avatar)110 ms210 ms

Most of either time is the rebuild and the 50 ms watch. A reload also loads and runs every module again; a swap loads only what changed.