0013 · Web frontend: React + daisyUI on Bun, structure generated by Puerto, wire types from OpenAPI
Status: Accepted (2026-10-11 — built in 9.0 – 9.3). Spec: PLAN.md § Phase 9.
Context
Section titled “Context”Puerto generates the backend of a Rails-style scaffold but no screen. The frontend must (a) leave
a working CRUD per entity, (b) give the structure to keep developing by hand, (c) follow the same
Dependency Rule as the backend — the layout of nexe-document’s document-workspace — and (d) stay
cheap for Puerto to keep green in the compile matrix.
Options weighed:
- Leptos / Dioxus (WASM). One language, but the DTOs are poem-openapi
Objects, not serde, so sharing types is not free; a wasm target and trunk multiplymake test/full; both frameworks break their API often enough to keep breaking the templates. - HTMX + Askama. No build step, but HTML endpoints sit next to the JSON API inside
presentation(API First is lost) and the HTML is checked by no contract. - TypeScript. Bun enters the toolchain. Everything else is in its favour: the OpenAPI spec becomes the contract between the two halves, and agents write TS/React well.
A first draft copied document-workspace’s four layers wholesale, one use case class per CRUD
action. Read against its own code (list-queue-tasks.ts: log, call the repository, return), a
frontend CRUD use case only delegates — the server owns validation — so that layer would be
generated empty five times per entity.
Decision
Section titled “Decision”- React 19 + daisyUI 5 (Tailwind v4). daisyUI is CSS classes only: no JS, no runtime
dependency, works with native
<dialog>and<form>, which is all a CRUD needs, and the user can swap it. shadcn was rejected for its dependency weight; Preact / Svelte for the friction of a compat layer or a second mental model. - No TanStack. wouter for routing, a small
useAsynchook for server state. Without file-based routing the route table is a generated file (core/generated/routes.tsx), so adding an entity never patches user code — the same move asbootstrap.rs. - Bun as runtime, package manager and test runner (
bun test): one binary to pin and install in CI, and the fastest install for a matrix that generates many projects. - No layer without logic. The generated CRUD is
domain/(types, error, repository port),infrastructure/(HTTP adapter) andpresentation/(containers call the port, views take props).application/ships empty with a README: a use case is written by hand when there is a rule or an orchestration to hold, and Puerto never generates one. What the hexagon buys on the frontend is the port — screens tested against a fake repository, no network — plus one composition root (core/generated/dependencies.ts) and the Dependency Rule checked by dependency-cruiser. - Puerto generates the structure itself, from puerto.toml and its Tera templates. It is not delegated to openapi-generator: that tool knows nothing of layers, and bending its mustache templates into them would be a second template system to maintain.
- openapi-typescript generates only the wire types (
infrastructure/http/schema.d.ts), used through openapi-fetch by the generated adapters. A DTO changed in Rust — including by hand — failsbun run typecheck. The spec is exported by a Rust test from mocked use cases (ADR-0012) into a committeddocs/api/openapi.json, so a contract change shows in the diff. - No client-side copy of domain rules. The 422 code from the server is shown as-is. Sharing the rules themselves (the Rust domain compiled to WASM) is deferred to Phase 10, triggered by the first non-trivial validation rule — today puerto.toml already keeps both sides consistent at generation time.
- Optional, default on:
[project] web = true,puerto new --no-webto skip.
Consequences
Section titled “Consequences”make test/fulland CI needbun. A generated project needs it too, unless created with--no-web.- Two steps after touching a DTO (
make web/sync): Puerto never runscargoorbunitself. Until the sync, the frontend does not typecheck — deliberate, it is the drift signal. - A container that grows logic is the cue to move it into
application/; nothing enforces it beyond review and the Dependency Rule. - Accessibility beyond native elements (combobox, focus traps) is the user’s to add — daisyUI ships none.
bun test+ happy-dom + testing-library is verified in piece 9.0; if it does not hold, Vitest (run by Bun) replaces it and this ADR records why.- Puerto now owns templates in two languages; the snapshot files cover both.
Verified in 9.0
Section titled “Verified in 9.0”bun test+ happy-dom (@happy-dom/global-registrator) + Testing Library holds: two preload files inbunfig.toml, happy-dom first, because Testing Library buildsscreenfromdocumentwhen it is imported. Vitest is not needed.- The tool scripts run as
bun --bun <tool>. dependency-cruiser refuses an odd-numbered Node release (it found Node 25 onPATH); under Bun’s runtime it needs no Node at all. - TypeScript stays on 5.x:
openapi-typescriptdeclares atypescript ^5peer, and TypeScript 7 (the native port) has no JS API for dependency-cruiser to parse with.
Decided in 9.1
Section titled “Decided in 9.1”- The spec test writes
docs/api/openapi.jsonwhen it is missing and passes; only an existing, different file fails. Strict-on-missing would make a freshpuerto newfailmake testwith nothing to sync. The compile matrix runs the test twice (write, then compare), so the strict path and the determinism of the export stay covered. openapi_service()inbootstrap.rsis the onlyOpenApiService::new: the server adds.server(...)on top, the test calls.spec()on it. The exported spec carries noserversentry — the frontend’s client usesbaseUrl: "/api".
Decided in 9.2
Section titled “Decided in 9.2”client.tscomes with the first entity, not the template. It importsschema.d.ts, which only exists aftermake web/sync; in the template it made a freshpuerto newfailbun run typecheck. The first scaffold needs a sync anyway. Written once, never overwritten.- Entities whose fields the frontend generator did not handle yet got no slice at all (9.2
covers
String,Uuid,i64,f64,booland non-enum VOs over them). The alternative — a slice that does not typecheck — would turn every intermediate project red; one predicate (web::has_web_slice) keeps scaffold, the guard, the drift check andcore/generated/*agreeing on who has screens. Lifted in 9.3. - The bun checks run in every web scenario of the matrix, not only
web_crud: a few seconds each (install from a warm cache included) against minutes ofcargo, and every scenario that later gains a slice is then checked by its own frontend. - Generated TypeScript is emitted Biome-clean, not formatted afterwards:
bun run lintchecks it in the matrix before any formatting. Puerto never runs bun, so it emulates the two rules that depend on names — import order (web::organize_imports: sources by distance,/before other characters, specifiers case-insensitively) and wrapping at 100 columns where a line’s length depends on the entity (routes,navEntries, wrapped imports). Templates avoid the rest by shape. Formatting cannot be emulated for every name, somake web/sync— the step every scaffold already needs — also runsbun run format(biome check --writewith the linter off: formatting and import order only, a no-op on files that already passmake lint). - Screens are tested through
renderScreen(ui, dependencies, path)(test-support/render.tsx, template): aPartial<Dependencies>— a screen test names only the adapters it uses, so adding an entity does not touch other entities’ tests — and a recording wouter memory location to assert navigation.test-support/may not reach an adapter, and only test files may import it (dependency-cruiser). - Variables named after the entity avoid TypeScript’s reserved words (
Case→caseItem) and the templates’ own locals; an uncountable plural (series) names its listseriesList.
Decided in 9.3
Section titled “Decided in 9.3”- Form state is text. Every input but a checkbox holds a
string; the conversions to and from the model are named helpers inpresentation/shared/forms.ts(template, tested), not inline expressions — the generated view stays readable and a user can change one rule (the list separator, the empty-means-nullchoice) in one place. nullin the model, optional on the wire. poem-openapi marks anOptionfield as notrequired, so openapi-typescript types itx?: T. The domain model saysT | null— what the screens branch on — and the adapter converts at the boundary.Option<bool>is a three-way<select>: a checkbox cannot say “not set”.- Enum VOs are narrowed, not cast:
parseStatusindomain/rejects an unknown value with the code the backend uses for it ({entity}.invalid_{vo}), so an API that grew a variant the frontend does not know shows a code instead of a silent wrong value. datetime-localedits local time to the minute; the model keeps ISO 8601 instants. The Object Mother uses a whole-minute UTC instant so the edit round-trip is exact.