Duolith docs

0070. Production adapters are one package of ports, imported like the runtime, with two runtime hooks

  • Status: Accepted (Mik, 17 Nov 2026)
  • Date: 2026-11-14
  • Decided by: production adapters agent, pending the integrator and Mik
  • Planning item: Roadmap milestone 3, "Production gaps": crash and analytics adapters, consent screen, string extraction and platform formatting, npm compatibility scanner (D33, D34)

Context

Version 1 promises crash reporting, analytics, a consent screen, translation with platform formatting, and an npm compatibility scanner (roadmap, milestone 3). The domain map says each crash or analytics provider is reached through an interface we own, so replacing one changes one folder. D33 (which provider) is still open, so the first adapters must work with no provider at all. The plan names no folder for these adapters, and OWNERS.yaml has no context for them.

Decision

  • **One package, packages/adapters (@duolith/adapters)**, owned by the Runtime context, depending only on @duolith/client's public API (tools/boundaries.yaml). It holds consent, analytics, crash reporting and translation.
  • Each adapter is a port with a reference implementation. The port is Transport<Payload>: send(payload, { leaving }). consoleTransport() prints; httpTransport(url) posts JSON to an address the app owns, by navigator.sendBeacon while the page is hidden. A provider (D33) is one more transport in one folder; no provider word appears outside it.
  • Pages import it like the runtime. import { t, track } from "@duolith/adapters" is rewritten by the web emitter to /_duolith/adapters/index.js, and the compiler carries the sources (crates/emit-web/src/adapters.rs), as it carries @duolith/client. Inside the adapters, @duolith/client points at the built runtime, so a page and the adapters share one copy of state and the router.
  • Started once, read anywhere. startConsent(), startAnalytics(), startCrashReporting() and startTranslation() run in the root layout's script; pages read consent(), track(), captureError(), t() and translation().
  • **Two hooks in @duolith/client**, the only runtime change: onScreenShown(watcher), called by the router after a screen's guards let it in, with the route's pattern, location and page module; and onActionSettled(watcher), called when an action run succeeds or fails for good, with the action's new optional name.

Alternatives considered

OptionWhy not
Put the adapters in @duolith/clientThe runtime would grow four supporting concerns and their provider seams; a provider change would touch the core context
One package per adapterConsent is read by analytics and crash reporting, and translation's locale by formatting; four packages would share one small surface
Providers' SDKs as the first adaptersD33 is open; the reference implementations must run offline and in tests
Let pages import any npm packageBare imports are not resolved by the web build yet, and the scanner (0073) exists to decide which packages could be

Consequences

  • New glossary candidates, to approve with this record: consent (what the person agreed to, by category), transport (where reports and events go), breadcrumb, catalogue (a locale's messages), message, locale.
  • The language server declares @duolith/adapters in the script view from generated declarations (dist/duolith-adapters.d.ts).
  • The glossary terms are in spec/glossary.yaml; Mik approved them on 17 Nov 2026.
  • OWNERS.yaml lists packages/adapters/** under Runtime; a separate "Production" context can be split out later without moving code.