Duolith docs

0141. Links reach the router through the shell, other sites open in the system, and a dev server reloads the app on a phone

  • Status: Accepted (Mik, 16 Nov 2026), with sms: kept and plain http allowed in debug builds only.
  • Date: 2026-11-14
  • Decided by: Mik (the adapter contract additions, the preview app); integrator (built on the recommendation meanwhile)
  • Planning item: none

Context

On a phone, a link to the app (a universal link, an App Link, the app's own scheme) must open the right screen whether the app was closed or running, and sign-in's magic links need the whole address. An href to another site did nothing on native (the engine had no way to leave the app). The environment values the web build sets as __duolith_environment were never set on native. And trying a change on a phone meant rebuilding the app.

Decision

  • The shell hands links over whole. Android (intent filters with autoVerify, a singleTask activity) and iOS (scene URL contexts and web-browsing user activities) pass only links on the manifest's domains or in its scheme (decision 0140), as the link global prop when the link started the app and as the duolithLink global event while it runs.
  • The adapter contract grows (packages/engine/adapter.d.ts): initialLink(), listenForLinks(listener), shellEnvironment() and openExternal(url). @duolith/client/native routes each link to its path (linkPath: an https link's path, query and fragment; a scheme link's host and path) and exposes onLink(listener) and lastLink() for code that needs the address, such as sign-in. This is the contract agreed with sign-in: it reads the magic link from onLink/lastLink, and its return address is an https link on a link domain, or the app's scheme.
  • Other sites open in the system: an href with a scheme calls openExternal, which is openUrl on the DuolithShell module (Android ACTION_VIEW with CATEGORY_BROWSABLE, iOS UIApplication.open). Only http, https, mailto, tel and sms are opened, checked in the engine and again in each shell: javascript: must never run, file: stops an Android app, and an app's own scheme is a path in it. An href written as text, or as one string in braces, with another scheme fails the build (E0170); sms: joins the link addresses on every target so the lists are one.
  • Environment values: the native build writes the DUOLITH_PUBLIC_* variables of its environment, by their camel-case names, into the app's file (duolith-app.json); the shell passes them as the environment global prop, and the client sets __duolith_environment from it.
  • **duolith dev --target android|ios [--host]** builds, bundles and serves /main.lynx.bundle, /duolith-app.json and a WebSocket at /_duolith/socket that sends {"type":"reload"} after each rebuild (or {"type":"error"}), from the Duolith command with no extra dependency (a small RFC 6455 server). A debug build of the shell given the address (-Pduolith.devServer, the duolithDevServer extra or launch argument) loads from it and reloads the bundle on the message; release builds never do. The socket takes a connection with no Origin (a shell) or the server's own; each write has a time limit, and none is made while the served state is locked. A link that arrives before the app's file is fetched waits for it; the newest such link is the one the app opens on. With --host it listens on the network and prints a QR code of the address.
  • The preview app (native/preview-app) is the shell with a scan screen and no app of its own, as dev.duolith.preview: it reuses the shell's code and resources, and opens the scanned address. The dev server's page offers duolith-preview://open?server=<address> for phones whose own camera scanned the code; since any page can send that link, the preview app asks before it opens the app a link names.

Alternatives considered

OptionWhy not
The shell navigates itself (passing only a path)Sign-in needs the whole address; the router already knows the routes
A DuolithShell.onLink callback registered from the bundleA global prop and a global event are how the shells already talk to the engine (back, effects), and they reach the bundle before its first frame
Lynx's own dev tools and the Lynx Explorer app for previewsExplorer loads a bundle URL but knows nothing of Duolith's effects and shell modules; the preview app is the real shell
A third-party WebSocket or QR crate stack for the dev serverKept to qrcode and sha1_smol; the server is a few dozen lines and tested with a headless client

Consequences

  • The engine's adapter and the client gained exports; the in-browser tests (native-shell-in-browser.test.ts) drive them through a stand-in DuolithShell module.
  • The preview app cannot carry an app's name, icon, link domains or unusual permissions; those need the shell's own debug build.
  • Mik to confirm: the adapter additions, the duolithLink and link names, plain http to the computer in debug builds (cleartext allowed only in debug builds on Android, the shell's and the preview app's; the iOS preview app allows local networking always and arbitrary loads only in its Debug build), and publishing the preview app to the stores later.