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-optimizeto 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 filespublic, max-age=31536000, immutable, everything elseno-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 testbuilds its own site and never optimizes it, so it is unchanged; the screenshot tool draws fromduolith dev, which never optimizes either.- The kit's and effects' browser tests build with
duolith buildand 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.