Duolith docs

0045. Native output is ReactLynx, written against an engine adapter

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: native emit domain (internal only), pending Mik's approval
  • Planning item: WP10 (native output)

Context

duolith build --target native has to turn the same Screen IR the web emitter reads into code a phone runs. The plan names Lynx as the engine. Lynx offers ReactLynx (React components over Lynx elements, run on its background thread with a first render on its main thread) and a lower level element API. Whatever the choice, the compiled views must not tie the language to it: decision 0004 confines an engine to one package, so it can be swapped without touching the compiler's output format more than it must.

Decision

  • The engine is Lynx, through ReactLynx. The emitter writes TSX that ReactLynx's build (rspeedy with pluginReactLynx) bundles into main.lynx.bundle, the file the iOS and Android shells load.
  • Views see only the adapter. packages/engine/adapter.d.ts is the contract: one primitive per element (Screen, View, Text, Button, Image, Input, TextArea, List, Scroll, Form, Toggle, Checkbox, Slider, Progress, Icon, Overlay, Group), their props, the theme and the look types. The package's JSX runtime declares no intrinsic elements, so the emitted code type-checks only if it uses the adapter; packages/engine/src implements it on Lynx elements and is the only code that imports @lynx-js/* (tools/boundaries.yaml).
  • What one source file becomes. A page, layout or component turns into <module>.setup.js (its script and expression functions, the same rewrite the web emitter does, types stripped), a .setup.d.ts, and <module>.tsx (a function component that runs setup once per instance with useSetup and draws with x.view(() => ...)). Kit parts the app uses are compiled the same way into src/kit/. src/routes.ts, src/theme.ts, src/theme.css, src/index.tsx, a tsconfig.json and duolith-native.json complete the build.
  • The runtime is shared. Signals, effects, the router's matching and guards come from @duolith/client; its native entry adds the instance (useSetup, pass, slot, track, rows) and a router that keeps a stack of screens in a state cell instead of the browser's history.
  • Styles become looks. Each style table entry becomes a list of rules, weakest first: the conditions it needs (interaction states, dark, a minimum window width, a rank for state rules) and its declarations with every token resolved, for light mode and, where a token differs, for dark. The theme's colour scheme is applied at build time (always light drops dark rules, always dark resolves to dark values). Logical sides become physical ones and the web's line-clamp recipe becomes one lineClamp. The adapter picks the rules that hold on each draw; nothing is matched by selector on the device.
  • Base looks are classes. Each primitive's own look (a button centres its content, an input has a border) is a st-<element> class in the generated theme.css, imported first, so a utility's inline style always wins over it, as the web's :where() base styles lose to utilities. <style> blocks compile to scoped classes as on the web.
  • **Dark mode is the colorScheme global prop.** The shells pass light or dark; the adapter sets duolith-dark on the app's root and chooses dark values for looks.

Alternatives considered

OptionWhy not
Lynx's element API directlyEvery element, update and list would be hand-written in the emitter; ReactLynx already diffs and schedules
Emit Lynx elements (<view>, <text>) in the viewsTies the output to Lynx; the adapter would be documentation, not a boundary
Resolve looks to CSS classes, as on the webLynx's CSS subset drops :focus-visible, :hover, :not and color-mix(); state and dark rules would need selectors it does not have
Share the script rewrite with the web emitter nowMoving it into a shared crate touches crates/emit-web, outside this work; it was duplicated in emit-native until it moved to crates/script (decision 0047)
React NativeNot the plan's engine, and its runtime is larger than the language needs

Consequences

  • The native emitter and the web emitter must be kept in step by hand until the rewrite moves to a shared crate.
  • A change to adapter.d.ts is a change to the compiler's output contract: every snapshot in packages/engine/test/snapshots/ is re-type-checked against it.
  • Swapping the engine means a new packages/engine/src, not a new emitter.