Duolith docs

Native builds

The same pages that make the web app make the iOS and Android apps. On a phone there is no web view: pages compile to ReactLynx, and the Lynx engine draws them with the platform's own views (decision 0045). This guide covers building, running, and what a native build refuses.

Building

duolith build my-app --target native           # writes my-app/dist-native
node packages/engine/scripts/bundle.ts my-app/dist-native   # bundles it into main.lynx.bundle

A native build makes every check a web build makes first (structure, then types), and stops there if anything fails. Then it checks what a phone cannot honour, and only then writes dist-native/:

FileHolds
src/pages/*.setup.js, *.tsx, *.cssEach page's setup (its script), view and styles, as ReactLynx modules
src/components/, src/kit/The same for the project's components and the kit parts it uses
src/index.tsx, src/routes.tsThe entry, which starts the app, and the route table
src/theme.ts, src/theme.cssThe theme's tokens, light and dark
native/When the app imports effects: ios/Info.permissions.plist, android/AndroidManifest.permissions.xml and effects.json (decision 0051)
public/The project's public/ files
duolith-native.jsonThe manifest that marks the folder as a native build

The two shells in native/ load main.lynx.bundle:

# Android: needs the Android SDK (ANDROID_HOME) and JDK 17 or later
cd native/android && ./gradlew assembleDebug -Pduolith.build=../../my-app/dist-native

# iOS: needs a Mac with Xcode, XcodeGen and CocoaPods
cd native/ios/App && xcodegen && pod install && open DuolithShell.xcworkspace

native/android/README.md and native/ios/README.md have the details, and say what has been checked on which machine.

Trying it without a phone

The engine's tests run the native output in Lynx for Web, in Chromium, with a stand-in for the shell's module (packages/engine/test/). That is how every native feature is checked in CI: the same bundle, the same engine, drawn by the browser instead of UIKit or Android views. It shows layout, navigation, motion, overlays and effects calls; it cannot show how a screen feels, or what VoiceOver and TalkBack read.

native/DEVICE-CHECKLIST.md lists everything only a real phone can confirm. Go through it before a release.

What works the same

Everything in the language: elements, flow, components, binding, events, styling and themes (dark mode follows the system through the colorScheme global prop), the kit, navigation with push and pop transitions and the system back button, data (state that loads, actions, streams, the offline queue), motion presets and the default motion of shows and lists, boundaries with skeletons and fallbacks, and islands (built at once on a phone, since the bundle holds every component's code). examples/FEATURES.md has a native section listing each with the test that checks it.

What a native build refuses

A phone cannot honour some things a browser can, and the build says so with an error rather than drop them (decision 0049). Each error names the line and a fix; duolith explain <code> says more.

CodeRefusedWhat to do
E0200, E0201A hover style or :hover rule with no touch lookAdd the same look under pressed: or :active
E0202An effect the shells have not built (none today: every effect is built)See spec/effects/effects.yaml (native: true) and effects.md
E0204Two files that would be one moduleRename one
E0205, E0206A selector a phone cannot match, a property it does not drawUse a utility, or a property the native engine draws
E0207, E0213A key or focus event, or a focus style, on something a phone never focusesUse on:press, or put it on a field
E0208A color-mix() the build cannot work outMix theme tokens or literal colours
E0209, E0210An at-rule a phone cannot answer, or a declaration a @supports block would loseUse the window prefixes (md:, dark:)
E0211A Rust module, not yet built for nativeSee rust-modules.md

The conformance fixtures in spec/conformance show each refusal next to the web output of the same page (the "Native refusals" section of its README).

Permissions

An app that imports an effect needing a permission gets its declarations written for it: the camera's NSCameraUsageDescription and android.permission.CAMERA, push's notification permission, and so on. The usage text iOS shows comes from spec/effects/effects.yaml; replace it in permissions.yaml at the app's root. A name there that is not a permission is E0221.