Duolith docs

0053. The production adapters run on native with the shell as their host

  • Status: Accepted (Mik, 16 Nov 2026). The outbox limit is an option, mostWaiting; phones keep writing times without zone names.
  • Date: 2026-11-14
  • Decided by: native render domain (wave 5), approved by Mik on 16 Nov 2026
  • Planning item: none (wave 5, native rendering)

Context

Crash reporting, analytics, consent and translation (decisions 0070-0074) were written for the browser: localStorage, sendBeacon, the document's visibility, the window's error events, navigator.languages and catalogues fetched from /_duolith/locales/. A native build that imported them stopped with E0203. A phone has none of those, and PrimJS, the engine that runs the app's script on iOS and Android, has no Intl.

Decision

The adapters read the platform through one host (packages/adapters/src/host.ts). The web's is the browser, as before. The native entry (packages/adapters/src/native/index.ts, which the native bundle maps @duolith/adapters to) puts the shell in its place before any page runs:

  • Storage is the shell's key-value storage, through the storage effect's platform half. It keeps consent, the chosen locale and the outbox across launches.
  • Leaving is the app going to the background (the lifecycle effect's phase event).
  • Sends go through an outbox. A phone has no beacon and can stop the app in the background at any moment. So httpTransport keeps each payload in storage first and takes it out once a request for it succeeds (a 4xx drops it). It sends oldest first, stops at the first failure and tries again later (30 s, doubling to 15 min), keeps at most 100 payloads (or the transport's mostWaiting) and 512 KiB, and sends what is left when it next starts. Each payload is kept with an id, so it is taken out by identity, and with the consent category it was sent under, which is checked again when it goes: refusing a category drops what waits under it. The web is unchanged: one request, or a beacon when leaving.
  • Crashes come from the shell's uncaught handler. Lynx reports what the script throws to the shell (Android's LynxViewClient.onReceivedError, iOS's LynxViewLifecycle). The shell keeps each crash in a file of its own (the newest 20), sends it to the bundle as the duolithCrash global event, and answers DuolithShell.takeCrashes() with the crashes kept, forgetting them. Crash reporting takes them when it starts and again each time the event comes, so a crash is reported once, whether the bundle heard it or only found it on the next start. Frames are sent as they ran. They are mapped offline with the bundle's kept source map (packages/engine/scripts/map-frames.ts), because a phone has no map to fetch.
  • Languages and catalogues. The shells put the phone's languages in the locales global prop. The native build writes the checked catalogues into the bundle (src/locales.ts calls provideCatalogues), so t() needs no request.
  • **A compact Intl** (intl-fallback.ts) formats where the engine has none, from CLDR's data as ICU writes it: intl.ts uses the platform's Intl wherever the engine has one. The native entry hands it the compact one; the web build does not ship it. The tests run the fallback itself against ICU for 69 locales.
    • The bundle step reads each locale the app has a catalogue for out of Node's ICU (packages/adapters/scripts/intl-data.ts; the manifest's locales). That covers its digits, signs, grouping and number patterns, every currency's symbol, its calendar's month and weekday names, its date and time patterns, and its relative-time phrases. American English is built in.
    • Every pattern is checked against ICU's output for dates that tell each field apart, and only the ones the fallback cannot make from others are kept: about 11 KB a locale.
    • Plural and ordinal rules are make-plural's (CLDR 48, the same as Node 22's and 24's ICU), checked against ICU for each locale.
    • Numbers cover decimal, percent and currency (symbol or code); fraction and significant digits, minimum integer digits, grouping and sign display. They are rounded half away from zero on the number's decimal digits, as ICU rounds.
    • Dates and times cover dateStyle and timeStyle, and any mix of weekday, year, month, day, hour, minute and second, with hour12 or hourCycle. They are written in the locale's own calendar (Gregorian, Buddhist or Persian), in the device's zone, UTC or a fixed offset. A zone is written as its offset (GMT+1), except UTC, because a phone without Intl has no zone names.
    • Relative time is the locale's own phrases, as numeric: "auto" writes them.
    • The bundle fails, with the reason, for a locale it cannot write exactly: another calendar, a field it does not write, or a plural rule make-plural and ICU disagree on. An option outside the list is reported once on the console and left out. A locale the app names without a catalogue is formatted as its language's, or as English, and that is reported once.
  • On native, presses are not heard for breadcrumbs, Global Privacy Control is off, and lang and dir are not set on a root, since the shell sets the direction.

Alternatives considered

OptionWhy not
formatjs's Intl polyfillsHundreds of kilobytes of locale data in every bundle, for a fallback most apps use for a few formats
Hand-written rules for the common languagesIt wrote wrong plurals, ordinals, dates and relative times outside English, without saying so
Ship ICU's data for every localeMegabytes in the app, where the app's own catalogues already say which locales it shows
Send native crashes from the shell itselfTwo crash pipelines: breadcrumbs, consent and the screen live in the bundle
Fetch catalogues on native as on the webThe first screen would wait on the network, and offline launches would show keys
Map frames on the phoneIt would ship the map in the app; the map is for whoever reads the report

Consequences

  • On a phone, a zone other than UTC is written by its offset, where ICU writes its name ("GMT-8" rather than "PST" or "Pacific Standard Time"), for timeStyle: "long" and "full".
  • The formats come from the ICU of the Node that bundles the app, so a newer Node can change what a new bundle writes, as a newer browser changes what the web writes.
  • Payloads wait in the phone's storage until they are delivered.
  • What only a device shows is in native/DEVICE-CHECKLIST.md:
    • PrimJS without Intl;
    • the real uncaught handlers and what their errors carry;
    • the line offset of PrimJS's frames.

Mik's answers (16 Nov 2026)

  • A phone does not write zone names (timeStyle: "long"), so the bundle carries no zone data.
  • The outbox's limit is an option: httpTransport(url, { mostWaiting }), a whole number of at least 1 (100 by default); anything else throws a RangeError when the transport is made.