Duolith docs

0050. Effects are imported by name from @duolith/effects, and each contract has an app-facing half and a platform half

  • Status: Accepted (Mik, 17 Nov 2026)
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval
  • Planning item: WP11 (platform effects)

Context

Version 1 has eleven platform effects (sign-in, secure storage, key-value storage, push, purchases, permissions, share, haptics, camera, lifecycle, minimum version). Each must be reactive like state, must work on the web today, and must later be implemented in Swift and Kotlin against the same contract (spec/effects/<effect>.ts, contract "Platform effect interface"). Writing the reactive behaviour three times (the session, the explainer, ownership, de-duplicated listeners) would make the three targets drift.

Decision

One module. A page writes import { camera, signIn } from "@duolith/effects". The web emitter rewrites the import to /_duolith/effects/index.js, and the build ships the effects' web code, from packages/effects/src with types removed (as the runtime is shipped), only when some page or component imports @duolith/effects. The effects import the runtime as @duolith/client, pointed at the runtime the build ships.

Two halves per contract. Each spec/effects/<effect>.ts declares:

  • the app-facing half (Camera, SignIn, ...): what pages call. It is written once in TypeScript (packages/effects/src/<effect>.ts, create<Effect>(platform)) on top of StateCell, so every value it exposes is reactive;
  • the platform half (CameraPlatform, SignInPlatform, ...): a few primitives each target implements: packages/effects/src/web/ for the web, native/ios/effects/ and native/android/effects/ for Swift and Kotlin (stubs until the shells exist).

Effects that need another effect take it, rather than the platform doing it: camera and push ask through permissions, so permissions.status stays true; sign-in keeps who is signed in in key-value storage (known synchronously at start, so guards can read it, and shared by every window) and the tokens in secure storage; lifecycle's online is the runtime's network.online.

Ways to sign in resolve true/false and put the failure in session.error instead of rejecting, so a press handler needs no try. Other effects reject with an EffectError whose code is in the diagnostics catalogue (E0222 to E0230).

Alternatives considered

OptionWhy not
Effects in @duolith/clientThe runtime would carry every effect's code to every app, and client may not depend on effects implementations
A module per effect (@duolith/effects/camera)Eleven specifiers to rewrite and document; one module with named imports is what pages already do for the kit
The whole effect per platform (reactive half in Swift and Kotlin too)Three copies of the session, the explainer and ownership logic, which would drift
Effects that throw for every failureSign-in failures are expected and shown on the page; a rejected promise in a press handler is an uncaught error

Consequences

packages/effects depends on @duolith/client (allowed by tools/boundaries.yaml). spec/effects is a TypeScript project of its own that packages/effects references, so the implementations are checked against the contracts by tsc -b. The native shells (WP10) must run the TypeScript app-facing half with their own platforms bound in. The language server does not yet declare @duolith/effects for the script view.