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, bynavigator.sendBeaconwhile 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/clientpoints 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()andstartTranslation()run in the root layout's script; pages readconsent(),track(),captureError(),t()andtranslation(). - **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'spattern, location and page module; andonActionSettled(watcher), called when an action run succeeds or fails for good, with the action's new optionalname.
Alternatives considered
| Option | Why not |
|---|---|
Put the adapters in @duolith/client | The runtime would grow four supporting concerns and their provider seams; a provider change would touch the core context |
| One package per adapter | Consent 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 adapters | D33 is open; the reference implementations must run offline and in tests |
| Let pages import any npm package | Bare 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/adaptersin 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.yamllistspackages/adapters/**under Runtime; a separate "Production" context can be split out later without moving code.