Duolith docs

0107. An optimized web build: minified, with hashed names and an import map

  • Status: Accepted (Mik, 16 Nov 2026): the default for duolith build, with --no-optimize to leave it out.
  • Date: 2026-11-15
  • Decided by: domain E implementer (internal only)
  • Planning item: wave 5, web production build

Context

duolith build writes readable modules under fixed names, so a host can cache them only briefly, and every visit after a deploy may mix old and new code.

Decision

duolith build (since 16 Nov 2026; --optimize before that):

  • minifies every module (oxc's printer, without comments or spaces; a module it cannot parse is kept as it is) and every stylesheet (comments out, white space collapsed, nothing that could change a selector or calc());
  • writes a copy of each one whose name carries a hash of its contents, _duolith/pages/index.3f9c2a7d10.js;
  • puts an import map first in each page's head, from every module's address to its hashed copy, so the code, the route table and the router keep their addresses while the browser fetches the hashed names; the stylesheets and preloaded modules are linked by their hashed names;
  • writes _headers (Netlify and Cloudflare Pages read it): the hashed files public, max-age=31536000, immutable, everything else no-cache.

The files under their own names stay, for what fetches an address itself instead of importing it: the push worker (registered at a fixed address), and an island downloaded afresh after a failure.

Import maps rather than rewritten imports: rewriting would change every module's text whenever any module it imports changes, so one edit would rename most of the app.

Made the default

Mik chose to make it the default once the other packages that read built files by name were checked against it. They were, on 16 Nov 2026:

  • The build report counted each runtime file twice, under its own name and its hashed copy's; it now counts each once, and reads the minified sizes that ship (crates/cli/tests/optimize_command.rs).
  • duolith test builds its own site and never optimizes it, so it is unchanged; the screenshot tool draws from duolith dev, which never optimizes either.
  • The kit's and effects' browser tests build with duolith build and now load the optimized site.

--no-optimize writes the plain build; --optimize is still accepted.

Consequences

An optimized site holds each module twice on disk; a browser downloads only the hashed copy. Browsers without import maps (before Safari 16.4) are not supported by an optimized build.