Duolith docs

Platform effects

An effect is something the device does for the app: sign in, keep a secret, ask for a permission, open the share sheet, buzz, take a photo. A page imports effects from @duolith/effects and uses them like any other value; everything an effect exposes is reactive, so markup that reads haptics.available or purchases.owns("pro") follows it.

import { haptics, share } from "@duolith/effects";

async function shareLake() {
  const outcome = await share({ title: "Lake Bled", url: "https://example.com/lake-bled" });
  if (outcome === "copied") toast("Link copied", { tone: "success" });
}

examples/effects has a screen for every effect. The effects reference lists each export and the permissions it needs, generated from spec/effects/effects.yaml.

Two halves

Each effect has one contract in spec/effects/ with two halves:

  • the app-facing half (Camera, Purchases, ...), written once in TypeScript in packages/effects, which is what pages call;
  • the platform half (CameraPlatform, ...), the few primitives each target implements: the browser's in packages/effects/src/web/, Swift in native/ios/effects/, Kotlin in native/android/effects/.

So an effect behaves the same on every target, and only the primitives differ. On a phone the halves meet over one JSON bridge, the DuolithEffects Lynx module (decision 0048).

The effects

EffectExportNotes
Sign-insignIn, mockSignInBackendEmail and password, magic link, Apple, Google; the app picks the backend with signIn.useBackend(...)
Secure storagesecureStorageget, set, remove of strings in the Keychain or Keystore
Key-value storagestoragestorage.value(key, initial) is a stored, reactive value
PushpushAsks for the notification permission when subscribing
Purchasespurchases, mockStoreOne-time products; the web has no store, so available is false there
Permissionspermissionsrequest(name, { reason }), with an explainer first
Share sheetshare"shared", "cancelled", "copied" (where there is no sheet) or "unavailable"
Hapticshapticsimpact, selection, notification; nothing happens where the device cannot
Cameracameracapture({ facing, maxWidth, signal })
LifecyclelifecycleWhether the app is in front and the device online, with onForeground and the like
Minimum versionminimumVersioncheck({ load }) asks the server for the oldest version it supports; status becomes "update-required"

Importing a name that is not an effect is E0220.

Asking for a permission

Ask with a reason, and the app's own explainer shows before the system prompt, once:

const status = await permissions.request("camera", { reason: "Take a photo for your profile. Nothing is uploaded." });
if (status !== "granted") return;

While a reason waits for an answer, permissions.explaining holds it; the layout shows a dialog for it and answers with permissions.answer(true) to go on to the system prompt, or false to stop. Nothing is asked when the answer is already known. examples/effects/components/Explainer.duo is one such dialog.

Declarations on native

A native build writes the declarations an app's effects need (decision 0051): the camera's NSCameraUsageDescription and android.permission.CAMERA, push's notification permission, and so on, into dist-native/native/. The usage text iOS shows comes from effects.yaml; replace it in permissions.yaml at the app's root:

# permissions.yaml
camera: Take a photo of the receipt you are claiming.

A name there that is not a permission is E0221.

What is built where

Every effect works on the web, and every effect in spec/effects/effects.yaml is marked native: true, so each one is built on iOS and Android too. A native build that imports an effect without native: true is refused with E0202, rather than ship web code that cannot work on a phone. See native.md.

Failures

An effect that fails throws an EffectError with a code: E0222 (not available on this platform), E0223 (permission not given), E0224 to E0226 (sign-in), E0227 (a secure value cannot be read), E0228 (push), E0229 (purchase), E0230 (photo). duolith explain E0223 says what each means. Catch them where the user can be told:

try {
  photo = await camera.capture({ facing: "environment" });
} catch (failure) {
  problem = (failure as Error).message;
}

Mocks

mockSignInBackend() is a sign-in backend with no network, with an outbox for magic links; mockStore(products) is a store that sells them. Pass them to signIn.useBackend(...) and purchases.useStore(...) in examples and tests, never in a release.