Duolith docs

0079. duolith build --report writes build-report.json and prints a summary

  • Status: Accepted (Mik, 17 Nov 2026)
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval
  • Planning item: WP13 (the build report), docs/plan/contracts.md (Build report)

Context

The build report is a contract owned by the execution ladder and read by editors, the tool server and docs (docs/plan/contracts.md), at spec/schemas/build-report.schema.json, which was not written. People need to see which rung each screen landed on and why; tools need the same as JSON.

Decision

  • **duolith build [project] --report** writes build-report.json in the output folder and prints a table: one row per screen and component (rung, bytes, bytes rung 0 saved, bindings, events, file and route), each Rust module, warnings, and totals. With --json the same report is the report field of the command's JSON answer.
  • **Its shape is spec/schemas/build-report.schema.json, version 1:** target; the bytecode gate (decision 0076); screens (pages, layouts, the not-found screen) and components (the project's and the kit parts it uses), each with kind, source, route, module, rung (0 or 1), script (none, source, bytecode), reason (why not rung 0), bytes, savedBytes, bindings, events, effects, modules, warnings; modules (each Rust module: rung 3, WebAssembly and loader bytes, used by); and totals. camelCase, as every JSON the framework writes.
  • Counted as bindings: bound text, bound attributes and props, class: conditions, <show> conditions, lists, and bind: pairs; events apart. Effects are imports of framework packages other than @duolith/client and @duolith/kit (D21: one scope). Warnings are the ladder's (a constant list too long to write out); the analyzer has no warnings yet.
  • pnpm check builds every example with --report and validates each report against the schema (packages/modules/test/build-report.test.ts).

Alternatives considered

OptionWhy not
Write the report outside the output folderTwo places to clean; the output folder is what a build produced
A separate duolith report commandBuilds the project twice to know sizes
Report gzip sizesA compression library for one number; raw sizes compare the same way

Consequences

  • The schema is a contract: changing a field is a new version and a decision.
  • The report sits beside the site; a host serves it like any file, and it holds nothing private (file names and sizes).