Duolith docs

0048. On native, effects cross one JSON bridge, and an effect not built for native fails the build

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

Context

Decision 0050 splits each effect into an app-facing half in TypeScript and a platform half per platform. The native build bundled @duolith/effects' web code, so on a device storage meant localStorage and share meant navigator.share. Nothing reached the Kotlin and Swift halves in native/*/effects, and --target native wrote no permission declarations.

Decision

  • One module, two methods. Each shell registers a Lynx native module, DuolithEffects, with call(effect, method, argsJson) for what the platform answers at once and callAsync(effect, method, argsJson, done) for what waits on the user or the system. Arguments are the contract's own, as a JSON array. An answer is {"value": …} or {"error": {"code", "message"}} with a catalogue code. What a platform reports by itself (storage changed elsewhere, the app went to the background) arrives as the duolithEffect global event, with {effect, event, value}.
  • One bridge per platform. EffectsBridge (native/android/effects/ Bridge.kt, native/ios/effects/Bridge.swift) holds the dispatch table. The shell module only forwards to it.
  • The native bundle swaps the platform halves only. The engine's bundle aliases @duolith/effects to packages/effects/src/native, which builds the same app-facing halves with platforms that call the bridge (callPlatform, callPlatformLater and onPlatformEvent from @duolith/engine). No web platform code is bundled.
  • Built for native is in the catalogue. spec/effects/effects.yaml marks with native: true each effect that has both halves on both platforms. Importing any other effect in a native build is E0202, an error naming the effect and listing those that are built. Nothing falls back to the web code.
  • Declarations. --target native runs the same effects analysis as the web build and writes native/android/AndroidManifest.permissions.xml and native/ios/Info.permissions.plist into the build. Gradle merges the first through the debug and release source sets. The iOS project merges the second into the built Info.plist with PlistBuddy.
  • The first-screen render does nothing. ReactLynx renders the first screen on Lynx's main thread, which has no native modules. There the bridge answers null, a promise that never settles, and no events. The background thread's render replaces it.

Consequences

  • Seven effects work on native: storage, secureStorage, permissions, share, haptics, lifecycle and minimumVersion. signIn, push, purchases and camera fail the native build until their halves are written.
  • Lynx for Web checks the TypeScript side end to end with a fake module (packages/engine/test/native-effects-in-browser.test.ts). The Kotlin halves compile in the Android build. The Swift halves have not been compiled: there was no Swift toolchain. Device behaviour is in native/DEVICE-CHECKLIST.md.
  • permissions.request("camera") without the camera effect declares no camera permission, so Android answers "denied". This follows decision 0051: declarations come from the effects an app imports.