Skip to content

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.

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 multiply make 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.

  • 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 useAsync hook 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 as bootstrap.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) and presentation/ (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 — fails bun run typecheck. The spec is exported by a Rust test from mocked use cases (ADR-0012) into a committed docs/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-web to skip.
  • make test/full and CI need bun. A generated project needs it too, unless created with --no-web.
  • Two steps after touching a DTO (make web/sync): Puerto never runs cargo or bun itself. 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.
  • bun test + happy-dom (@happy-dom/global-registrator) + Testing Library holds: two preload files in bunfig.toml, happy-dom first, because Testing Library builds screen from document when 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 on PATH); under Bun’s runtime it needs no Node at all.
  • TypeScript stays on 5.x: openapi-typescript declares a typescript ^5 peer, and TypeScript 7 (the native port) has no JS API for dependency-cruiser to parse with.
  • The spec test writes docs/api/openapi.json when it is missing and passes; only an existing, different file fails. Strict-on-missing would make a fresh puerto new fail make test with 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() in bootstrap.rs is the only OpenApiService::new: the server adds .server(...) on top, the test calls .spec() on it. The exported spec carries no servers entry — the frontend’s client uses baseUrl: "/api".
  • client.ts comes with the first entity, not the template. It imports schema.d.ts, which only exists after make web/sync; in the template it made a fresh puerto new fail bun 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, bool and 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 and core/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 of cargo, 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 lint checks 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, so make web/sync — the step every scaffold already needs — also runs bun run format (biome check --write with the linter off: formatting and import order only, a no-op on files that already pass make lint).
  • Screens are tested through renderScreen(ui, dependencies, path) (test-support/render.tsx, template): a Partial<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 list seriesList.
  • Form state is text. Every input but a checkbox holds a string; the conversions to and from the model are named helpers in presentation/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-null choice) in one place.
  • null in the model, optional on the wire. poem-openapi marks an Option field as not required, so openapi-typescript types it x?: T. The domain model says T | 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: parseStatus in domain/ 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-local edits 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.