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 edit | What the page does |
|---|---|
| A page's or layout's markup, script or handlers | Its 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 styles | The styles are replaced. No screen is built again. |
| A component | Every 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 layout | That 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 file | The page reloads, and the terminal and the console say why (E0571). |
| Anything, so that it no longer builds or type-checks | The 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
- The watcher looks at the project's files every 50 ms and rebuilds when one changed. The runtime is compiled once per run.
- 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. - 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. - In the browser,
packages/client/src/web/hotimports 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. - 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.1only. - It answers only its own pages. A request whose
Hostis notlocalhostor an address written as numbers with the server's port, whoseOriginis 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 saysCross-Origin-Resource-Policy: same-origin,X-Content-Type-Options: nosniffandX-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, nonew Function, no inline handlers. Modules load by address, and the error overlay sets its message as text. - Nothing of it ships:
duolith buildwrites 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):
| Edit | Hot replacement | Full reload |
|---|---|---|
Text in examples/social | 123 ms | 172 ms |
| A style | 121 ms | 165 ms |
| A handler | 108 ms | 195 ms |
A component (examples/components' Avatar) | 110 ms | 210 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.