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/:
| File | Holds |
|---|---|
src/pages/*.setup.js, *.tsx, *.css | Each 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.ts | The entry, which starts the app, and the route table |
src/theme.ts, src/theme.css | The 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.json | The 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.
| Code | Refused | What to do |
|---|---|---|
| E0200, E0201 | A hover style or :hover rule with no touch look | Add the same look under pressed: or :active |
| E0202 | An effect the shells have not built (none today: every effect is built) | See spec/effects/effects.yaml (native: true) and effects.md |
| E0204 | Two files that would be one module | Rename one |
| E0205, E0206 | A selector a phone cannot match, a property it does not draw | Use a utility, or a property the native engine draws |
| E0207, E0213 | A key or focus event, or a focus style, on something a phone never focuses | Use on:press, or put it on a field |
| E0208 | A color-mix() the build cannot work out | Mix theme tokens or literal colours |
| E0209, E0210 | An at-rule a phone cannot answer, or a declaration a @supports block would lose | Use the window prefixes (md:, dark:) |
| E0211 | A Rust module, not yet built for native | See 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.
Related
- effects.md: the platform effects and which are built on native.
- motion-and-islands.md: motion, boundaries and islands on both targets.
- execution-ladder.md: how a native build will ship bytecode once the spike says so.