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 inpackages/effects, which is what pages call; - the platform half (
CameraPlatform, ...), the few primitives each target implements: the browser's inpackages/effects/src/web/, Swift innative/ios/effects/, Kotlin innative/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
| Effect | Export | Notes |
|---|---|---|
| Sign-in | signIn, mockSignInBackend | Email and password, magic link, Apple, Google; the app picks the backend with signIn.useBackend(...) |
| Secure storage | secureStorage | get, set, remove of strings in the Keychain or Keystore |
| Key-value storage | storage | storage.value(key, initial) is a stored, reactive value |
| Push | push | Asks for the notification permission when subscribing |
| Purchases | purchases, mockStore | One-time products; the web has no store, so available is false there |
| Permissions | permissions | request(name, { reason }), with an explainer first |
| Share sheet | share | "shared", "cancelled", "copied" (where there is no sheet) or "unavailable" |
| Haptics | haptics | impact, selection, notification; nothing happens where the device cannot |
| Camera | camera | capture({ facing, maxWidth, signal }) |
| Lifecycle | lifecycle | Whether the app is in front and the device online, with onForeground and the like |
| Minimum version | minimumVersion | check({ 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.
Related
- native.md: building for iOS and Android.
- testing.md: testing pages that use effects.
- security.md: what the web build allows a page to load.